/telnyx-ai-assistants-curl

name: telnyx-ai-assistants-curl
description: >-
  AI voice assistants with custom instructions, knowledge bases, and tool
  integrations.
metadata:
  author: telnyx
  product: ai-assistants
  language: curl
  generated_by: telnyx-openapi-pipeline
  contract: v2

<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx AI Assistants - curl

Installation

# curl is pre-installed on macOS, Linux, and Windows 10+

Setup

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

All examples below use `$TELNYX_API_KEY` for authentication.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "my-resource",
      "instructions": "You are a helpful assistant.",
      "model": "openai/gpt-4o"
  }' \
  "https://api.telnyx.com/v2/ai/assistants"

Common error codes: `401` invalid API key, `403` insufficient permissions, `404` resource not found, `422` validation error (check field formats), `429` rate limited (retry with exponential backoff).

Important Notes

• **Phone numbers** must be in E.164 format (e.g., `+13125550001`). Include the `+` prefix and country code. No spaces, dashes, or parentheses.
• **Pagination:** List endpoints return paginated results. Use `page[number]` and `page[size]` query parameters to navigate pages. Check `meta.total_pages` in the response.

Reference Use Rules

Do not invent Telnyx parameters, enums, response fields, or webhook fields.

• If the parameter, enum, or response field you need is not shown inline in this skill, read [references/api-details.md](references/api-details.md) before writing code.
• Before using any operation in `## Additional Operations`, read [the optional-parameters section](references/api-details.md#optional-parameters) and [the response-schemas section](references/api-details.md#response-schemas).

Core Tasks

Create an assistant

Assistant creation is the entrypoint for any AI assistant integration. Agents need the exact creation method and the top-level fields returned by the SDK.

`POST /ai/assistants`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | | | `instructions` | string | Yes | System instructions for the assistant. | | `tags` | array[string] | No | Tags associated with the assistant. | | `model` | string | No | ID of the model to use when `external_llm` is not set. | | `tools` | array[object] | No | Deprecated for new integrations. | | ... | | | +28 optional params in [references/api-details.md](references/api-details.md) |

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "my-resource",
      "instructions": "You are a helpful assistant.",
      "model": "openai/gpt-4o"
  }' \
  "https://api.telnyx.com/v2/ai/assistants"

Primary response fields:

• `.data.id`
• `.data.name`
• `.data.model`
• `.data.instructions`
• `.data.created_at`
• `.data.a2a_agents`

Chat with an assistant

Chat is the primary runtime path. Agents need the exact assistant method and the response content field.

`POST /ai/assistants/{assistant_id}/chat`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | string | Yes | The message content sent by the client to the assistant | | `conversation_id` | string (UUID) | Yes | A unique identifier for the conversation thread, used to mai... | | `assistant_id` | string (UUID) | Yes | Unique identifier of the assistant. | | `name` | string | No | The optional display name of the user sending the message | | `stream` | boolean | No | When true, the response is streamed as Server-Sent Events (`... |

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "Tell me a joke about cats",
  "conversation_id": "42b20469-1215-4a9a-8964-c36f66b406f4"
}' \
  "https://api.telnyx.com/v2/ai/assistants/550e8400-e29b-41d4-a716-446655440000/chat"

Primary response fields:

• `.data.content`

Create an assistant test

Test creation is the main validation path for production assistant behavior before deployment.

`POST /ai/assistants/tests`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | A descriptive name for the assistant test. | | `destination` | string | Yes | The target destination for the test conversation. | | `instructions` | string | Yes | Detailed instructions that define the test scenario and what... | | `rubric` | array[object] | Yes | Evaluation criteria used to assess the assistant's performan... | | `description` | string | No | Optional detailed description of what this test evaluates an... | | `telnyx_conversation_channel` | object | No | The communication channel through which the test will be con... | | `max_duration_seconds` | integer | No | Maximum duration in seconds that the test conversation shoul... | | ... | | | +2 optional params in [references/api-details.md](references/api-details.md) |

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Customer Support Bot Test",
  "destination": "+15551234567",
  "instructions": "Act as a frustrated customer who received a damaged product. Ask for a refund and escalate if not satisfied with the initial response.",
  "rubric": [
    {
      "criteria": "Assistant responds within 30 seconds",
      "name": "Response Time"
    },
    {
      "criteria": "Provides correct product information",
      "name": "Accuracy"
    }
  ]
}' \
  "https://api.telnyx.com/v2/ai/assistants/tests"

Primary response fields: