Call Commands

Start AI Assistant

Changed on

Start an AI assistant on the call.

Expected Webhooks:

  • call.conversation.created includes conversation_id during startup
  • call.conversation.ended
  • call.conversation_insights.generated
post/calls/{call_control_id}/actions/ai_assistant_start

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_start
  • Auth: HTTP bearer

Path parameters

call_control_idstring required

Unique identifier and token for controlling the call

Request body

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 call.ai_gather.message_history_updated webhook carrying the full message history is sent each time the conversation message history is updated. The assistant's own telephony_settings.send_message_history_updates overrides this value when it is set.

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.

Example request

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

Response

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

Example response

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

Changes

  • 279d149de88fRevision changes
    • info

      added the new speechmatics/linden-1 enum value to the request property //

    • info

      added the new speechmatics/linden-1 enum value to the request property /

  • bf888fe6e3fbRevision changes
    • warning

      removed the request property

    • warning

      removed the request property