Create an AI assistant

Create an assistant for conversations, support tickets, the help desk, internal AI chat or voice calls.

Endpoint

POST
/ai-assistants

Body

NameTypeRequiredDescription
organization_idintegerYesYour API key's organization ID.
namestringYesDisplay name.
ai_model_idintegerYesModel ID from AI Models.
connectionstringYessystem, organization or specific. The server stores system unless your plan includes your own provider credentials.
assistant_typestringNoconversation, support-ticket, helpdesk, ai-chat or voice.
descriptionstringNoShort description.
instructionsstringNoFull system instructions.
instructions_languagestringNoENG or ESP.
is_easy_modebooleanNoGuided mode. Default true; send false when you write instructions yourself.
easy_mode_configobject | nullNoGuided-mode source. Use null for advanced mode.
timezonestringNoIANA timezone. Default UTC.
specific_openai_secret_keystringNoProvider key used when connection is specific.
telnyx_ai_assistant_configobjectNoVoice configuration. See Configure a voice assistant.

Every other writable field of the AI assistant object can also be sent on create; the same shapes as in Update an AI assistant apply. Unknown top-level fields are rejected.

What the server does on create:

  • Generates version_id.
  • voice assistants get voice_enabled: true and, when you send no voice config, telnyx_ai_assistant_config: { "sync_status": "pending", "voice_mode": "unified" }. The voice agent is then synced with the voice provider.
  • ai-chat and helpdesk assistants get a default internal_tools set (it replaces any internal_tools you send).
  • conversation, support-ticket and ai-chat assistants get advanced_options.conversation_summary_config.enabled: true unless you set it.
  • Media send flags (can_send_images, ...) are turned on when instructions reference media from the assistant media library.
  • created_by_user_id is not filled in for API key requests, and no change history entry is recorded.

Request

Create a voice assistant:

Response

The created AI assistant object (shortened):

json

Errors

StatusWhen
400A required field is missing, a value is outside its enum or range, an unknown top-level field is sent, or a handoff rule references an invalid user or assistant.
403organization_id is not your API key's organization.

Report an issue with this documentation

Please log in to report issues with our documentation.