REST-API-Endpunkte für Assistenten

Assistenten sind die KI-Agenten für Ihre Telefonate. Jeder Assistent hat eigenes System-Prompt, LLM-Konfiguration, Stimmeneinstellungen und Transkriptionsoptionen. Über eine Vorlage (templateId) erhalten Sie sinnvolle Defaults und passen danach einzelne Felder per PATCH an. Ist der Assistent fertig, weisen Sie Telefonnummern zu — für eingehende Anrufe oder ausgehende Kampagnen.

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

erforderlich

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

erforderlich

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

Antwort

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

erforderlich

The unique ID of the assistant to retrieve.

Example request

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

Antwort

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

erforderlich

The unique ID of the assistant to update.

Request body

string

erforderlich

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

Antwort

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

erforderlich

The unique ID of the assistant.

Request body

string

erforderlich

Your account slug.

array

erforderlich

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..."]
  }'

Antwort

{
  "success": true
}

Nach der Zuweisung einer Telefonnummer werden eingehende Anrufe an diese Nummer automatisch an diesen Assistenten weitergeleitet. Stellen Sie sicher, dass inbound_enabled beim Assistenten auf true steht, wenn er Anrufe empfangen soll.

Überblick

Endpunkte

Webhooks

REST-API-Endpunkte für Assistenten

Create an assistant

Request body

Example request

Antwort

Get an assistant

Path parameters

Example request

Antwort

Update an assistant

Path parameters

Request body

Example request

Antwort

Assign phone numbers to an assistant

Path parameters

Request body

Example request

Antwort

​Create an assistant

​Request body

​Example request

​Antwort

​Get an assistant

​Path parameters

​Example request

​Antwort

​Update an assistant

​Path parameters

​Request body

​Example request

​Antwort

​Assign phone numbers to an assistant

​Path parameters

​Request body

​Example request

​Antwort

Create an assistant

Request body

Example request

Antwort

Get an assistant

Path parameters

Example request

Antwort

Update an assistant

Path parameters

Request body

Example request

Antwort

Assign phone numbers to an assistant

Path parameters

Request body

Example request

Antwort