Hail

Fetch the current state of one SMS by id. Use this after ``send_sms`` to check delivery status. Example: get_sms(sms_id="...")

Fetch one verification and its state. Use it to poll. There is no notification, and review takes business days. Poll every few minutes to hours, not every few seconds; the state refreshes from the carrier at most once a minute. On ``approved``: call quote_numbers again. The offer is now ``ready``; then acquire_number. On ``rejected``: read ``rejection_reason``, ask the user, dismiss it with cancel_verification, then submit a new one. ``verification_id`` comes from submit_verification or list_verifications. Returns ``{"i…

Read what the carrier needs to verify the organization before it can buy a number. Call this when quote_numbers shows an offer with ``readiness == "verification_required"``. Read-only. ``country_code`` is ISO alpha-2 (for example ``"GB"``). ``number_type`` is ``local``, ``mobile``, ``national`` or ``toll_free``. ``subject_type`` is required: ``person`` (the user) or ``business`` (the user's company). Never guess it: ask the user "you or your company?". The result's ``subject_types`` lists what the carrier accepts. The organizatio…

List the workspace's saved agents: the brains that answer calls and texts on its numbers, and that ``place_call`` can use via ``agent_id``. Returns ``{"items": [{"id", "name", "system_prompt", "first_message", "ai_disclosure", "ai_disclosure_line", "voice_config", "tools", "max_duration_seconds", "handover_max_duration_seconds", "voice_enabled", "sms_enabled", "status", "handover_contacts"}, ...]}``.

List recent calls in your organization, newest first. Cursor-paginated: pass the previous response's ``next_cursor`` to fetch the next page. ``status`` (one of queued, dialing, ringing, in_progress, completed, failed, busy, no_answer, canceled) and ``to`` (E.164) are optional server-side filters. Returns a dict ``{"items": [...], "next_cursor": <str|None>}``.

List the workspace's contacts: org members (with their phone/email) plus manually saved contacts. Use ``lookup_contact`` for name searches. ``q`` optionally filters server-side (matches name/email/phone). ``limit`` caps the page (server default 100, max 500). Returns ``{"items": [{"id", "kind", "name", "phone_e164", "email", "role"}, ...]}`` — ``kind`` is ``"member"`` (id ``member:<user_id>``, ``role`` set) or ``"manual"`` (id is the contact's UUID, ``role`` null).

List the addresses this workspace can send email from. Call this BEFORE ``send_email`` when you do not already know the ``from_`` address — do not guess a domain. Returns ``{"items": [...], "next_cursor": ..., "default_from": ...}``. Each item carries ``domain``, ``kind`` (``"custom"`` or ``"hail_mail"``) and ``verification_status``; only ``"verified"`` rows can send. A ``custom`` item's ``domain`` is a bare DNS name that accepts any local-part (``sales@acme.com``); a ``hail_mail`` item's ``domain`` is already a full address. …

List emails in your organization, newest first. Cursor-paginated: pass the previous response's ``next_cursor`` to fetch the next page. Two optional server-side filters: * ``direction`` — ``outbound`` or ``inbound``. Pass ``direction="inbound"`` to read replies and other received mail. * ``status`` — one of ``queued``, ``sent``, ``failed``, ``bounced``, ``complained``, ``received``. Items are trimmed summaries (no message body). Call ``get_email`` with an item's ``id`` to read the full body. Example: lis…

List the US state and Canadian province codes that quote_numbers accepts as ``region`` (optional, with ``city``). Returns ``{"regions": [{"country_code", "code", "name"}]}``, such as ``{"country_code": "US", "code": "AZ", "name": "Arizona"}``, or ``{"error": "<message>"}``.

List the workspace's dedicated phone numbers, newest first. ``limit`` is 1..200 (default 50). Pass the returned ``next_cursor`` as ``cursor`` for the next page. Returns ``{"items": [{"id", "e164", "country_code", "number_type", "capabilities", "provisioning_state", "voice_agent_id", "sms_agent_id", ...}], "next_cursor"}``, or ``{"error": "<message>"}``.

Page through recent SMS messages for your organization. ``status`` filters to one of: queued, sent, delivered, failed, undelivered, received. ``to`` filters to messages sent to a specific E.164 number. Paginate with the returned ``next_cursor``.

List the organization's carrier verifications, newest first. ``purpose`` is ``number`` or ``sms``; only that kind is listed. Omit to see every registration. ``purpose='sms'`` lists the registrations to text US numbers from a US number. Returns ``{"items": [{"id", "country_code", "number_type", "subject_type", "subject_name", "purpose", "state", "rejection_reason", "created_at", "updated_at", "submitted_at", "approved_at", "confirmation"}]}``. ``state`` is ``awaiting_review``, ``submitting``, ``submitted``, ``approved``, …

Find a contact by name, email, or phone fragment. Resolve a person to their ``phone_e164``/``email`` BEFORE calling ``place_call``, ``send_sms``, or ``send_email`` — do not guess a contact's number. Returns up to 10 matches, same item shape as ``list_contacts``. Example: lookup_contact(query="maya")

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 leadi…

Compare live phone-number offers from the carriers. Read-only: it buys nothing and charges nothing. ``country_code`` is an ISO alpha-2 code such as ``"US"``. ``capabilities`` is ``["voice"]``, ``["sms"]`` or both (default). ``number_type`` is ``local``, ``mobile``, ``national`` or ``toll_free``; omit it to compare all types. ``area_code`` is an area code or the first digits of the number, as dialed in the country: ``"020"`` (London), ``"480"`` (Arizona). ``city`` is a city name such as ``"London"``. Each offer has ``local…

Release a phone number. DESTRUCTIVE and permanent. Calls and texts to the number stop. This month's fee and any earlier months are still billed. There is no refund. The number may not be recoverable. Ask the user before calling this. ``confirm_e164`` must equal the number's ``e164`` (for example ``"+14155550100"``). The tool reads the number first and refuses with ``{"error": ...}`` on a mismatch, without releasing anything. A number whose order is still pending cannot be released (409). A number whose order failed was n…

Choose which agent answers a number's calls and texts. ``voice_agent_id`` makes the number answer calls with that agent (Hail registers it for inbound at the carrier and LiveKit); ``clear_voice=True`` stops answering calls. ``sms_agent_id`` makes the agent reply to texts; ``clear_sms=True`` stops that. A field left out keeps its value. ``number_id`` comes from GET /numbers. Returns the updated ``PhoneNumberResponse`` as a dict, or ``{"error": "<message>"}``.

Send an outbound email through your configured SES sender. ``to`` is a non-empty list of RFC-style email addresses. At least one of ``body_text`` / ``body_html`` is required (both is fine — multipart-alternative). Prefer including ``body_html``: open and click tracking only works for emails with an HTML body. A plain-text-only email still gets sent, delivered, and bounce events, but opens and clicks are never tracked. ``cc``, ``bcc``, and ``reply_to`` are optional and follow the usual mail conventions. Hail sets no ``repl…

Send an outbound SMS. ``to`` must be E.164 (e.g. ``+14155551234``). ``body`` is the message text. With no ``from_``: destinations where the sender-ID carrier delivers a dynamic alphanumeric sender ID unchanged (about 110 countries, see core/hailhq/core/sender_id_corridors.py) use your organization's sender ID (or ``HAIL``, the platform default); Australia (+61) may use ``HAIL`` instead; every other destination, including the US and Canada, uses your organization's oldest active SMS-capable number and the API retur…

Send the user's personal or company details and identity documents to the carrier for verification. IRREVERSIBLE: once submitted it cannot be cancelled, and the carrier keeps the documents. ``attest_authorized``: pass true only if the person or company named in these details and documents asked for this submission and gave you the details and files in this conversation. Never invent, guess, infer or reuse personal data or documents. Anything else: pass false (the call then sends nothing). ``purpose`` is ``number`` (default) or `…

Change a saved agent. Safe to repeat: the same call gives the same result. Only the fields you pass change; a field left out keeps its value. ``status`` is ``"live"`` or ``"paused"``; a paused agent does not answer. ``language`` is a lowercase ISO 639-1 code. Pass ``language`` or ``voice_id`` alone: the other value is kept. ``max_duration_seconds`` and ``handover_max_duration_seconds`` are 60..3600. ``handover_contacts`` replaces the whole list: ``[{contact_id, note}]`` (max 10) as in ``create_agent``; ``[]`` removes every contac…

Upload a file to attach to a future outbound email. ``content_base64`` is the file's raw bytes, base64-encoded. Returns ``{"id": ..., "filename": ..., "content_type": ..., "size_bytes": ...}`` — pass ``id`` in ``send_email``'s ``attachment_ids`` list. The id is reusable across many sends and expires in 24h if never used. Files over 25MB (combined with the message body and any other attachments, per send) are rejected — host large files externally and link to them in the body instead.

Identify the human whose credentials this session runs under. Use it to sign or route mail as that person: pass their address as ``send_email(reply_to=...)`` so replies reach them rather than the sending domain, which is often an unattended ``noreply@``. Returns ``{"auth_kind", "organization_id", "user_id", "email", "name"}``. ``user_id``/``email``/``name`` are null when the server runs on a shared operator key (``auth_kind="shared"``) — there is no human behind it, so send without a ``reply_to``. Example: whoami() …