calls_make
Place an outbound AUDIO/VOICE phone call via Twilio (PSTN) or Telegram (MTProto 1:1 call). Use this any time the user asks to 'call', 'ring', 'phone', 'dial', or have a spoken conversation. Do NOT use messages.send when the user asks to call someone — a call is real-time voice, not a text message. You conduct the conversation as the voice agent using the provided greeting and instructions.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"greeting": "<greeting>"
},
"name": "calls_make"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | Android package that places the call (generic — any app with a dispatch recipe, or manual UI dispatch). Example: 'com.whatsapp'. Used only when channel='android'. Ignored for other channels. | |
| channel | No | Voice transport: 'twilio' or 'telnyx' (phone via PSTN — both require phone_number in E.164; pick the carrier the workspace has connected), 'telegram' (MTProto 1:1 call — requires telegram_user_id, NOT a phone number or thread_id), 'maxru' (Max.ru voice call — requires maxru_user_id), 'android' (Android device voice call — requires phone_number in E.164), 'whatsapp' (WhatsApp voice call via the workspace's connected WhatsApp account — requires phone_number in E.164), 'whatsapp_business' (a Meta Cloud API number; requires phone_number in E.164; the contact must have allowed calls, otherwise a permission request is sent instead). OMIT to auto-select based on the current thread (e.g. inside a Telegram DM → uses 'telegram'). | |
| greeting | Yes | The first sentence the agent speaks immediately when the call connects. ALWAYS provide a greeting — without it the caller hears silence. Keep it short and natural. Example: 'Hi, this is Diana calling from DialogBrain. Do you have a moment to chat?' | |
| contact_id | No | LINE only: the contact entity ID for storing the confirmed display name after placement. Ignored for other channels/apps. | |
| report_back | No | When to re-invoke you after the call ends. 'on_answer' (default) = only if the call was answered, 'always' = even on missed/failed calls, 'never' = fire and forget. Transcript is always stored regardless of this setting. | |
| in_workspace | No | Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected. | |
| instructions | No | What to do during the call — objective, questions, tone. The AI generates a natural opening and guides the conversation. Example: 'Call about invoice #1234. Ask if they received it and when payment is expected. Be friendly and professional.' | |
| phone_number | No | Destination phone number in E.164 format (e.g., '+15551234567', '+66812345678'). Required when channel='twilio'. | |
| viber_number | No | Destination Viber number in E.164 (e.g., '+15551234567'). Required when channel='viber' — the call is placed from the workspace's connected Viber account. | |
| maxru_user_id | No | Destination Max.ru user/chat ID. Required when channel='maxru'. | |
| skip_dispatch | No | Set true after you placed the call manually with the android_* UI tools — skips the automatic recipe and attaches straight to the already-live call. OMIT for the normal automatic dispatch. Used only when channel='android'. Ignored for other channels. | |
| voice_agent_id | No | ID of the agent that conducts the call (an `id` from agents.list). If omitted, uses the workspace's default voice-capable agent when one exists. Pass this when the call fails with 'No voice agent configured'. | |
| telegram_user_id | No | Destination Telegram user ID (decimal int64 as string, e.g. '123456789'). Required when channel='telegram'. The caller account must have had prior interaction with this user — a cold contact cannot be reached via voice. | |
| channel_account_id | No | The account that places the call (id from channels.list): the phone number for twilio/telnyx, the connected account for telegram, whatsapp, whatsapp_business. OMIT when the workspace has one account of the channel. With several and none named, the call is placed from the account of the conversation this run is in (a WhatsApp group call: from the number that is in the group); when that does not single one out the call is refused with the list. | |
| target_display_name | No | LINE only: the contact's LINE display name to place the voice call to (resolved by the planner from the contact). Ignored for other channels/apps. | |
| permission_request_text | No | Only for channel='whatsapp_business': the text of the call-permission request WhatsApp sends when the contact has not yet allowed calls. Omit for a generic default. |