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

accountSlug

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

name

string

required

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

templateId

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"
  }
}

success

boolean

true when the assistant was created successfully.

assistant.id

string

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

assistant.account_id

string

The account this assistant belongs to.

assistant.name

string

The name you provided.

assistant.type

string

The template type used to create the assistant.

assistant.model

string

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

assistant.provider

string

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

assistant.temperature

number

LLM sampling temperature. Higher values produce more varied output.

assistant.max_tokens

integer

Maximum tokens per LLM response.

assistant.first_message

string

The first thing the assistant says when a call connects.

assistant.system_prompt

string

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

assistant.voice_provider

string

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

assistant.voice_model

string

The voice model identifier for the selected TTS provider.

assistant.voice_id

string

The specific voice ID within the provider.

assistant.voice_name

string

Human-readable name for the selected voice.

assistant.transcriptor_provider

string

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

assistant.transcriptor_model

string

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

assistant.transcriptor_language

string

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

assistant.recording_enabled

boolean

Whether call recording is active for this assistant.

assistant.inbound_enabled

boolean

Whether this assistant can receive inbound calls.

assistant.outbound_enabled

boolean

Whether this assistant can place outbound calls.

assistant.created_at

string

ISO 8601 timestamp of when the assistant was created.

assistant.updated_at

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

assistantId

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

assistantId

string

required

The unique ID of the assistant to update.

Request body

accountSlug

string

required

Your account slug. Required to verify ownership.

name

string

Updated assistant name.

first_message

string

The opening line the assistant speaks when a call connects.

system_prompt

string

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

provider

string

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

model

string

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

temperature

number

Sampling temperature for the LLM (0.0–2.0).

max_tokens

integer

Maximum tokens per LLM completion.

voice_provider

string

TTS provider. Supported values: cartesia, elevenlabs.

voice_model

string

Voice model identifier for the selected TTS provider.

voice_id

string

Specific voice ID within the TTS provider.

voice_name

string

Human-readable label for the voice.

transcriptor_provider

string

STT provider. Supported values include deepgram, assemblyai.

transcriptor_model

string

Transcription model (for example, nova-2).

transcriptor_language

string

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

recording_enabled

boolean

Enable or disable stereo call recording.

inbound_enabled

boolean

Allow this assistant to handle inbound calls.

outbound_enabled

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

assistantId

string

required

The unique ID of the assistant.

Request body

accountSlug

string

required

Your account slug.

phoneNumberIds

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

Overview

Endpoints

Webhooks

Documentation Index

​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