Reference

Voice

client.voice.get() -> unknown

📝 Description

Get the current account-level default voice for AI phone agents.

Returns which voice is used for all AI agents under this account unless overridden at the agent level or per-call. Controls how your AI agents sound during phone conversations.

🔌 Usage

await client.voice.get();

⚙️ Parameters

requestOptions: VoiceClient.RequestOptions

client.voice.reset() -> unknown

📝 Description

Reset account voice to the system default.

Removes the account-level voice override so all AI agents fall back to the system default voice during phone calls (unless they have their own voice_id configured).

🔌 Usage

await client.voice.reset();

⚙️ Parameters

requestOptions: VoiceClient.RequestOptions

client.voice.set({ ...params }) -> unknown

📝 Description

Set the account-level default voice for AI phone agents.

This becomes the default voice for ALL AI agents under this account, controlling how they sound on phone calls. Individual agents or specific calls can still override this setting.

Voice resolution priority:

Per-call voice_id (POST /v1/calls)
Agent voice_id (PATCH /v1/agents/{id})
Account default (this endpoint) ← you are here
System default (Supportive Male)

Accepts:

A preset name: "female-1", "female-2", "female-3", "male-1", "male-2", "male-3"
A Cartesia voice UUID: "f786b574-daa5-4673-aa0c-cbe3e8534c02"

🔌 Usage

await client.voice.set({
    voice_id: "voice_id"
});

⚙️ Parameters

request: AgentlineApi.VoiceSettingUpdate

requestOptions: VoiceClient.RequestOptions

client.voice.list() -> unknown

📝 Description

List all available voice presets for AI phone agents.

Returns named TTS (text-to-speech) voice presets that can be used when configuring AI agents or making phone calls. Each voice defines how your AI agent sounds on the phone.

You can use a preset name (e.g. "female-1", "male-1") or pass any valid Cartesia voice UUID directly as a voice_id.

🔌 Usage

await client.voice.list();

⚙️ Parameters

requestOptions: VoiceClient.RequestOptions

Agents

client.agents.list() -> unknown

📝 Description

List all AI voice agents configured on your account.

Returns every AI phone agent you've created, including their system prompts, voice settings, and associated phone numbers. Useful for checking which agents are ready to make or receive calls.

🔌 Usage

await client.agents.list();

⚙️ Parameters

requestOptions: AgentsClient.RequestOptions

client.agents.create({ ...params }) -> AgentlineApi.AgentOut

📝 Description

Create a new AI voice agent for telephony.

Sets up a new AI phone agent with a custom system prompt, voice, and greeting. Once created, buy a phone number and attach it to this agent so it can make and receive calls autonomously.

Fields:

name: Display name for the agent
system_prompt: Instructions that define the agent's personality and behavior on calls
initial_greeting: What the AI agent says when the call connects
voice_id: TTS voice preset (e.g. "female-1") or Cartesia UUID
transfer_number: Phone number to transfer calls to (e.g. a human operator)
voicemail_message: Message the agent leaves if the call goes to voicemail

🔌 Usage

await client.agents.create({
    name: "name"
});

⚙️ Parameters

request: AgentlineApi.AgentCreate

requestOptions: AgentsClient.RequestOptions

client.agents.get({ ...params }) -> unknown

📝 Description

Get details of a specific AI voice agent.

Returns the agent's full configuration including system prompt, voice settings, greeting, and transfer number.

🔌 Usage

await client.agents.get({
    agent_id: "agent_id"
});

⚙️ Parameters

request: AgentlineApi.GetAgentsRequest

requestOptions: AgentsClient.RequestOptions

client.agents.delete({ ...params }) -> unknown

📝 Description

Delete an AI voice agent.

Permanently removes the agent, its calls, messages, and conversations, and detaches any phone numbers assigned to it. Detached numbers remain active on your account and can be reassigned to another agent.

🔌 Usage

await client.agents.delete({
    agent_id: "agent_id"
});

⚙️ Parameters

request: AgentlineApi.DeleteAgentsRequest

requestOptions: AgentsClient.RequestOptions

client.agents.update({ ...params }) -> unknown

📝 Description

Update an AI voice agent's configuration.

Modify any combination of the agent's settings: system prompt, voice, greeting, transfer number, or voicemail message. Changes take effect on the next call the agent handles. Only include the fields you want to change — unset fields are preserved.

🔌 Usage

await client.agents.update({
    agent_id: "agent_id"
});

⚙️ Parameters

request: AgentlineApi.AgentUpdate

requestOptions: AgentsClient.RequestOptions

Billing

client.billing.getBalance() -> unknown

📝 Description

Get your AI telephony account balance and rate card.

Returns the current balance, currency, billing rates for calls and phone numbers, and how many call minutes or phone numbers the balance can cover. Use this to check affordability before making calls or buying numbers for your AI agents.

🔌 Usage

await client.billing.getBalance();

⚙️ Parameters

requestOptions: BillingClient.RequestOptions

client.billing.getExpenditure({ ...params }) -> unknown

📝 Description

Get a detailed expenditure breakdown for AI telephony usage.

Shows total spend split by category (voice calls, phone number provisioning, top-ups, refunds) with counts and averages. Useful for tracking how much your AI agents are spending on phone calls and phone numbers.

🔌 Usage

await client.billing.getExpenditure();

⚙️ Parameters

request: AgentlineApi.GetExpenditureBillingRequest

requestOptions: BillingClient.RequestOptions

client.billing.listCallCharges({ ...params }) -> unknown

📝 Description

List individual call charges from AI agent phone calls.

Each entry includes the voice call duration, cost, direction (inbound/outbound), phone numbers involved, and timestamp. Shows exactly how much each AI agent call cost.

🔌 Usage

await client.billing.listCallCharges();

⚙️ Parameters

request: AgentlineApi.ListCallChargesBillingRequest

requestOptions: BillingClient.RequestOptions

client.billing.listNumberCharges({ ...params }) -> unknown

📝 Description

List phone number provisioning charges.

Shows the cost of each phone number bought for your AI agents, including the number, country, and current status.

🔌 Usage

await client.billing.listNumberCharges();

⚙️ Parameters

request: AgentlineApi.ListNumberChargesBillingRequest

requestOptions: BillingClient.RequestOptions

client.billing.getSummary({ ...params }) -> unknown

📝 Description

Month-over-month spending summary.

Returns total debits grouped by month for trend analysis.

🔌 Usage

await client.billing.getSummary();

⚙️ Parameters

request: AgentlineApi.GetSummaryBillingRequest

requestOptions: BillingClient.RequestOptions

Calls

client.calls.list({ ...params }) -> unknown

📝 Description

List voice calls made by your AI agents.

Returns call history with optional filters by agent or status. Each entry includes direction (inbound/outbound), duration, phone numbers, and current status.

Filters:

agent_id: only calls for a specific AI agent
status: "initiated", "in-progress", "completed", or "failed"

🔌 Usage

await client.calls.list();

⚙️ Parameters

request: AgentlineApi.ListCallsRequest

requestOptions: CallsClient.RequestOptions

client.calls.create({ ...params }) -> unknown

📝 Description

Make an outbound phone call from your AI agent.

Initiates a real phone call from the AI agent's phone number to the specified destination. The agent uses its configured system prompt, voice, and greeting to conduct the conversation autonomously.

The AI agent handles the entire call — speech-to-text, LLM reasoning, and text-to-speech — in real time. The call transcript is saved automatically and can be retrieved via GET /v1/calls/{call_id}/transcript.

Request body:

agent_id: the AI agent making the call
to_number: destination phone number in E.164 format (e.g. "+12125551234")
from_number_id: (optional) specific number to call from
system_prompt: (optional) override the agent's default prompt for this call
initial_greeting: (optional) override the agent's greeting for this call
voice_id: (optional) override the voice for this call

🔌 Usage

await client.calls.create({
    agent_id: "agent_id",
    to_number: "to_number"
});

⚙️ Parameters

request: AgentlineApi.CallRequest

requestOptions: CallsClient.RequestOptions

client.calls.get({ ...params }) -> unknown

📝 Description

Get full details of a specific voice call.

Returns the call's metadata including direction, phone numbers, status, duration, AI agent configuration used, and the full conversation transcript between the AI agent and the caller.

🔌 Usage

await client.calls.get({
    call_id: "call_id"
});

⚙️ Parameters

request: AgentlineApi.GetCallsRequest

requestOptions: CallsClient.RequestOptions

client.calls.pushContext({ ...params }) -> unknown

📝 Description

Push context into a LIVE relay-mode call (mid-call context injection).

This is the required way for backend agents (Hermes, OpenClaw, etc.) to answer a live caller after a call.utterance event. Do your work, then POST a concise caller-ready response here. It is spoken verbatim and stored as the assistant turn for later conversation context.

AUTHENTICATION (one of):

Push token (preferred — no API key): the push_token from the call.utterance payload, via X-Push-Token header, ?token= query param, or push_token body field.
Bearer API key: Authorization: Bearer al_live_... for the account that owns the call.

Body — any of these keys works (context is canonical): {"context": "the exact short response the caller should hear"}

Other accepted keys: summary, answer, response, reply, text, result.

Every response must include the exact turn_id from call.utterance. Late context is rejected instead of being applied to another question.

Returns: delivered=true, status="live" — voice agent will speak it now delivered=true, status="duplicate" — identical retry already accepted HTTP 409 — turn is stale/cancelled HTTP 410 — call has ended. STOP working on this request and abandon any in-flight lookup. No further context will be spoken.

🔌 Usage

await client.calls.pushContext({
    call_id: "call_id",
    body: {
        "key": "value"
    }
});

⚙️ Parameters

request: AgentlineApi.PushContextCallsRequest

requestOptions: CallsClient.RequestOptions

client.calls.hangup({ ...params }) -> unknown

📝 Description

Hang up an active phone call.

Programmatically terminates an in-progress voice call. Use this when the AI agent needs to end the conversation, or to force-stop a call that is no longer needed. The call's final transcript and billing are processed automatically after hangup.

🔌 Usage

await client.calls.hangup({
    call_id: "call_id"
});

⚙️ Parameters

request: AgentlineApi.HangupCallsRequest

requestOptions: CallsClient.RequestOptions

client.calls.getTranscript({ ...params }) -> unknown

📝 Description

Get the full conversation transcript for a call.

Returns the complete speech-to-text transcript of the phone call, with each turn labeled by role ("human" for the caller, "assistant" for the AI agent). Useful for reviewing what was said on the call, extracting information, or auditing AI agent behavior.

🔌 Usage

await client.calls.getTranscript({
    call_id: "call_id"
});

⚙️ Parameters

request: AgentlineApi.GetTranscriptCallsRequest

requestOptions: CallsClient.RequestOptions

Events

client.events.poll({ ...params }) -> unknown

📝 Description

Poll for telephony events from your AI agents.

Returns pending events such as call completions, transcripts, and failures. Events are consumed on retrieval (one-time read) — once polled, they are automatically deleted from the mailbox.

Your AI agent should call this endpoint periodically to receive notifications about completed calls and their transcripts.

Filters:

agent_id: only events for a specific AI agent
event_type: e.g. "call.completed", "call.failed"

🔌 Usage

await client.events.poll();

⚙️ Parameters

request: AgentlineApi.PollEventsRequest

requestOptions: EventsClient.RequestOptions

client.events.peek({ ...params }) -> unknown

📝 Description

Peek at pending telephony events without consuming them.

Returns a preview of queued events (call completions, transcripts) without removing them from the mailbox. Useful for checking if there are events to process before committing to retrieve them.

🔌 Usage

await client.events.peek();

⚙️ Parameters

request: AgentlineApi.PeekEventsRequest

requestOptions: EventsClient.RequestOptions

Messages

client.messages.list({ ...params }) -> unknown

📝 Description

List SMS messages sent and received by your AI agents.

Returns message history with optional filters by AI agent or conversation. Each entry includes direction (inbound/outbound), phone numbers, message body, and delivery status.

🔌 Usage

await client.messages.list();

⚙️ Parameters

request: AgentlineApi.ListMessagesRequest

requestOptions: MessagesClient.RequestOptions

client.messages.send({ ...params }) -> unknown

📝 Description

Send an outbound SMS message from an AI agent's phone number.

🔌 Usage

await client.messages.send({
    agent_id: "agent_id",
    to_number: "to_number",
    body: "body"
});

⚙️ Parameters

request: AgentlineApi.MessageSend

requestOptions: MessagesClient.RequestOptions

client.messages.listConversations({ ...params }) -> unknown

📝 Description

List all SMS conversations for your AI agents.

Returns conversation threads, optionally filtered by AI agent. Each conversation represents an ongoing SMS exchange between an AI agent's phone number and an external contact.

🔌 Usage

await client.messages.listConversations();

⚙️ Parameters

request: AgentlineApi.ListConversationsMessagesRequest

requestOptions: MessagesClient.RequestOptions

Numbers

client.numbers.list() -> unknown

📝 Description

List all phone numbers provisioned on your account.

Returns every phone number you've bought for your AI agents, including which agent each number is assigned to, the number's status (active/released), and country.

🔌 Usage

await client.numbers.list();

⚙️ Parameters

requestOptions: NumbersClient.RequestOptions

client.numbers.buy({ ...params }) -> unknown

📝 Description

Buy a US phone number for your AI agent.

Searches for and purchases a real US phone number from the telephony provider, then attaches it to the specified AI agent. Once attached, the agent can make outbound calls and receive inbound calls on this number.

Each AI agent can only have ONE active phone number. Costs $2.00 per number.

Request body:

agent_id: str (required) — the AI agent to assign this number to
country: str (must be "US")
number_type: "local" | "tollfree"
area_code: preferred 3-digit US area code (e.g. "212" for NYC, "415" for SF)

🔌 Usage

await client.numbers.buy({
    agent_id: "agent_id"
});

⚙️ Parameters

request: AgentlineApi.NumberProvision

requestOptions: NumbersClient.RequestOptions

client.numbers.get({ ...params }) -> unknown

📝 Description

Get details of a specific phone number.

Returns the phone number, its assigned AI agent, provider ID, country, and current status.

🔌 Usage

await client.numbers.get({
    number_id: "number_id"
});

⚙️ Parameters

request: AgentlineApi.GetNumbersRequest

requestOptions: NumbersClient.RequestOptions

client.numbers.reassign({ ...params }) -> unknown

📝 Description

Reassign a phone number to a different AI agent.

Moves an existing phone number from one AI agent to another. The target agent must not already have an active number assigned. The phone number remains active — only the agent ownership changes.

🔌 Usage

await client.numbers.reassign({
    number_id: "number_id",
    agent_id: "agent_id"
});

⚙️ Parameters

request: AgentlineApi.ReassignNumbersRequest

requestOptions: NumbersClient.RequestOptions

Webhooks

client.webhooks.list({ ...params }) -> unknown

📝 Description

List the account's per-agent webhook configuration(s).

Secrets are masked. Pass agent_id to inspect a single agent's webhook. The full secret is only ever shown once, on the POST that creates/replaces it.

🔌 Usage

await client.webhooks.list();

⚙️ Parameters

request: AgentlineApi.ListWebhooksRequest

requestOptions: WebhooksClient.RequestOptions

client.webhooks.set({ ...params }) -> AgentlineApi.WebhookCreated

📝 Description

Create or replace an agent's webhook.

The configured URL receives ALL of that agent's event types — call lifecycle (call.received, call.completed, call.failed), SMS (sms.received), and future events — as signed JSON POSTs. Each agent may have at most one webhook; POSTing again replaces it.

agent_id: the agent whose events this webhook receives (required).
secret: HMAC signing secret. Omit to auto-generate.

The response returns the full secret once — store it to verify the signature header on deliveries.

🔌 Usage

await client.webhooks.set({
    url: "url",
    agent_id: "agent_id"
});

⚙️ Parameters

request: AgentlineApi.WebhookConfig

requestOptions: WebhooksClient.RequestOptions

client.webhooks.delete({ ...params }) -> unknown

📝 Description

Remove an agent's webhook. No events for that agent will be delivered via HTTP afterwards; they remain available via GET /v1/events (the mailbox).

🔌 Usage

await client.webhooks.delete({
    agent_id: "agent_id"
});

⚙️ Parameters

request: AgentlineApi.DeleteWebhooksRequest

requestOptions: WebhooksClient.RequestOptions

client.webhooks.test({ ...params }) -> unknown

📝 Description

Fire a signed webhook.test event to the agent's webhook.

Uses the exact same event bus (publish_event) that real telephony events use, so a successful delivery confirms the entire pipeline is wired correctly. Returns 404 if no webhook is configured for the agent.

🔌 Usage

await client.webhooks.test({
    agent_id: "agent_id"
});

⚙️ Parameters

request: AgentlineApi.TestWebhooksRequest

requestOptions: WebhooksClient.RequestOptions

Uh oh!

FilesExpand file tree

reference.md

Latest commit

History

reference.md

File metadata and controls

Reference

Voice

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Agents

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Billing

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Calls

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Events

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Messages