Create an assistant

POST 
/ai/assistants

Create a new AI Assistant.

application/json

Body

required

name stringrequired
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

• WebhookTool
• RetrievalTool
• HangupTool
• TransferTool
• DTMFTool
• BookAppointmentTool
• CheckAvailabilityTool

type stringrequired

Possible values: [webhook]

webhook

object

required

name stringrequired

The name of the tool.

description stringrequired

The description of the tool.

url stringrequired

The URL of the external tool to be called. This URL is going to be used by the assistant. The URL can be templated like: https://example.com/api/v1/{id}, where {id} is a placeholder for a value that will be provided by the assistant if path_parameters are provided with the id attribute.

method string

Possible values: [GET, POST, PUT, DELETE, PATCH]

Default value: POST

The HTTP method to be used when calling the external tool.

headers

object[]

The headers to be sent to the external tool.

Array [

name string

value string

The value of the header. Note that we support mustache templating for the value. For example you can use Bearer {{#integration_secret}}test-secret{{/integration_secret}} to pass the value of the integration secret as the bearer token.

]

The headers to be sent to the external tool.

body_parameters

object

The body parameters the webhook tool accepts, described as a JSON Schema object. These parameters will be passed to the webhook as the body of the request. See the JSON Schema reference for documentation about the format

properties object

The properties of the body parameters.

required string[]

The required properties of the body parameters.

type string

Possible values: [object]

path_parameters

object

The path parameters the webhook tool accepts, described as a JSON Schema object. These parameters will be passed to the webhook as the path of the request if the URL contains a placeholder for a value. See the JSON Schema reference for documentation about the format

properties object

The properties of the path parameters.

required string[]

The required properties of the path parameters.

type string

Possible values: [object]

query_parameters

object

The query parameters the webhook tool accepts, described as a JSON Schema object. These parameters will be passed to the webhook as the query of the request. See the JSON Schema reference for documentation about the format

properties object

The properties of the query parameters.

required string[]

The required properties of the query parameters.

type string

Possible values: [object]

type stringrequired

Possible values: [retrieval]

retrieval

object

required

bucket_ids string[]required

List of embedded storage buckets to use for retrieval-augmented generation.

max_num_results integer

The maximum number of results to retrieve as context for the language model.

type stringrequired

Possible values: [hangup]

hangup

object

required

description string

Default value: This tool is used to hang up the call.

The description of the function that will be passed to the assistant.

type stringrequired

Possible values: [transfer]

transfer

object

required

targets

object[]

required

The different possible targets of the transfer. The assistant will be able to choose one of the targets to transfer the call to.

Array [

name string

The name of the target.

to string

The destination number or SIP URI of the call.

]

The different possible targets of the transfer. The assistant will be able to choose one of the targets to transfer the call to.

from stringrequired

Number or SIP URI placing the call.

type stringrequired

Possible values: [send_dtmf]

send_dtmf objectrequired

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.

type stringrequired

Possible values: [check_availability]

check_availability

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.

]

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

200: Successful Response

application/json

• Schema
• Example (from schema)

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

• WebhookTool
• RetrievalTool
• HangupTool
• TransferTool
• DTMFTool
• BookAppointmentTool
• CheckAvailabilityTool

type stringrequired

Possible values: [webhook]

webhook

object

required

name stringrequired

The name of the tool.

description stringrequired

The description of the tool.

url stringrequired

The URL of the external tool to be called. This URL is going to be used by the assistant. The URL can be templated like: https://example.com/api/v1/{id}, where {id} is a placeholder for a value that will be provided by the assistant if path_parameters are provided with the id attribute.

method string

Possible values: [GET, POST, PUT, DELETE, PATCH]

Default value: POST

The HTTP method to be used when calling the external tool.

headers

object[]

The headers to be sent to the external tool.

Array [

name string

value string

The value of the header. Note that we support mustache templating for the value. For example you can use Bearer {{#integration_secret}}test-secret{{/integration_secret}} to pass the value of the integration secret as the bearer token.

]

The headers to be sent to the external tool.

body_parameters

object

The body parameters the webhook tool accepts, described as a JSON Schema object. These parameters will be passed to the webhook as the body of the request. See the JSON Schema reference for documentation about the format

properties object

The properties of the body parameters.

required string[]

The required properties of the body parameters.

type string

Possible values: [object]

path_parameters

object

The path parameters the webhook tool accepts, described as a JSON Schema object. These parameters will be passed to the webhook as the path of the request if the URL contains a placeholder for a value. See the JSON Schema reference for documentation about the format

properties object

The properties of the path parameters.

required string[]

The required properties of the path parameters.

type string

Possible values: [object]

query_parameters

object

The query parameters the webhook tool accepts, described as a JSON Schema object. These parameters will be passed to the webhook as the query of the request. See the JSON Schema reference for documentation about the format

properties object

The properties of the query parameters.

required string[]

The required properties of the query parameters.

type string

Possible values: [object]

type stringrequired

Possible values: [retrieval]

retrieval

object

required

bucket_ids string[]required

List of embedded storage buckets to use for retrieval-augmented generation.

max_num_results integer

The maximum number of results to retrieve as context for the language model.

type stringrequired

Possible values: [hangup]

hangup

object

required

description string

Default value: This tool is used to hang up the call.

The description of the function that will be passed to the assistant.

type stringrequired

Possible values: [transfer]

transfer

object

required

targets

object[]

required

The different possible targets of the transfer. The assistant will be able to choose one of the targets to transfer the call to.

Array [

name string

The name of the target.

to string

The destination number or SIP URI of the call.

]

The different possible targets of the transfer. The assistant will be able to choose one of the targets to transfer the call to.

from stringrequired

Number or SIP URI placing the call.

type stringrequired

Possible values: [send_dtmf]

send_dtmf objectrequired

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.

type stringrequired

Possible values: [check_availability]

check_availability

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.

]

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

{
  "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": {}
}

422: Validation Error

application/json

• Schema
• Example (from schema)

Schema

detail

object[]

Array [

loc

object[]

required

Array [

anyOf

• MOD1
• MOD2

string

integer

]

msg Message (string)required

type Error Type (string)required

]

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

Request samples

• cURL

---

curl -L 'https://api.telnyx.com/v2/ai/assistants' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "name": "string",
  "model": "string",
  "instructions": "string",
  "tools": [
    {
      "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": "retrieval",
      "retrieval": {
        "bucket_ids": [
          "string"
        ],
        "max_num_results": 0
      }
    },
    {
      "type": "hangup",
      "hangup": {
        "description": "This tool is used to hang up the call."
      }
    },
    {
      "type": "transfer",
      "transfer": {
        "targets": [
          {
            "name": "Support",
            "to": "+13129457420"
          }
        ],
        "from": "+35319605860"
      }
    },
    {
      "type": "send_dtmf",
      "send_dtmf": {}
    },
    {
      "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"
      }
    }
  ],
  "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

• 200
• 422

---

{
  "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": {}
}

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