Skip to main content

Get an assistant

GET 
/ai/assistants/:assistant_id

Retrieve an AI Assistant configuration by assistant_id.

Request ​

Path Parameters

    assistant_id Assistant Idrequired

Query Parameters

    fetch_dynamic_variables_from_webhook Fetch Dynamic Variables From Webhook
    from From
    to To
    call_control_id Call Control Id

Responses ​

200: Successful Response

Schema

    id stringrequired
    name stringrequired
    created_at date-timerequired
    description string
    model stringrequired

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

    instructions stringrequired

    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.

  • ]

    • 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 values

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 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Response samples

{
  "id": "string",
  "name": "string",
  "created_at": "2024-07-29T15:51:28.071Z",
  "description": "string",
  "model": "string",
  "instructions": "string",
  "tools": [
    {},
    {},
    {},
    {},
    {},
    {}
  ],
  "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": {}
}