Start AI Assistant

POST

calls

{call_control_id}

actions

ai_assistant_start

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.calls.actions.startAIAssistant('call_control_id');

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.calls.actions.start_ai_assistant(
    call_control_id="call_control_id",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Calls.Actions.StartAIAssistant(
		context.TODO(),
		"call_control_id",
		telnyx.CallActionStartAIAssistantParams{},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.calls.actions.ActionStartAiAssistantParams;
import com.telnyx.sdk.models.calls.actions.ActionStartAiAssistantResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ActionStartAiAssistantResponse response = client.calls().actions().startAiAssistant("call_control_id");
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->calls->actions->startAIAssistant(
    'call_control_id',
    assistant: [
      'id' => 'id',
      'dynamicVariables' => [
        'customer_name' => 'John', 'account_id' => 'ACC-12345'
      ],
      'externalLlm' => [
        'authenticationMethod' => 'token',
        'baseURL' => 'base_url',
        'certificateRef' => 'certificate_ref',
        'forwardMetadata' => true,
        'llmAPIKeyRef' => 'llm_api_key_ref',
        'model' => 'model',
        'tokenRetrievalURL' => 'token_retrieval_url',
      ],
      'fallbackConfig' => [
        'externalLlm' => [
          'authenticationMethod' => 'token',
          'baseURL' => 'base_url',
          'certificateRef' => 'certificate_ref',
          'forwardMetadata' => true,
          'llmAPIKeyRef' => 'llm_api_key_ref',
          'model' => 'model',
          'tokenRetrievalURL' => 'token_retrieval_url',
        ],
        'llmAPIKeyRef' => 'llm_api_key_ref',
        'model' => 'model',
      ],
      'greeting' => 'greeting',
      'instructions' => 'You are a friendly voice assistant.',
      'llmAPIKeyRef' => 'my_llm_api_key',
      'mcpServers' => [['foo' => 'bar']],
      'model' => 'gpt-4o',
      'name' => 'name',
      'observabilitySettings' => ['foo' => 'bar'],
      'openaiAPIKeyRef' => 'my_openai_api_key',
      'tools' => [
        [
          'bookAppointment' => [
            'apiKeyRef' => 'my_calcom_api_key',
            'eventTypeID' => 0,
            'attendeeName' => 'attendee_name',
            'attendeeTimezone' => 'attendee_timezone',
          ],
          'type' => 'book_appointment',
        ],
      ],
    ],
    clientState: 'aGF2ZSBhIG5pY2UgZGF5ID1d',
    commandID: '891510ac-f3e4-11e8-af5b-de00688a4901',
    greeting: 'Hello, can you tell me your age and where you live?',
    interruptionSettings: ['enable' => true],
    messageHistory: [
      [
        'content' => 'Hello, I would like some help.',
        'role' => 'user',
        'metadata' => ['foo' => 'bar'],
      ],
    ],
    participants: [
      [
        'id' => 'v3:abc123def456',
        'role' => 'user',
        'name' => 'John Doe',
        'onHangup' => 'continue_conversation',
      ],
    ],
    sendMessageHistoryUpdates: true,
    transcription: [
      'language' => 'auto', 'model' => 'distil-whisper/distil-large-v2'
    ],
    voice: 'Telnyx.KokoroTTS.af',
    voiceSettings: [
      'type' => 'elevenlabs', 'apiKeyRef' => 'my_elevenlabs_api_key'
    ],
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "greeting": "Hello, can you tell me your age and where you live?",
  "interruption_settings": {
    "enable": true
  },
  "transcription": {
    "model": "distil-whisper/distil-large-v2",
    "language": "auto"
  },
  "message_history": [],
  "send_message_history_updates": false,
  "participants": [],
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
'

{
  "data": {
    "result": "ok",
    "conversation_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

call_control_id

string

required

Unique identifier and token for controlling the call

Body

application/json

AI Assistant request

assistant

object

AI Assistant configuration. All fields except id are optional — the assistant's stored configuration will be used as fallback for any omitted fields.

Show child attributes

greeting

string

Text that will be played when the assistant starts, if none then nothing will be played when the assistant starts. The greeting can be text for any voice or SSML for AWS.Polly.<voice_id> voices. There is a 3,000 character limit.

Example:

"Hello, can you tell me your age and where you live?"

interruption_settings

object

Settings for handling user interruptions during assistant speech

Show child attributes

transcription

object

The settings associated with speech to text for the voice assistant. This is only relevant if the assistant uses a text-to-text language model. Any assistant using a model with native audio support (e.g. fixie-ai/ultravox-v0_4) will ignore this field.

Show child attributes

message_history

(User message. · object | Assistant Message · object | Tool Message · object | System Message · object | Developer Message · object)[]

A list of messages to seed the conversation history before the assistant starts. Follows the same message format as the ai_assistant_add_messages command.

Messages sent by an end user

User message.
Assistant Message
Tool Message
System Message
Developer Message

Show child attributes

Example:

{
  "role": "user",
  "content": "Hello, I would like some help."
}

send_message_history_updates

boolean

default:false

When true, a webhook is sent each time the conversation message history is updated.

participants

object[]

A list of participants to add to the conversation when it starts.

Show child attributes

client_state

string

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

Example:

"aGF2ZSBhIG5pY2UgZGF5ID1d"

command_id

string

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

Example:

"891510ac-f3e4-11e8-af5b-de00688a4901"

Response

Successful response upon making a call control command that includes conversation_id.

data

Call Control Command Result With Conversation ID · object

Show child attributes

Example:

{
  "result": "ok",
  "conversation_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a"
}

⌘I

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.calls.actions.startAIAssistant('call_control_id');

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.calls.actions.start_ai_assistant(
    call_control_id="call_control_id",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Calls.Actions.StartAIAssistant(
		context.TODO(),
		"call_control_id",
		telnyx.CallActionStartAIAssistantParams{},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.calls.actions.ActionStartAiAssistantParams;
import com.telnyx.sdk.models.calls.actions.ActionStartAiAssistantResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ActionStartAiAssistantResponse response = client.calls().actions().startAiAssistant("call_control_id");
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->calls->actions->startAIAssistant(
    'call_control_id',
    assistant: [
      'id' => 'id',
      'dynamicVariables' => [
        'customer_name' => 'John', 'account_id' => 'ACC-12345'
      ],
      'externalLlm' => [
        'authenticationMethod' => 'token',
        'baseURL' => 'base_url',
        'certificateRef' => 'certificate_ref',
        'forwardMetadata' => true,
        'llmAPIKeyRef' => 'llm_api_key_ref',
        'model' => 'model',
        'tokenRetrievalURL' => 'token_retrieval_url',
      ],
      'fallbackConfig' => [
        'externalLlm' => [
          'authenticationMethod' => 'token',
          'baseURL' => 'base_url',
          'certificateRef' => 'certificate_ref',
          'forwardMetadata' => true,
          'llmAPIKeyRef' => 'llm_api_key_ref',
          'model' => 'model',
          'tokenRetrievalURL' => 'token_retrieval_url',
        ],
        'llmAPIKeyRef' => 'llm_api_key_ref',
        'model' => 'model',
      ],
      'greeting' => 'greeting',
      'instructions' => 'You are a friendly voice assistant.',
      'llmAPIKeyRef' => 'my_llm_api_key',
      'mcpServers' => [['foo' => 'bar']],
      'model' => 'gpt-4o',
      'name' => 'name',
      'observabilitySettings' => ['foo' => 'bar'],
      'openaiAPIKeyRef' => 'my_openai_api_key',
      'tools' => [
        [
          'bookAppointment' => [
            'apiKeyRef' => 'my_calcom_api_key',
            'eventTypeID' => 0,
            'attendeeName' => 'attendee_name',
            'attendeeTimezone' => 'attendee_timezone',
          ],
          'type' => 'book_appointment',
        ],
      ],
    ],
    clientState: 'aGF2ZSBhIG5pY2UgZGF5ID1d',
    commandID: '891510ac-f3e4-11e8-af5b-de00688a4901',
    greeting: 'Hello, can you tell me your age and where you live?',
    interruptionSettings: ['enable' => true],
    messageHistory: [
      [
        'content' => 'Hello, I would like some help.',
        'role' => 'user',
        'metadata' => ['foo' => 'bar'],
      ],
    ],
    participants: [
      [
        'id' => 'v3:abc123def456',
        'role' => 'user',
        'name' => 'John Doe',
        'onHangup' => 'continue_conversation',
      ],
    ],
    sendMessageHistoryUpdates: true,
    transcription: [
      'language' => 'auto', 'model' => 'distil-whisper/distil-large-v2'
    ],
    voice: 'Telnyx.KokoroTTS.af',
    voiceSettings: [
      'type' => 'elevenlabs', 'apiKeyRef' => 'my_elevenlabs_api_key'
    ],
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "greeting": "Hello, can you tell me your age and where you live?",
  "interruption_settings": {
    "enable": true
  },
  "transcription": {
    "model": "distil-whisper/distil-large-v2",
    "language": "auto"
  },
  "message_history": [],
  "send_message_history_updates": false,
  "participants": [],
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
'

{
  "data": {
    "result": "ok",
    "conversation_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a"
  }
}

Voice API Fundamentals

Voice Features

AI Capabilities

Tutorials

Regional & Restrictions

API Reference

For AI Agents

Start AI Assistant

Authorizations

Path Parameters

Body

Response