telnyx-ai-assistants-curl

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 before writing code.
• Before using any operation in ## Additional Operations, read the optional-parameters section and the response-schemas section.

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

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.conversation_flow

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

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

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:

• .data.test_id
• .data.name
• .data.destination
• .data.created_at
• .data.instructions
• .data.description

Important Supporting Operations

Use these when the core tasks above are close to your flow, but you need a common variation or follow-up step.

Get an assistant

Fetch the current state before updating, deleting, or making control-flow decisions.

GET /ai/assistants/{assistant_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/assistants/550e8400-e29b-41d4-a716-446655440000"

Primary response fields:

• .data.id
• .data.name
• .data.created_at
• .data.conversation_flow
• .data.description
• .data.dynamic_variables

Update an assistant

Create or provision an additional resource when the core tasks do not cover this flow.

POST /ai/assistants/{assistant_id}

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/assistants/550e8400-e29b-41d4-a716-446655440000"

Primary response fields:

• .data.id
• .data.name
• .data.created_at
• .data.conversation_flow
• .data.description
• .data.dynamic_variables

List assistants

Inspect available resources or choose an existing resource before mutating it.

GET /ai/assistants

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/assistants"

Response wrapper:

• items: .data

Primary item fields:

• id
• name
• created_at
• conversation_flow
• description
• dynamic_variables

Import assistants from external provider

Import existing assistants from an external provider instead of creating from scratch.

POST /ai/assistants/import

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "elevenlabs",
  "api_key_ref": "my-openai-key"
}' \
  "https://api.telnyx.com/v2/ai/assistants/import"

Response wrapper:

• items: .data

Primary item fields:

• id
• name
• created_at
• conversation_flow
• description
• dynamic_variables

Get All Tags

Inspect available resources or choose an existing resource before mutating it.

GET /ai/assistants/tags

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/assistants/tags"

Primary response fields:

• .data.tags

List assistant tests with pagination

Inspect available resources or choose an existing resource before mutating it.

GET /ai/assistants/tests

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/assistants/tests"

Response wrapper:

• items: .data
• pagination: .meta

Primary item fields:

• name
• created_at
• description
• destination
• instructions
• max_duration_seconds

Get all test suite names

Inspect available resources or choose an existing resource before mutating it.

GET /ai/assistants/tests/test-suites

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/assistants/tests/test-suites"

Response wrapper:

• items: .data

Primary item fields:

• data

Get test suite run history

Fetch the current state before updating, deleting, or making control-flow decisions.

GET /ai/assistants/tests/test-suites/{suite_name}/runs

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/assistants/tests/test-suites/{suite_name}/runs"

Response wrapper:

• items: .data
• pagination: .meta

Primary item fields:

• status
• created_at
• updated_at
• completed_at
• conversation_id
• conversation_insights_id

Additional Operations

Use the core tasks above first. The operations below are indexed here with exact SDK methods and required params; use references/api-details.md for full optional params, response schemas, and lower-frequency webhook payloads. Before using any operation below, read the optional-parameters section and the response-schemas section so you do not guess missing fields.

For exhaustive optional parameters, full response schemas, and complete webhook payloads, see references/api-details.md.