Skip to main content

Update an assistant

POST 
/ai/assistants/:assistant_id

Update an AI Assistant's attributes.

Request ​

Path Parameters

    assistant_id Assistant Idrequired

Body

required

    name string
    model string

    ID of the model to use. You can use the Get models API to see all of your available models,

    instructions string

    System instructions for the assistant. These may be templated with dynamic variables

    tools

    object[]

    The tools that the assistant can use. These may be templated with dynamic variables

  • Array [

    • oneOf

    type stringrequired

    Possible values: [book_appointment]

    book_appointment

    object

    required

    event_type_id integerrequired

    Event Type ID for which slots are being fetched. cal.com

    api_key_ref stringrequired

    Reference to an integration secret that contains your Cal.com API key. You would pass the identifier for an integration secret /v2/integration_secrets that refers to your Cal.com API key.

    attendee_name string

    The name of the attendee cal.com. If not provided, the assistant will ask for the attendee's name.

    attendee_timezone string

    The timezone of the attendee cal.com. If not provided, the assistant will ask for the attendee's timezone.

  • ]

    • description string
    greeting string

    Text that the assistant will use to start the conversation. This may be templated with dynamic variables

    llm_api_key_ref string

    This is only needed when using third-party inference providers. The identifier for an integration secret /v2/integration_secrets that refers to your LLM provider's API key. Warning: Free plans are unlikely to work with this integration.

    voice_settings

    object

    voice stringrequired

    The voice to be used by the voice assistant. Check the full list of available voices via our voices API. To use ElevenLabs, you must reference your ElevenLabs API key as an integration secret under the api_key_ref field. See integration secrets documentation for details. For Telnyx voices, use Telnyx.<model_id>.<voice_id> (e.g. Telnyx.KokoroTTS.af_heart)

    api_key_ref string

    The identifier for an integration secret /v2/integration_secrets that refers to your ElevenLabs API key. Warning: Free plans are unlikely to work with this integration.

    transcription

    object

    model string

    The speech to text model to be used by the voice assistant.

    • distil-whisper/distil-large-v2 is lower latency but English-only.
    • openai/whisper-large-v3-turbo is multi-lingual with automatic language detection but slightly higher latency.

    telephony_settings

    object

    default_texml_app_id string

    Default Texml App used for voice calls with your assistant. This will be created automatically on assistant creation.

    messaging_settings

    object

    default_messaging_profile_id string

    Default Messaging Profile used for messaging exchanges with your assistant. This will be created automatically on assistant creation.

    delivery_status_webhook_url string

    The URL where webhooks related to delivery statused for assistant messages will be sent.

    enabled_features EnabledFeatures (string)[]

    Possible values: [telephony, messaging]

    insight_settings

    object

    insight_group_id string

    Reference to an Insight Group. Insights in this group will be run automatically for all the assistant's conversations.

    dynamic_variables_webhook_url string

    If the dynamic_variables_webhook_url is set for the assistant, we will send a request at the start of the conversation. See our guide for more information.

    dynamic_variables object

    Map of dynamic variables and their default values

Responses ​

200: Successful Response

Schema

    any

422: Validation Error

Schema

    detail

    object[]

  • Array [

    • loc

    object[]

    required

  • Array [

    • anyOf

    string

  • ]

    • msg Message (string)required
    type Error Type (string)required

  • ]

Request samples

curl -L 'https://api.telnyx.com/v2/ai/assistants/:assistant_id' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "name": "string",
  "model": "string",
  "instructions": "string",
  "tools": [
    {
      "type": "book_appointment",
      "book_appointment": {
        "event_type_id": 0,
        "api_key_ref": "my_calcom_api_key",
        "attendee_name": "string",
        "attendee_timezone": "string"
      }
    },
    {
      "type": "check_availability",
      "check_availability": {
        "event_type_id": 0,
        "api_key_ref": "my_calcom_api_key"
      }
    },
    {
      "type": "webhook",
      "webhook": {
        "name": "string",
        "description": "string",
        "url": "https://example.com/api/v1/function",
        "method": "POST",
        "headers": [
          {
            "name": "string",
            "value": "string"
          }
        ],
        "body_parameters": {
          "properties": {
            "age": {
              "description": "The age of the customer.",
              "type": "integer"
            },
            "location": {
              "description": "The location of the customer.",
              "type": "string"
            }
          },
          "required": [
            "age",
            "location"
          ],
          "type": "object"
        },
        "path_parameters": {
          "properties": {
            "id": {
              "description": "The id of the customer.",
              "type": "string"
            }
          },
          "required": [
            "id"
          ],
          "type": "object"
        },
        "query_parameters": {
          "properties": {
            "page": {
              "description": "The page number.",
              "type": "integer"
            }
          },
          "required": [
            "page"
          ],
          "type": "object"
        }
      }
    },
    {
      "type": "hangup",
      "hangup": {
        "description": "This tool is used to hang up the call."
      }
    },
    {
      "type": "transfer",
      "transfer": {
        "targets": [
          {
            "name": "Support",
            "to": "+13129457420"
          }
        ],
        "from": "+35319605860"
      }
    },
    {
      "type": "retrieval",
      "retrieval": {
        "bucket_ids": [
          "string"
        ],
        "max_num_results": 0
      }
    }
  ],
  "description": "string",
  "greeting": "string",
  "llm_api_key_ref": "string",
  "voice_settings": {
    "voice": "string",
    "api_key_ref": "string"
  },
  "transcription": {
    "model": "string"
  },
  "telephony_settings": {
    "default_texml_app_id": "string"
  },
  "messaging_settings": {
    "default_messaging_profile_id": "string",
    "delivery_status_webhook_url": "string"
  },
  "enabled_features": [
    "telephony"
  ],
  "insight_settings": {
    "insight_group_id": "string"
  },
  "dynamic_variables_webhook_url": "string",
  "dynamic_variables": {}
}'

Response samples

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}