REST API endpoints for assistants

Assistants are the AI agents that handle your phone calls. Each assistant has its own system prompt, LLM configuration, voice settings, and transcription options. You can create assistants from a template to get sensible defaults quickly, then update individual fields as needed. Once an assistant is configured, you assign phone numbers to it so it can receive inbound calls or place outbound calls through a campaign.

Create an assistant

POST /api/assistants Creates a new assistant with default configuration. Use a templateId to pre-populate common settings, or start with custom and configure everything yourself via PATCH.

Request body

string

required

The slug identifier for your account or workspace. You can find this in your dashboard URL (for example, my-team in https://app.talkturo.com/home/my-team).

string

required

A human-readable name for the assistant (for example, "Sales Agent" or "Support Bot").

string

Pre-populates the assistant with a starter configuration. Accepted values: outbound-setter, inbound-support, follow-up, custom. Defaults to custom if omitted.

Example request

curl -X POST https://<your-domain>/api/assistants \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "my-team",
    "name": "Q1 Outbound Setter",
    "templateId": "outbound-setter"
  }'

Response

{
  "success": true,
  "assistant": {
    "id": "asst_01j...",
    "account_id": "acct_...",
    "name": "Q1 Outbound Setter",
    "type": "outbound-setter",
    "model": "gpt-4o-mini",
    "provider": "openai",
    "temperature": 0.7,
    "max_tokens": 1024,
    "first_message": "Hi, this is Alex from Talkturo...",
    "system_prompt": "You are a friendly outbound sales assistant...",
    "voice_provider": "cartesia",
    "voice_model": "sonic-english",
    "voice_id": "...",
    "voice_name": "Alex",
    "transcriptor_provider": "deepgram",
    "transcriptor_model": "nova-2",
    "transcriptor_language": "en",
    "recording_enabled": true,
    "inbound_enabled": false,
    "outbound_enabled": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

boolean

true when the assistant was created successfully.

string

Unique identifier for the assistant. Use this in subsequent GET and PATCH requests.

string

The account this assistant belongs to.

string

The name you provided.

string

The template type used to create the assistant.

string

The LLM model identifier (for example, gpt-4o-mini).

string

The LLM provider (for example, openai, anthropic, google).

number

LLM sampling temperature. Higher values produce more varied output.

integer

Maximum tokens per LLM response.

string

The first thing the assistant says when a call connects.

string

The system instructions that define the assistant’s behavior and persona.

string

The TTS provider (for example, cartesia, elevenlabs).

string

The voice model identifier for the selected TTS provider.

string

The specific voice ID within the provider.

string

Human-readable name for the selected voice.

string

The STT provider (for example, deepgram, assemblyai).

string

The transcription model (for example, nova-2).

string

BCP-47 language code for transcription (for example, en, es, fr).

boolean

Whether call recording is active for this assistant.

boolean

Whether this assistant can receive inbound calls.

boolean

Whether this assistant can place outbound calls.

string

ISO 8601 timestamp of when the assistant was created.

string

ISO 8601 timestamp of the most recent update.

Get an assistant

GET /api/assistants/{assistantId} Retrieves the full configuration of a single assistant.

Path parameters

string

required

The unique ID of the assistant to retrieve.

Example request

curl https://<your-domain>/api/assistants/asst_01j... \
  -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "assistant": {
    "id": "asst_01j...",
    "name": "Q1 Outbound Setter",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "system_prompt": "You are a friendly outbound sales assistant...",
    "voice_provider": "cartesia",
    "voice_id": "...",
    "inbound_enabled": false,
    "outbound_enabled": true,
    ...
  }
}

Update an assistant

PATCH /api/assistants/{assistantId} Updates one or more configuration fields on an existing assistant. All fields except accountSlug are optional — include only the fields you want to change.

Path parameters

string

required

The unique ID of the assistant to update.

Request body

string

required

Your account slug. Required to verify ownership.

string

Updated assistant name.

string

The opening line the assistant speaks when a call connects.

string

Updated system instructions. You can use CRM template variables like {{contact.first_name}}.

string

LLM provider. Supported values include openai, anthropic, google, deepseek, qwen.

string

LLM model identifier for the selected provider (for example, gpt-4o, gpt-4o-mini).

number

Sampling temperature for the LLM (0.0–2.0).

integer

Maximum tokens per LLM completion.

string

TTS provider. Supported values: cartesia, elevenlabs.

string

Voice model identifier for the selected TTS provider.

string

Specific voice ID within the TTS provider.

string

Human-readable label for the voice.

string

STT provider. Supported values include deepgram, assemblyai.

string

Transcription model (for example, nova-2).

string

BCP-47 language code for transcription (for example, en, es, fr).

boolean

Enable or disable stereo call recording.

boolean

Allow this assistant to handle inbound calls.

boolean

Allow this assistant to place outbound calls.

Example request

curl -X PATCH https://<your-domain>/api/assistants/asst_01j... \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "my-team",
    "system_prompt": "You are a helpful sales assistant for Acme Corp. Your goal is to qualify leads and book demos.",
    "voice_provider": "elevenlabs",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "recording_enabled": true
  }'

Response

{
  "success": true,
  "assistant": {
    "id": "asst_01j...",
    "name": "Q1 Outbound Setter",
    "system_prompt": "You are a helpful sales assistant for Acme Corp...",
    "voice_provider": "elevenlabs",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "recording_enabled": true,
    ...
  }
}

Assign phone numbers to an assistant

PATCH /api/assistants/{assistantId}/telephony/phone-numbers Assigns or replaces the phone numbers linked to an assistant. Passing an empty array removes all assigned numbers. You can get phone number IDs from the phone numbers endpoints.

Path parameters

string

required

The unique ID of the assistant.

Request body

string

required

Your account slug.

array

required

An array of phone number ID strings to assign to this assistant. This replaces any existing assignments. Pass an empty array ([]) to remove all phone numbers from the assistant.

Example request

curl -X PATCH https://<your-domain>/api/assistants/asst_01j.../telephony/phone-numbers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "my-team",
    "phoneNumberIds": ["pn_01j...", "pn_02k..."]
  }'

Response

{
  "success": true
}

After assigning a phone number, inbound calls to that number will automatically be routed to this assistant. Make sure inbound_enabled is set to true on the assistant if you want it to receive calls.

Overview

Endpoints

Webhooks

REST API endpoints for assistants

Create an assistant

Request body

Example request

Response

Get an assistant

Path parameters

Example request

Response

Update an assistant

Path parameters

Request body

Example request

Response

Assign phone numbers to an assistant

Path parameters

Request body

Example request

Response

​Create an assistant

​Request body

​Example request

​Response

​Get an assistant

​Path parameters

​Example request

​Response

​Update an assistant

​Path parameters

​Request body

​Example request

​Response

​Assign phone numbers to an assistant

​Path parameters

​Request body

​Example request

​Response

Create an assistant

Request body

Example request

Response

Get an assistant

Path parameters

Example request

Response

Update an assistant

Path parameters

Request body

Example request

Response

Assign phone numbers to an assistant

Path parameters

Request body

Example request

Response