Reference

Voice

client.voice.get() -> typing.Any

📝 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.

Returns account_id, default_voice_id (the stored preset name or UUID, null when none is set) and resolved_voice_id (the voice UUID calls will actually use).

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.voice.get()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.voice.reset() -> typing.Any

📝 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), starting with their next call. The previous value is not kept: read it with get_account_voice first if it may be needed again.

Returns account_id, default_voice_id null, resolved_voice_id (the system default) and a message.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.voice.reset()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.voice.set(...) -> typing.Any

📝 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 (make_outbound_call)
Agent voice_id (update_agent)
Account default (this tool)
System default (Supportive Male)

Returns account_id, default_voice_id (as sent) and resolved_voice_id (the UUID it resolves to). An unknown preset or malformed UUID returns HTTP 400.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.voice.set(
    voice_id="voice_id",
)

⚙️ Parameters

voice_id: str — Default voice for the account: a preset_name such as 'female-1' or a voice_id UUID, both listed by list_available_voices.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.voice.list(...) -> typing.Any

📝 Description

List the voices an AI phone agent can speak with.

Returns the six built-in voices — female-1, female-2, female-3, male-1, male-2, male-3 — plus the speech languages an agent can be pinned to and the speaking-speed range. The owner can pick from many more voices (accents and languages) in the AgentLine dashboard; an agent set to one of those keeps it.

Returns {"voices": [...], "languages": [...], "speaking_speed": {...}, "default_voice_id", "usage_hint"}. Each voice has preset_name (e.g. "female-1"), voice_id, name, tagline, description, gender, accent, locale, language and has_preview. Pass either preset_name or voice_id as voice_id to create_agent, update_agent, make_outbound_call or set_account_voice.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.voice.list()

⚙️ Parameters

gender: typing.Optional[str] — feminine | masculine | neutral

language: typing.Optional[str] — Language ('en') or locale ('en-GB') to filter by.

q: typing.Optional[str] — Free-text search over name, tagline, description and accent.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents

client.agents.list() -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.agents.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.create(...) -> AgentOut

📝 Description

Create a new AI voice agent for telephony.

Adds an agent to the account with its own system prompt, voice and greeting. Creating an agent is free; it cannot call until it has a number, so call buy_phone_number next with the returned id as agent_id.

Returns the new agent, including its id (agt_...). A voice_id that is not a preset from list_available_voices or a voice UUID is rejected, as is a transfer_number that differs from owner_phone (HTTP 400).

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.agents.create(
    name="name",
)

⚙️ Parameters

name: str — Display name for the AI voice agent

system_prompt: typing.Optional[str] — Default instructions for the agent's personality and behavior on ALL calls (inbound and outbound). Can be overridden per-call via POST /v1/calls.

initial_greeting: typing.Optional[str] — Default opening line spoken on ALL calls (inbound and outbound), e.g. 'Hello, how can I help you today?'. Can be overridden per-call via POST /v1/calls.

voice_id: typing.Optional[str] — Voice the agent speaks with: a voice_id from list_available_voices or a legacy preset name (e.g. 'female-1'); defaults to the system voice if not set

speech_language: typing.Optional[str] — BCP-47 locale the agent listens and speaks in, e.g. 'en-US', 'hi-IN'. 'auto' (or unset) keeps multilingual auto-detection. Allowed values are listed under 'languages' by list_available_voices.

speaking_speed: typing.Optional[float] — Speaking pace multiplier from 0.6 (slower) to 1.5 (faster); 1.0 is the voice's natural pace.

transfer_number: typing.Optional[str] — Number a live call is transferred to. Only the owner phone is allowed, so leave it out or send the same E.164 number as owner_phone; setting owner_phone fills it in.

voicemail_message: typing.Optional[str] — Message the AI agent leaves if the call goes to voicemail

owner_phone: typing.Optional[str] — Owner's phone number in E.164 format (e.g. '+12125551234'). Calls from this number enter task mode. This is also the only number a live call can be transferred to.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.get(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.agents.get(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str — Agent ID (agt_...) returned by create_agent or list_agents.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.delete(...) -> typing.Any

📝 Description

Delete an AI voice agent.

Permanently removes the agent with its calls and transcripts, messages, conversations, contacts and webhook. Cannot be undone. Phone numbers assigned to it are detached, not released: they stay active on your account and can be reassigned to another agent.

Returns {"deleted": true, "agent_id": ...}.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.agents.delete(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str — Agent ID (agt_...) returned by create_agent or list_agents.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.update(...) -> typing.Any

📝 Description

Update an AI voice agent's configuration.

Overwrites the fields you send; omitted fields keep their values and the old values are not kept. Changes apply to the next inbound or outbound call the agent handles; calls already in progress are unaffected.

Returns the full updated agent. Sending no fields, an unknown voice_id or a transfer_number other than owner_phone returns HTTP 400.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.agents.update(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str — Agent ID (agt_...) returned by create_agent or list_agents.

name: typing.Optional[str] — New display name for the AI voice agent

system_prompt: typing.Optional[str] — Updated default instructions for ALL future calls (does not affect calls already in progress)

initial_greeting: typing.Optional[str] — Updated default greeting for ALL future calls (inbound and outbound)

voice_id: typing.Optional[str] — New voice: a voice_id from list_available_voices or a legacy preset name

speaking_speed: typing.Optional[float] — Speaking pace multiplier from 0.6 (slower) to 1.5 (faster); 1.0 is the voice's natural pace. Send null to go back to 1.0.

transfer_number: typing.Optional[str] — Number a live call is transferred to. Only the owner phone is allowed, so send the same E.164 number as owner_phone (current or in this request); setting owner_phone updates it automatically.

voicemail_message: typing.Optional[str] — Updated voicemail message

owner_phone: typing.Optional[str] — Updated owner phone in E.164. Also becomes the only live-call transfer destination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Billing

client.billing.get_balance() -> typing.Any

📝 Description

Get your AI telephony account balance and rate card.

Returns the current balance, currency, billing rates for calls, phone numbers, and SMS, plus what the balance can cover. Use this to check affordability before paid telephony operations.

trial is null, or the account's free trial: status (pending until the first number is provisioned, then active for 7 days; converted or expired), ends_at, call_seconds_remaining, sms_remaining and number_id of the free trial number. A top-up or plan converts the trial and keeps the number; an expired trial's number is detached.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.billing.get_balance()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.billing.get_expenditure(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.billing.get_expenditure()

⚙️ Parameters

period: typing.Optional[str] — Which spending to total: 'current_month', 'last_month', 'all_time', or one calendar month as 'YYYY-MM' (e.g. '2026-09'). Unrecognized values fall back to the current month.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.billing.list_call_charges(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.billing.list_call_charges()

⚙️ Parameters

limit: typing.Optional[int] — Maximum number of call charges to return (1-200)

offset: typing.Optional[int] — Number of records to skip for pagination

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.billing.list_number_charges(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.billing.list_number_charges()

⚙️ Parameters

limit: typing.Optional[int] — Maximum number of number charges to return (1-200)

offset: typing.Optional[int] — Number of records to skip for pagination

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.billing.get_summary(...) -> typing.Any

📝 Description

Month-over-month spending summary.

Returns total debits grouped by month for trend analysis.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.billing.get_summary()

⚙️ Parameters

months: typing.Optional[int] — Number of months to show

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Calls

client.calls.list(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.calls.list()

⚙️ Parameters

agent_id: typing.Optional[str] — Only calls handled by this agent (agt_... from list_agents). Omit for every agent on the account.

status: typing.Optional[str] — Only calls in this exact status, e.g. 'completed' or 'failed'. Other statuses: 'initiated', 'in-progress', 'busy', 'no-answer', 'canceled'.

limit: typing.Optional[int] — Page size: how many calls to return, newest first.

offset: typing.Optional[int] — How many calls to skip, to page past earlier results.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.calls.create(...) -> typing.Any

📝 Description

Make an outbound phone call from your AI agent.

Dials a real person or business from the agent's number. The agent holds the whole conversation on its own with its system prompt, voice and greeting (or this call's overrides). The call reaches a third party and is billed to the account at $0.12 per minute, first minute charged in full, so confirm with the user first. Not idempotent: every successful call dials again.

Prerequisites: an agent with an active number from buy_phone_number (HTTP 400 otherwise), plus remaining subscription minutes or at least $0.50 of wallet balance (HTTP 402 otherwise). Included minutes are used first; only uncovered call time is charged to the wallet.

Returns right after dialing with the call id (call_...), agent_id, from_number, to_number, direction, status and started_at; the call runs on its own. Check get_call_details for progress and call get_call_transcript once status is completed.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.calls.create(
    agent_id="agent_id",
    to_number="to_number",
)

⚙️ Parameters

agent_id: str — ID of the AI agent making the call (e.g. 'agt_abc123')

to_number: str — Destination phone number in E.164 format (e.g. '+12125551234')

system_prompt: typing.Optional[str] — Per-call system prompt override. Replaces the agent's default prompt for this call ONLY. If omitted, the agent's default system_prompt is used.

initial_greeting: typing.Optional[str] — Per-call greeting override. Replaces the agent's default greeting for this call ONLY. If omitted, the agent's default initial_greeting is used.

voice_id: typing.Optional[str] — Override the TTS voice for this call: preset name (e.g. 'female-1') or a voice UUID

from_number_id: typing.Optional[str] — Specific phone number ID to call from; defaults to the agent's assigned number

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.calls.get(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.calls.get(
    call_id="call_id",
)

⚙️ Parameters

call_id: str — Call ID (call_...) from make_outbound_call, list_calls or a call event.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.calls.push_context(...) -> typing.Any

📝 Description

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

A call.utterance or call.task.open event means a live caller is waiting. Do the work, then push the facts; they reach the call immediately. The hosted voice phrases them in its own words (it never reads your text aloud) and keeps them for the rest of the call.

Arguments: call_id, turn_id and token from the event; context (the facts) and disposition (partial, progress, done, failed, noop or facts). context is required unless disposition is noop. turn_id is required unless disposition is facts.

Auth: pass the event's push_token as token. An AgentLine API key as Authorization: Bearer also works; OAuth tokens do not.

Returns {"delivered": true, "status", "call_id", "turn_id"}; status "duplicate" means an identical retry was already accepted. HTTP 409: the turn is stale or cancelled, so do not reuse this context. HTTP 410: the call ended; stop working on this request.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.calls.push_context(
    call_id="call_id",
)

⚙️ Parameters

call_id: str — ID (call_...) of the live call, from the call.utterance or call.task.open event.

token: typing.Optional[str] — The push_token from the call.utterance or call.task.open event. Authorizes this push for that call; same as the X-Push-Token header.

turn_id: typing.Optional[str] — The exact turn_id from the event, identifying the question being answered. Required except for disposition=facts.

push_token: typing.Optional[str]

context: typing.Optional[str] — The facts for the caller, in plain text, e.g. "John emailed yesterday about an invoice." The hosted voice rephrases them. Required unless disposition is noop.

disposition: typing.Optional[CallContextPushDisposition] — What this push does with the open task. partial: one real fact so far, spoken now, task stays open. progress: a note for the voice, not spoken, task stays open. done (default): final facts, settles the task. failed: could not do it, settles the task. noop: settle the task with nothing to say; context not needed. facts: a briefing for the whole call at any time, no turn_id needed.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.calls.hangup(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.calls.hangup(
    call_id="call_id",
)

⚙️ Parameters

call_id: str — Call ID (call_...) from make_outbound_call, list_calls or a call event.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.calls.get_transcript(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.calls.get_transcript(
    call_id="call_id",
)

⚙️ Parameters

call_id: str — Call ID (call_...) from make_outbound_call, list_calls or a call event.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Events

client.events.poll(...) -> typing.Any

📝 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, so process or store them. Use peek_events to look without consuming.

Returns {"events": [...], "count"}: each event has event_id, agent_id, event_type, payload and created_at, oldest first. An empty list means nothing is pending. Agents with a webhook receive events there instead.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.events.poll()

⚙️ Parameters

agent_id: typing.Optional[str] — Only events for this agent (agt_... from list_agents). Omit for every agent on the account.

event_type: typing.Optional[str] — Only events of this exact type, e.g. 'call.completed', 'call.failed', 'call.received' or 'sms.received'.

limit: typing.Optional[int] — Most events to claim in this call, oldest first. Events past the limit stay queued for the next poll.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.events.peek(...) -> typing.Any

📝 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.

Returns {"pending_count", "events"}: pending_count counts every queued event for the account (or agent_id); events lists event_id, agent_id, event_type and created_at, without payloads. Call poll_events to get the payloads.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.events.peek()

⚙️ Parameters

agent_id: typing.Optional[str] — Only events for this agent (agt_... from list_agents). Omit for every agent on the account.

limit: typing.Optional[int] — Most events to list, oldest first. Does not change pending_count.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Messages

client.messages.list(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.messages.list()

⚙️ Parameters

agent_id: typing.Optional[str] — Only messages for this agent (agt_... from list_agents). Omit for every agent on the account.

conversation_id: typing.Optional[str] — Only messages in this thread; take conversation_id from an earlier list_messages result.

limit: typing.Optional[int] — Page size: how many messages to return, newest first.

offset: typing.Optional[int] — How many messages to skip, to page past earlier results.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.messages.send(...) -> MessageOut

📝 Description

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

Each account can send 250 texts per UTC day across all its agents, unless the account has a raised limit.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.messages.send(
    agent_id="agent_id",
    to_number="to_number",
    body="body",
)

⚙️ Parameters

agent_id: str — ID of the AI agent sending the SMS (e.g. 'agt_abc123')

to_number: str — Destination phone number in E.164 format (e.g. '+12125551234')

body: str — SMS message text content

media_url: typing.Optional[str] — URL of media to attach (MMS)

from_number_id: typing.Optional[str] — Specific phone number ID to send from; defaults to the agent's assigned number

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.messages.list_conversations(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.messages.list_conversations()

⚙️ Parameters

agent_id: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Numbers

client.numbers.list() -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.numbers.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.numbers.buy(...) -> typing.Any

📝 Description

Buy a US or Canadian phone number for your AI agent.

Buys a real +1 number from the carrier, attaches it to the agent and uses an included subscription number, or charges $3.00 to the wallet. Once attached, the agent can make outbound calls and answers inbound calls on this number. Existing numbers retain their carrier. Each agent can have only one active number.

Free trial: an account that has never paid gets its first local number free (cost 0, trial true, trial_ends_at). That purchase starts a 7-day trial with 10 call minutes and 10 SMS. The number stays with the account after a top-up or plan purchase; otherwise it is detached from the account when the trial ends.

Prerequisites: an agent from create_agent with no active number (each agent has at most one; a second purchase returns HTTP 409), plus the trial's free number, a remaining subscription number allowance or $3.00 in the wallet (HTTP 402 otherwise; see get_account_balance).

Returns the number's id (num_..., used by release_phone_number and as from_number_id), phone_number, country, number_type, status, cost, balance_remaining and a private number card link (card_url, card_image_url, card_url_expires_at). After the purchase, tell the human about the card: card_message says what to pass on. If the account has an owner email, the card link is also emailed there.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.numbers.buy(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str — ID of the AI agent to assign this phone number to (e.g. 'agt_abc123')

country: typing.Optional[str] — Country code for the phone number ('US' or 'CA')

number_type: typing.Optional[str] — 'local' for a number in a geographic area code, or 'tollfree' for a toll-free 8xx number

area_code: typing.Optional[str] — For local numbers, the area code the number should be in, written as 3 digits (US e.g. '212' NYC, '415' SF; Canada e.g. '416' Toronto, '604' Vancouver, '514' Montreal); other values make the purchase fail. For tollfree, a prefix such as '800' or '888' narrows the search and other values are ignored. Omit to take any available number.

pattern: typing.Optional[str] — Legacy search: digits the local number must contain, e.g. '555'. Used only for local numbers when area_code is omitted; prefer area_code.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.numbers.attach(...) -> typing.Any

📝 Description

Manually attach a number that was bought outside this account. Each agent can only have ONE active number.

Query params:

phone_number: E.164 format (e.g. "+12125551234")
agent_id: agent to attach to
country: "US" (default) or "CA" — both are +1, so say which

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.numbers.attach(
    phone_number="phone_number",
    agent_id="agent_id",
)

⚙️ Parameters

phone_number: str

agent_id: str

country: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.numbers.get(...) -> typing.Any

📝 Description

Get details of a specific phone number.

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

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.numbers.get(
    number_id="number_id",
)

⚙️ Parameters

number_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.numbers.reassign(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.numbers.reassign(
    number_id="number_id",
    agent_id="agent_id",
)

⚙️ Parameters

number_id: str

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Webhooks

client.webhooks.list(...) -> typing.Any

📝 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, by set_webhook.

Returns {"webhooks": [...], "count"}: each has agent_id, url, masked secret, signature_header, protocol, capabilities and created_at. An empty list means no webhook is set, so events wait for poll_events. HTTP 404 if agent_id is not an agent on this account.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.webhooks.list()

⚙️ Parameters

agent_id: typing.Optional[str] — Inspect one agent's webhook (omit to list all)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.set(...) -> 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; setting it again replaces the URL. Omitted secret, signature_header, protocol and capabilities keep their current values.

Returns agent_id, url, the full secret (shown only here; get_webhook masks it), signature_header, protocol, capabilities and created_at. Store the secret to verify the signature header on deliveries.

🔌 Usage

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.webhooks.set(
    url="url",
    agent_id="agent_id",
)

⚙️ Parameters

url: str — HTTPS URL that will receive this agent's events as signed JSON POSTs. Setting this replaces any existing webhook for the agent.

agent_id: str — ID (agt_...) of the agent whose events this webhook receives, from create_agent or list_agents. Each agent may have at most one webhook.

secret: typing.Optional[str] — Optional HMAC signing secret used to verify the signature header on delivered payloads. Omit to keep the current secret, or to auto-generate one for a new webhook.

signature_header: typing.Optional[str] — Header name for the HMAC-SHA256 signature of the raw body. Defaults to 'X-Webhook-Signature' (natively verified by Hermes, OpenClaw, and other agent platforms). Set to 'X-Hub-Signature-256' for GitHub-style verification, or any custom header name your platform expects. Omit to keep the existing value when updating.

protocol: typing.Optional[WebhookConfigProtocol] — Live relay protocol. 'agentline-relay/1' (default): one call.utterance POST per task, answer in the response body or via push. 'agentline-relay/2': typed POSTs (call.session.start, call.task.open, call.task.amend, call.task.cancel, call.session.end); answer only via POST /v1/calls/{call_id}/context and return 202 quickly. Omit to keep the existing value when updating.

capabilities: typing.Optional[WebhookCapabilities] — Relay v2 capabilities. Omit to keep the existing value when updating.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.delete(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.webhooks.delete(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str — Agent whose webhook to delete

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.test(...) -> typing.Any

📝 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

from agentline_ai import AgentLine
from agentline_ai.environment import AgentLineEnvironment

client = AgentLine(
    api_key="<token>",
    environment=AgentLineEnvironment.PRODUCTION,
)

client.webhooks.test(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str — Agent (agt_... from list_agents) whose configured webhook should receive the test event.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

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

📝 Description