telnyx-ai-assistants-curl
AI voice assistants with custom instructions, knowledge bases, and tool integrations.
team-telnyx · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add team-telnyx/ai --skill 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
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]andpage[size]query parameters to navigate pages. Checkmeta.total_pagesin 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
| 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. |
| ... | +23 optional params in 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.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
| 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 |
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... |
| ... | +1 optional params in 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:
.data.test_id.data.name.data.destination.data.created_at- `.data.in