Telephony

curl -X POST "https://app.talkturo.com/api/assistants/6f8f2a40-89bf-4fd8-94ab-c7c8a7d1e190/telephony/test-call" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example; sb-refresh-token=rt_example_93kmd8pz" \
  --data '{
    "accountSlug": "acme-sales",
    "fromNumber": "+14155550120",
    "toNumber": "+14155550199"
  }'

const response = await fetch(
  "https://app.talkturo.com/api/assistants/6f8f2a40-89bf-4fd8-94ab-c7c8a7d1e190/telephony/test-call",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Cookie": "sb-access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example; sb-refresh-token=rt_example_93kmd8pz"
    },
    body: JSON.stringify({
      accountSlug: "acme-sales",
      fromNumber: "+14155550120",
      toNumber: "+14155550199"
    })
  }
);

const data = await response.json();
console.log(data);

{
  "success": true,
  "roomName": "assistant-6f8f2a40-89bf-4fd8-94ab-c7c8a7d1e190-test-call-9d2a7e4b",
  "sipCallId": "sip_7f3db90ac44e",
  "message": "Test call initiated successfully"
}

{
  "success": false,
  "error": "Insufficient credits"
}

Telephony endpoints

Manage an assistant's calling configuration, attached phone numbers, outbound test calls, and compliance templates from the telephony API. All telephony routes are scoped to a single assistant and require an authenticated browser session.

Base path

/api/assistants/[assistantId]/telephony

Endpoint summary

POST test-call

Start a test outbound call from a phone number already assigned to the assistant. The endpoint creates a room, dispatches the agent, and then creates the outbound SIP participant.

Path parameters

Request body

Request example

Response fields

Validation rules

The test call endpoint rejects requests unless all of the following are true:

• Outbound calling is enabled for the assistant.
• The assistant has a valid livekit_outbound_trunk_id.
• fromNumber is active.
• fromNumber is assigned to the assistant.
• The authenticated user has access to the account identified by accountSlug.

Execution flow

When the request passes validation, Talkturo runs the call setup in this order:

1. Create a LiveKit room.
2. Dispatch the assistant agent into the room.
3. Create the outbound SIP participant.

If the request succeeds, the response includes both the room name and SIP call identifier.

POST inbound

Toggle inbound calling on or off for an assistant. When enabled, provisions a LiveKit inbound SIP trunk and dispatch rule. When disabled, tears them down.

Path parameters

Body parameters

Response fields

POST outbound

Toggle outbound calling on or off for an assistant. When enabled, provisions a LiveKit outbound SIP trunk. When disabled, tears it down.

Path parameters

Body parameters

Response fields

POST settings

The main telephony settings endpoint. Assigns phone numbers, sets the Telnyx FQDN connection, enables or disables inbound and outbound calling, provisions LiveKit SIP trunks, and optionally configures voicemail detection and compliance briefing.

Path parameters

Body parameters

Response fields

GET and PATCH phone-numbers

List phone numbers available to the assistant, or assign phone numbers to the assistant. The GET method returns numbers that are active and either unassigned or already assigned to this assistant. The PATCH method replaces the assistant's phone-number assignments.

Path parameters

GET query parameters

PATCH body parameters

GET response fields

PATCH response fields

POST assign-phone-numbers

Assign one or more phone numbers to an assistant. Use this endpoint when numbers already exist in the account and need to be attached to a specific assistant for inbound or outbound use.

Path parameters

Expected behavior

Call this route after provisioning or selecting numbers elsewhere in the account. Once a number is assigned and active, you can use it in assistant telephony workflows such as inbound routing and outbound test calls.

GET compliance-templates

Return the compliance templates available for telephony configuration. Use this endpoint when your phone-number or carrier workflow requires a predefined compliance template.

Path parameters

Response fields

Expected behavior

Fetch compliance templates before presenting telephony compliance choices in your application. This keeps your UI aligned with the templates currently available in Talkturo.

Common integration notes

A successful telephony integration usually follows this order:

1. Configure inbound or outbound settings for the assistant.
2. Attach or assign the phone numbers the assistant will use.
3. Fetch compliance templates if your setup requires regulated number provisioning.
4. Run a test outbound call to verify the assistant, number assignment, and trunk configuration together.

Common failure cases

• 401 or 403 — the request was sent without a valid authenticated session or without access to the target account.
• 402 — the account does not have enough credits to run an outbound test call.
• Validation failure on test-call — outbound telephony is disabled, the outbound trunk is missing or invalid, or fromNumber is not active and assigned to the assistant.

Related telephony context

Talkturo also exposes an account-level session-auth endpoint outside the assistant telephony namespace:

• GET /api/assistant-phone-numbers — lists phone numbers attached to an assistant across the account.

Use the assistant-scoped telephony routes on this page for configuration changes tied to one assistant. Use the account-level listing route when you need a broader lookup across the account.

Account-level telephony endpoints

Manage telephony provider configuration, regional availability, and regulatory compliance at the account level. These routes are separate from assistant-scoped telephony endpoints and require session cookie authentication unless noted otherwise.

Endpoint summary

Telephony account

Use GET, POST, and PATCH on /api/telephony/account to manage the account's telephony provider configuration, including connection IDs, credentials, and provider-specific settings.

Request fields

Response fields

Telephony regions

Use GET /api/telephony/regions to retrieve regions and providers available for phone number provisioning. This endpoint is public and accepts country and provider query parameters to narrow the results.

Query parameters

Response fields

Telephony regulatory

Use GET and POST on /api/telephony/regulatory to manage regulatory requirements for phone number provisioning. The GET method retrieves requirements for a country and number type, while POST submits the compliance data needed to satisfy those requirements.

GET query parameters

POST body parameters

Response fields