Place a phone call
place_callPlace an outbound AI phone call with a saved agent or custom prompt, attest recipient consent, and configure language, recording, first message, tools, and metadata.
Instructions
Originate an outbound phone call.
Provide ``system_prompt`` (mode A — Hail's bundled fallback LLM
uses this prompt) or ``llm`` (mode B — bring your own
OpenAI-compatible endpoint as
``{"base_url": ..., "api_key": ..., "model": ...}``), or both, or
``agent_id`` (a saved agent from ``list_agents`` supplies the
prompt, first message, AI line, voice and tools; fields you pass
here win). At least one is required. Passing both runs your prompt on your
own endpoint: it receives Hail's voice preamble plus your prompt
as the leading system message.
``to`` must be E.164 (e.g. ``+14155551234``). ``from_`` is
optional and defaults to the first active number on your org.
``first_message`` is spoken verbatim on pickup; omit it to let
the agent open the conversation itself — it reacts to how the
call was answered, or introduces itself after silence.
``language`` sets the call's spoken language for speech-to-text,
text-to-speech, and turn detection, as a lowercase ISO 639-1 code
(e.g. ``"da"``); 39 languages are supported (server rejects others
with 422); omit for English. STT provider selection is
console-BYO-only (no per-call override); configure it on the
organization to pin a provider.
``ai_disclosure=False`` skips the spoken "this is an AI
assistant" line at the start of the call. Leave enabled unless
the user has verified it is not required for this call — US
artificial-voice calls (47 CFR 64.1200(b)(1)) and several AI
bot-disclosure laws require it, and Hail does not verify this.
The agent still identifies itself as an AI if asked.
``recording_enabled``: omit it to follow the agent, then the
workspace recording setting. ``true`` records this call and
``false`` does not, whatever the workspace setting. Pass it only
when the user asked for or against a recording.
``metadata`` is free-form JSON attached to the call record.
``tools`` are the agent tools to allow on this call. Omit for all
available; pass ``[]`` to disable.
``recipient_consent`` is required and must be the JSON boolean
``true`` (strings and numbers are refused): attest that you (the caller
triggering this request) have obtained the lawful consent needed
to contact this recipient. The API rejects the request (422) if
this is not ``true`` — Hail does not verify consent for you, you
are responsible for having a lawful basis (TCPA / ePrivacy / GDPR
as applicable). Set ``message_type="marketing"`` for promotional
calls (this additionally requires a non-empty ``consent_source``
describing how/where consent was obtained) — leave as the default
``"informational"`` for transactional/service calls.
``idempotency_key`` defaults to a fresh UUID per invocation
and is returned in the response under ``idempotency_key`` — to
retry *this* exact request (rather than dispatch a second call),
pass the value back on the retry. A new key is a new call.
Example:
place_call(to="+14155551234",
recipient_consent=True,
system_prompt="You are scheduling a haircut.",
first_message="Hi, I'm calling on behalf of Alex.")
Returns the API's ``CallResponse`` as a dict (id, status,
from_e164, to_e164, ...). On failure returns
``{"error": "<message>"}`` instead.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| llm | No | ||
| from_ | No | ||
| tools | No | ||
| agent_id | No | ||
| language | No | ||
| metadata | No | ||
| message_type | No | informational | |
| ai_disclosure | No | ||
| first_message | No | ||
| system_prompt | No | ||
| consent_source | No | ||
| idempotency_key | No | ||
| recipient_consent | Yes | ||
| recording_enabled | No | ||
| consent_obtained_at | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||