v52

OpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 MB

Call Commands

Start AI Assistant

Start an AI assistant on the call.

Expected Webhooks:

call.conversation.ended
call.conversation_insights.generated

post/calls/{call_control_id}/actions/ai_assistant_start

Path parameters

call_control_idstring required

Unique identifier and token for controlling the call

Request body

client_statestring

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

command_idstring

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

greetingstring

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.

send_message_history_updatesboolean

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

Example request

{
  "assistant": {
    "dynamic_variables": {
      "account_id": "ACC-12345",
      "customer_name": "John"
    },
    "instructions": "You are a friendly voice assistant.",
    "llm_api_key_ref": "my_llm_api_key",
    "model": "gpt-4o",
    "openai_api_key_ref": "my_openai_api_key",
    "tools": [
      {
        "book_appointment": {
          "api_key_ref": "my_calcom_api_key"
        }
      }
    ]
  },
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  "greeting": "Hello, can you tell me your age and where you live?",
  "message_history": [
    {
      "content": "Hello, I would like some help.",
      "role": "user"
    }
  ],
  "participants": [
    {
      "id": "v3:abc123def456",
      "name": "John Doe",
      "on_hangup": "continue_conversation",
      "role": "user"
    }
  ],
  "transcription": {
    "language": "auto",
    "model": "distil-whisper/distil-large-v2"
  }
}

Response

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

Example response

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