On this page
Connect a phone number to an agent
To answer support calls, connect a number you control to a published agent. To make outbound calls, use an imported number as the caller ID. This guide takes you through the carrier connection, number assignment and first test call.
You need an admin for number setup, a published phone agent and a carrier number. The environment must have voice execution and capacity enabled. A member who places outbound calls also needs Can place calls permission.
Bring your own carrier
A SIP trunk is the connection between Cumulus and your telephone carrier. An imported number is a carrier number registered in your Cumulus environment. Creating that registration does not purchase a number or assign it to an agent.
In Twilio
Use a compatible Elastic SIP trunk with the numbers you intend to use. Configure TLS signaling, SRTP media and the trunk's authentication. Outgoing calls use its Termination settings. Incoming calls use Origination, which sends them to the Cumulus destination returned during setup.
In Talos
In Studio, an admin creates the trunk, stores its password as a sip_auth secret and imports the number. Through the API, the sequence is:
PUT /api/v1/secrets/support-sip
{ "kind": "sip_auth", "value": "<the carrier password, supplied securely>" }
POST /api/v1/telephony/trunks
{ "trunk_id": "support-trunk", "name": "Support", "provider": "twilio_elastic_sip",
"termination_uri": "your-trunk.pstn.twilio.com", "auth_username": "your-user",
"auth_secret": { "id": "support-sip", "version": "<returned secret version>" } }
POST /api/v1/telephony/numbers
{ "e164": "+14155550100", "trunk_id": "support-trunk", "nickname": "Support line" }
Send these requests with the admin key and retain each request's idempotency key where required. Replace the fictional number and carrier settings with your own. Read trunk creation and number import for all fields. Wait until the imported number reports ready before assigning it.
For an SDK project, bindings and integrations connect a logical number name to this existing imported resource. Publishing the graph and assigning that number remain separate steps.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/telephony/trunks | trunks_list | viewer | List the SIP trunks connected to the current environment. |
POST /api/v1/telephony/trunks | trunks_create | admin | Connect your carrier’s SIP trunk using a versioned credential secret. Enable inbound routing if the trunk will receive calls. |
PATCH /api/v1/telephony/trunks/{trunk_id} | trunks_update | admin | Change a connected SIP trunk’s settings. |
DELETE /api/v1/telephony/trunks/{trunk_id} | trunks_delete | admin | Disconnect a SIP trunk from the environment. |
GET /api/v1/telephony/numbers | numbers_list | viewer | List imported phone numbers and their agent assignments. |
POST /api/v1/telephony/numbers | numbers_import | admin | Import a number from a connected carrier trunk. Wait for the number to become ready before using it as caller ID. |
PATCH /api/v1/telephony/numbers/{number_id} | numbers_update | admin | Rename a number or change its agent assignments. An incoming-call assignment pins the current publication; reassign after changing the live version. |
DELETE /api/v1/telephony/numbers/{number_id} | numbers_release | admin | Release an imported number from Talos. |
Receive incoming calls
- Enable incoming calls with
PATCH /api/v1/telephony/trunks/{trunk_id}and{"inbound":true}. - Copy the returned
inbound_sip_uriinto the trunk's enabled Origination destination in Twilio. - Confirm that the called number is attached to that carrier trunk and is imported and
readyin Cumulus. - Assign the published agent with
PATCH /api/v1/telephony/numbers/{number_id}and{"inbound_agent_id":"<agent_id>"}. - Read the returned
inbound_agent_version, then call the number from an approved line. Confirm two-way speech and check the resulting run's agent and version.
The number keeps the publication assigned at step 4. Publishing a new version does not update that assignment automatically: assign the agent again when you want incoming calls to use the new version. Set inbound_agent_id to null to remove the assignment.
For example, if the number points to version 3 and you publish version 4, incoming calls still use version 3 until you reassign it. You can roll back by selecting an earlier live publication, assigning the number again and checking its returned version.
If an incoming call produces no run, check the carrier's failed-call log, the Origination destination and the number attachment. A TLS connection alone does not establish SRTP media; the exact trunk must support both.
Test an incoming version
Use an isolated test agent, synthetic records and a dedicated number. First test the conversation with simulations and browser voice where supported. Then publish the reviewed graph with live: true, assign the test number and make a controlled incoming call. Private keypad nodes need a telephone test.
A publication created with live: false remains test-only even after promotion; it is not a replacement for this live publication step. A phone run marked test: true also places a real call and uses the configured customer endpoints.
For a shared demo, use a company-controlled or approved disposable number rather than a personal number. Testing methods explains how to keep tool calls on sandbox services.
Load caller context
Look up the caller in your own system before the agent starts speaking. Define a dedicated HTTP action and bind its returned variables with phone.inbound_context, using drafts.edit. The action must be a phone POST with effect_key idempotency and a timeout of at most 10 seconds:
[
{ "type": "action.put", "action": {
"name": "incoming_context", "description": "Resolve caller account and routing context",
"channels": ["phone"], "method": "POST", "url": "https://your-service.example/incoming",
"headers": {}, "auth": { "scheme": "none" },
"input_schema": { "type": "object" }, "output_schema": { "type": "object" },
"idempotency": { "mode": "effect_key" }, "timeout_ms": 10000, "on_uncertain": "failure_edge"
} },
{ "type": "phone.inbound_context", "value": {
"action_id": "incoming_context", "variables": ["customer_name", "site_name", "noCallerIdMatch"]
} }
]
Use bearer, basic or header authentication with a version-pinned http_auth secret for your endpoint. An existing endpoint that verifies Retell webhook signatures can use {"scheme": "retell_signature", "secret_ref": {"id": "incoming-signing-key", "version": "<current_version>"}}; the key signs the exact request bytes and is never sent as a credential header. Store it through secrets.put, outside an assistant prompt.
The action receives this body, with the incoming call's actual numbers:
{ "event": "call_inbound", "call_inbound": {
"agent_id": "your-agent", "agent_version": 1,
"from_number": "+15555550123", "to_number": "+15555550100"
} }
Return {"call_inbound": {"dynamic_variables": {"customer_name": "Alex", "site_name": "North warehouse"}}}. For an unknown caller, return only routing flags such as {"call_inbound": {"dynamic_variables": {"noCallerIdMatch": "true"}}} and route to your identity lookup flow. Outputs are strings, at most 4096 characters each, with at most 256 fields. Only names declared in variables are applied. The lookup cannot choose another agent or change platform identity fields. A field omitted on a no-match path stays absent; using it later without a successful lookup ends that path with missing_variable.
Return {"call_inbound": {"reject": true}} to reject the call. A timeout, invalid response or refused action ends setup before the first conversation or recording starts.
The endpoint receives a stable Idempotency-Key; deduplicate it. Cumulus retains a successful lookup response under the environment's content-retention policy. If setup restarts, it can restore that response instead of asking your endpoint again. An expired or purged response cannot be restored.
Setup creates a run before calling this endpoint, so you can inspect the run even when the lookup fails. It runs only on incoming SIP calls; browser tests and outbound calls supply their context explicitly. Set the phone.inbound_context edit's value to null to remove the binding.
Publish the reviewed configuration with live: true, then assign the number to that version.
The inbound lookup runs only for incoming carrier calls. Outbound calls and browser tests must supply their own context; the SDK tutorial shows how.
Private keypad identity verification
A caller-number lookup finds a possible account; it does not verify the person. A verify_identity node can compare keypad input with the expected values supplied by your authorized business service. Its result selects the success or failure path. The caller ends a field with # and cancels with *.
These nodes require telephone runs. Browser, cloud and simulation runs cannot execute them. Use synthetic values and a dedicated number first. Private verification explains the policy, required exits and failure behavior.
Private keypad tokenization
After verification, a tokenize_private node can collect private fields and send them to your configured vault endpoint. The caller enters 1# to consent. The vault returns a UUID token; only that token and a permitted last-four suffix become ordinary flow values. Tokenization does not charge a card or schedule a payment.
If a vault request has an uncertain result, check it using the original effect identity before another attempt. Follow private workflow setup for endpoint authentication, consent, recording privacy and recovery.
Caller ID: from
For an outbound request, pass the imported number as from and the consenting recipient as to, both in E.164 form. If from is omitted, the published agent must have a valid telephony default. Use the complete phone request to start the call and retain its run ID.
A cold transfer's caller ID follows the trunk's configured mode. A node's showTransfereeAsCaller choice must agree with that mode; it does not reconfigure the carrier for one transfer.
During and after a call
A successful create request returns a run ID while the call is still starting. Use that ID to follow the call, then read its transcript, tool receipts, recording and analysis. For a booking, check the reservation response before telling a customer it succeeded. See run review.
Phone tools must wait for their result (waitForResult: true), and transfer destinations must be predefined. Validation also reports unsupported speech or storage settings. Resolve those diagnostics before publishing.
Recordings and analysis can become ready after the run ends. Check their individual states, and use recording URLs only for authorized playback; they expire. Runtime helpers provide bounded waits for these outputs.
Voices
Read GET /api/v1/voices for available speech models and voices, then select a compatible profile on the agent. Your administrator configures the provider credentials and language support for the environment. Test speech in the browser before checking the carrier path.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/voices | voices_list | viewer | List available speech models and text-to-speech voices for agent configuration. |
POST /api/v1/voices/preview | voices_preview | member | Preview a fixed English or Spanish line with configured voice, model, speed and expressiveness; does not run an agent |