place_call
Place one real phone call FROM the selected outbound number (the authenticated user’s verified personal number by default) to accomplish a specific objective (book a table, ask a question, chase an order). A real-time voice agent handles the call, including automated phone menus and hold queues. Its default opening says who it is calling for and states the call's purpose. Use get_agent and update_agent for number settings and inbound greeting/instructions. Outbound greeting and system instructions are read-only through MCP; use objective and context for call-specific facts. Changes apply directly to new calls. Call facts are added automatically. The recording disclosure belongs in the first spoken turn that advances the objective, whether asking a question, making a request, or giving task-related details. Brief introductory chatter or an acknowledgment of a request to hold may come first. State that recording is happening in the selected call language; no fixed wording is required. Returns immediately with a call_id and resolved locale, language, and voice; the call proceeds in the background and typically takes 2–5 minutes — poll get_call (pass wait_seconds to long-poll) until the status is terminal. The response includes a listen_url: a private web link where the user can hear the call live, watch the transcript, and stop the call — offer it to the user. Calls in Central America, Europe, North America, and South America, subject to route availability; never for emergencies. Calls involving a non-US/Canadian number require a paid plan from the first call. Rates vary by caller ID and destination; the response includes an estimated provider cost for one minute, including per-call costs. This estimate is not a final charge. Paid usage follows telephone, AI and any lookup costs, including unsuccessful attempts, and can update after the call. Calls can be placed at any time of day, any day of the week, and the user is responsible for fair use; one call runs at a time per account and volume is governed by the plan — rejections return a machine-readable error code with retry guidance, so relay the message to the user rather than retrying blindly. The voice agent receives the name of the person the call is for: if the account has no name on file the call is rejected with user_name_required — ask your user what name to give (e.g. "Sam" or "Sam at Acme"), then call again with it in user_name; it is saved to the account for future calls.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Destination phone number in E.164, e.g. +14155551234. Supported: Central America, Europe, North America, and South America (Telnyx regions; Caribbean excluded). Destination country codes: BZ, CR, SV, GT, HN, NI, PA, AX, AL, AD, AT, BE, BA, BG, HR, CY, CZ, DK, EE, FO, FI, FR, DE, GI, GR, GL, GG, HU, IS, IE, IM, IT, JE, LV, LI, LT, LU, MK, MT, MC, ME, NL, NO, PL, PT, XK, RO, RU, SM, RS, SK, SI, ES, SJ, SE, CH, UA, GB, VA, US, CA, MX, PM, AR, BO, BR, CL, CO, EC, FK, GF, GY, PY, PE, SR, UY, VE. | |
| locale | No | Language the voice agent should use for the entire call. Choose one of the advertised BCP 47 tags for the active speech provider. The objective and context may be written in another language. Defaults to the selected source’s published preference in the phone workspace, otherwise the supported account preference, then English. Uses an available saved voice or the provider default. Applies only to this call; the selected language stays fixed for the entire call. Unsupported locales return unsupported_language before dialing | |
| context | No | Extra facts the agent may reveal if asked (e.g. party preferences, callback number policy). | |
| timezone | Yes | The callee’s local IANA timezone, for example America/Chicago or Europe/London. Determine it from reliable context or ask; do not guess from a phone number. | |
| number_id | No | Account phone assignment ID from list_phone_numbers; omit to use the account default. | |
| objective | Yes | What the call should achieve, with all needed specifics and acceptable fallbacks. E.g. "Book a table for 2 tonight at 19:30 under 'Iddo'. Acceptable window 19:00–20:30." | |
| user_name | No | The user name supplied to the voice agent for the call, e.g. "Sam" or "Sam at Acme". The default introduction uses the saved name when explaining who the call is for; a custom introduction follows the published outbound agent instructions. Only needed when place_call returned user_name_required: ask your user for it, do not invent one. Saved to the account for future calls; a later value updates the saved name. | |
| request_id | No | Optional retry key. Reuse the same UUID and arguments after a lost response to avoid a second call. | |
| callee_name | No | Who is being called, e.g. "Zuni Café". Improves the conversation and the logs. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||