Source: https://docs.cumuluslabs.io/phone
Content version: b85fb305

# 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 {#byoc}

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 {#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 {#connect}

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:

```text
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](/docs/reference/trunks.create) and [number import](/docs/reference/numbers.import) for all fields. Wait until the imported number reports `ready` before assigning it.

For an SDK project, [bindings and integrations](/docs/sdk-bindings) 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`](https://docs.cumuluslabs.io/reference/trunks.list) | `trunks_list` | viewer | List the SIP trunks connected to the current environment. |
| [`POST /api/v1/telephony/trunks`](https://docs.cumuluslabs.io/reference/trunks.create) | `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}`](https://docs.cumuluslabs.io/reference/trunks.update) | `trunks_update` | admin | Change a connected SIP trunk’s settings. |
| [`DELETE /api/v1/telephony/trunks/{trunk_id}`](https://docs.cumuluslabs.io/reference/trunks.delete) | `trunks_delete` | admin | Disconnect a SIP trunk from the environment. |
| [`GET /api/v1/telephony/numbers`](https://docs.cumuluslabs.io/reference/numbers.list) | `numbers_list` | viewer | List imported phone numbers and their agent assignments. |
| [`POST /api/v1/telephony/numbers`](https://docs.cumuluslabs.io/reference/numbers.import) | `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}`](https://docs.cumuluslabs.io/reference/numbers.update) | `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}`](https://docs.cumuluslabs.io/reference/numbers.release) | `numbers_release` | admin | Release an imported number from Talos. |

## Receive incoming calls {#incoming}

1. Enable incoming calls with `PATCH /api/v1/telephony/trunks/{trunk_id}` and `{"inbound":true}`.
2. Copy the returned `inbound_sip_uri` into the trunk's enabled Origination destination in Twilio.
3. Confirm that the called number is attached to that carrier trunk and is imported and `ready` in Cumulus.
4. Assign the published agent with `PATCH /api/v1/telephony/numbers/{number_id}` and `{"inbound_agent_id":"<agent_id>"}`.
5. 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 {#incoming-test}

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](/docs/testing) explains how to keep tool calls on sandbox services.

### Load caller context {#incoming-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:

```json
[
  { "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:

```json
{ "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](/docs/sdk-tutorial) shows how.


## Private keypad identity verification {#private-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](/docs/sdk-private) explains the policy, required exits and failure behavior.

## Private keypad tokenization {#private-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](/docs/sdk-private) for endpoint authentication, consent, recording privacy and recovery.

## Caller ID: from {#caller-id}

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](/docs/api#phone-call) 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 {#calls}

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](/docs/investigate-runs).

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](/docs/sdk-runtime) provide bounded waits for these outputs.

## Voices {#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`](https://docs.cumuluslabs.io/reference/voices.list) | `voices_list` | viewer | List available speech models and text-to-speech voices for agent configuration. |
| [`POST /api/v1/voices/preview`](https://docs.cumuluslabs.io/reference/voices.preview) | `voices_preview` | member | Preview a fixed English or Spanish line with configured voice, model, speed and expressiveness; does not run an agent |
