Place a phone call
place_callStart an outbound AI phone call.
At least one of ``system_prompt``, ``llm`` or ``agent_id`` is required.
US artificial-voice calls (47 CFR 64.1200(b)(1)) require the AI disclosure.
Hail does not verify the lawful basis or the recipient's consent.
A 4xx response returns no ``idempotency_key``.
Returns the call ID, status, phone numbers and ``idempotency_key``, or an error.
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": {
"to": "<to>",
"recipient_consent": "<recipient_consent>"
},
"name": "place_call"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient phone number in E.164 format, such as ``+14155551234``. | |
| llm | No | Own model endpoint compatible with OpenAI's chat completions API: ``{base_url, api_key, model}``. Omitted: Hail's bundled model. | |
| from_ | No | Caller ID: an E.164 workspace number with voice, from ``list_numbers``. Omitted: an active workspace number, else one from the shared pool. | |
| tools | No | Names of the agent tools allowed on this call. An empty list disables them. Omitted: every tool the workspace's channels support. | |
| agent_id | No | Saved agent whose settings the call uses, from ``list_agents`` or ``create_agent``. Explicit arguments override its settings. | |
| language | No | Spoken language as a supported lowercase ISO 639-1 code, such as ``es``. Omitted: English. An unsupported code returns 422. | |
| metadata | No | Free-form JSON object stored on the call record. Keys starting with ``recording_`` are reserved. | |
| llm_model | No | Model ID of the calling agent. Optional. Recorded for analytics only. | |
| message_type | No | ``informational`` for transactional or service messages, or ``marketing``. | informational |
| ai_disclosure | No | Speak an AI notice at the start of the call. ``false`` skips it. | |
| first_message | No | Line spoken on pickup. Without it, the agent reacts to the answer or silence. | |
| system_prompt | No | Task instructions, added to the call agent's instructions. | |
| consent_source | No | Where or how consent was obtained, such as ``signup form``. Required when ``message_type`` is ``marketing``. | |
| idempotency_key | No | Retry key. The ``idempotency_key`` from an earlier response refers to that original request instead of starting a new one. Omitted: a new key is generated and returned. | |
| recipient_consent | Yes | Attestation that the recipient lawfully agreed to be contacted, as the user confirmed it. Hail does not check it; only ``true`` is accepted. | |
| recording_enabled | No | Recording for this call, overriding the agent and workspace settings. | |
| consent_obtained_at | No | When consent was obtained, as an ISO 8601 timestamp, if known. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||