Import assistants from external provider

POST 
/ai/assistants/import

Import assistants from external providers. Any assistant that has already been imported will be overwritten with its latest version from the importing provider.

application/json

Body

required

provider stringrequired

Possible values: [elevenlabs, vapi]

The external provider to import assistants from.

api_key_ref stringrequired

Integration secret pointer that refers to the API key for the external provider. This should be an identifier for an integration secret created via /v2/integration_secrets.

200: Successful Response

application/json

• Schema
• Example (from schema)

Schema

data

object[]

required

Array [

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
• HandoffTool
• HangupTool
• TransferTool
• SIPReferTool
• DTMFTool

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.

The handoff tool allows the assistant to hand off control of the conversation to another AI assistant. By default, this will happen transparently to the end user.

type stringrequired

Possible values: [handoff]

handoff

object

required

ai_assistants

object[]

required

List of possible assistants that can receive a handoff.

Array [

name stringrequired

Helpful name for giving context on when to handoff to the assistant.

id stringrequired

The ID of the assistant to hand off to.

]

List of possible assistants that can receive a handoff.

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.

custom_headers

object[]

Custom headers to be added to the SIP INVITE for the transfer command.

Array [

name string

value string

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

]

Custom headers to be added to the SIP INVITE for the transfer command.

type stringrequired

Possible values: [refer]

refer

object

required

targets

object[]

required

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

Array [

name stringrequired

The name of the target.

sip_address stringrequired

The SIP URI to which the call will be referred.

sip_auth_username string

SIP Authentication username used for SIP challenges.

sip_auth_password string

SIP Authentication password used for SIP challenges.

]

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

sip_headers

object[]

SIP headers to be added to the SIP REFER. Currently only User-to-User and Diversion headers are supported.

Array [

name string

Possible values: [User-to-User, Diversion]

value string

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

]

SIP headers to be added to the SIP REFER. Currently only User-to-User and Diversion headers are supported.

custom_headers

object[]

Custom headers to be added to the SIP REFER.

Array [

name string

value string

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

]

Custom headers to be added to the SIP REFER.

type stringrequired

Possible values: [send_dtmf]

send_dtmf objectrequired

]

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)

voice_speed number

Default value: 1

The speed of the voice in the range [0.25, 2.0]. 1.0 is deafult speed. Larger numbers make the voice faster, smaller numbers make it slower. This is only applicable for Telnyx Natural voices.

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.

language string

The language of the audio to be transcribed. This is only applicable for openai/whisper-large-v3-turbo model. If not set, of if set to auto, the model will automatically detect the language. For the full list of supported languages, see the whisper tokenizer.

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.

privacy_settings

object

data_retention boolean

If true, conversation history and insights will be stored. If false, they will not be stored. This in‑tool toggle governs solely the retention of conversation history and insights via the AI assistant. It has no effect on any separate recording, transcription, or storage configuration that you have set at the account, number, or application level. All such external settings remain in force regardless of your selection here.

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

import_metadata

object

import_provider string

Possible values: [elevenlabs, vapi]

Provider the assistant was imported from.

import_id string

ID of the assistant in the provider's system.

]

{
  "data": [
    {
      "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",
        "voice_speed": 1,
        "api_key_ref": "string"
      },
      "transcription": {
        "model": "string",
        "language": "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"
      },
      "privacy_settings": {
        "data_retention": true
      },
      "dynamic_variables_webhook_url": "string",
      "dynamic_variables": {},
      "import_metadata": {
        "import_provider": "elevenlabs",
        "import_id": "string"
      }
    }
  ]
}

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/import' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "provider": "elevenlabs",
  "api_key_ref": "string"
}'

Response samples

• 200
• 422

---

{
  "data": [
    {
      "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",
        "voice_speed": 1,
        "api_key_ref": "string"
      },
      "transcription": {
        "model": "string",
        "language": "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"
      },
      "privacy_settings": {
        "data_retention": true
      },
      "dynamic_variables_webhook_url": "string",
      "dynamic_variables": {},
      "import_metadata": {
        "import_provider": "elevenlabs",
        "import_id": "string"
      }
    }
  ]
}

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