telnyx-ai-assistants-curl

AI voice assistants with custom instructions, knowledge bases, and tool integrations.

安装

npx skills add team-telnyx/ai

收录说明

来自 team-telnyx/ai（224 stars），仓库最近更新 2026-11-02。尚未人工实测。

SKILL.md 原文

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

# Telnyx AI Assistants - curl

## Installation

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

## Setup

```bash
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:

```bash
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) |

```bash
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 (`... |

```bash
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) |

```bash
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}`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assistant_id` | string (UUID) | Yes | Unique identifier of the assistant. |
| `call_control_id` | string (UUID) | No | Filter results by call control id. |
| `fetch_dynamic_variables_from_webhook` | boolean | No | Whether to fetch dynamic variables from the configured webho... |
| `from` | string (E.164) | No | Start of the filter range. |
| ... | | | +1 optional params in [references/api-details.md](references/api-details.md) |

```bash
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.a2a_agents`
- `.data.avatar_settings`
- `.data.conversation_flow`

### Update an assistant

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

`POST /ai/assistants/{assistant_id}`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assistant_id` | string (UUID) | Yes | Unique identifier of the assistant. |
| `tags` | array[string] | No | Tags associated with the assistant. |
| `name` | string | No |  |
| `model` | string | No | ID of the model to use when `external_llm` is not set. |
| ... | | | +31 optional params in [references/api-details.md](references/api-details.md) |

```bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "instructions": "You are a friendly support assistant for Acme. Keep answers short."
  }' \
  "https://api.telnyx.com/v2/ai/assistants/550e8400-e29b-41d4-a716-446655440000"
```

Primary response fields:
- `.data.id`
- `.data.name`
- `.data.created_at`
- `.data.a2a_agents`
- `.data.avatar_settings`
- `.data.conversation_flow`

### List assistants

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

`GET /ai/assistants`

```bash
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`
- `a2a_agents`
- `avatar_settings`
- `conversation_flow`

### List deleted assistants

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

`GET /ai/assistants/deleted`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page[number]` | integer | No | Page number to retrieve (1-based). |
| `page[size]` | integer | No | Number of items to return per page. |

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

Response wrapper:
- items: `.data`
- pagination: `.meta`

Primary item fields:
- `id`
- `name`
- `created_at`
- `a2a_agents`
- `avatar_settings`
- `conversation_flow`

### Import assistants from external provider

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

`POST /ai/assistants/import`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `provider` | enum (elevenlabs, vapi, retell) | Yes | The external provider to import assistants from. |
| `api_key_ref` | string | Yes | Integration secret pointer that refers to the API key for th... |
| `import_ids` | array[string] | No | Optional list of assistant IDs to import from the external p... |
| `Idempotency-Key` | string | No | Optional opaque, unquoted key for safely retrying the same l... |

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

Response wrapper:
- items: `.data`

Primary item fields:
- `id`
- `name`
- `created_at`
- `a2a_agents`
- `avatar_settings`
- `conversation_flow`

### Get All Tags

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

`GET /ai/assistants/tags`

```bash
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`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `test_suite` | string | No | Filter tests by test suite name |
| `telnyx_conversation_channel` | string | No | Filter tests by communication channel (e.g., 'web_chat', 'sm... |
| `destination` | string | No | Filter tests by destination (phone number, webhook URL, etc.... |
| ... | | | +1 optional params in [references/api-details.md](references/api-details.md) |

```bash
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`

```bash
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`

---

## 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](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](references/api-details.md#optional-parameters) and [the response-schemas section](references/api-details.md#response-schemas) so you do not guess missing fields.

| Operation | SDK method | Endpoint | Use when | Required params |
|-----------|------------|----------|----------|-----------------|
| Get test suite run history | HTTP only | `GET /ai/assistants/tests/test-suites/{suite_name}/runs` | Fetch the current state before updating, deleting, or making control-flow decisions. | `suite_name` |
| Trigger test suite execution | HTTP only | `POST /ai/assistants/tests/test-suites/{suite_name}/runs` | Trigger a follow-up action in an existing workflow rather than creating a new top-level resource. | `suite_name` |
| Get assistant test by ID | HTTP only | `GET /ai/assistants/tests/{test_id}` | Fetch the current state before updating, deleting, or making control-flow decisions. | `test_id` |
| Update an assistant test | HTTP only | `PUT /ai/assistants/tests/{test_id}` | Modify an existing resource without recreating it. | `test_id` |
| Delete an assistant test | HTTP only | `DELETE /ai/assistants/tests/{test_id}` | Remove, detach, or clean up an existing resource. | `test_id` |
| Get test run history for a specific test | HTTP only | `GET /ai/assistants/tests/{test_id}/runs` | Fetch the current state before updating, deleting, or making control-flow decisions. | `test_id` |
| Trigger a manual test run | HTTP only | `POST /ai/assistants/tests/{test_id}/runs` | Trigger a follow-up action in an existing workflow rather than creating a new top-level resource. | `test_id` |
| Get specific test run details | HTTP only | `GET /ai/assistants/tests/{test_id}/runs/{run_id}` | Fetch the current state before updating, deleting, or making control-flow decisions. | `test_id`, `run_id` |
| Delete an assistant | HTTP only | `DELETE /ai/assistants/{assistant_id}` | Remove, detach, or clean up an existing resource. | `assistant_id` |
| Get Canary Deploy | HTTP only | `GET /ai/assistants/{assistant_id}/canary-deploys` | Fetch the current state before updating, deleting, or making control-flow decisions. | `assistant_id` |
| Create Canary Deploy | HTTP only | `POST /ai/assistants/{assistant_id}/canary-deploys` | Create or provision an additional resource when the core tasks do not cover this flow. | `assistant_id` |
| Update Canary Deploy | HTTP only | `PUT /ai/assistants/{assistant_id}/canary-deploys` | Modify an existing resource without recreating it. | `assistant_id` |
| Delete Canary Deploy | HTTP only | `DELETE /ai/assistants/{assistant_id}/canary-deploys` | Remove, detach, or clean up an existing resource. | `assistant_id` |
| Assistant Sms Chat | HTTP only | `POST /ai/assistants/{assistant_id}/chat/sms` | Run assistant chat over SMS instead of direct API chat. | `from`, `to`, `assistant_id` |
| Assistant WhatsApp Chat | HTTP only | `POST /ai/assistants/{assistant_id}/chat/whatsapp` | Create or provision an additional resource when the core tasks do not cover this flow. | `from`, `to`, `content`, `assistant_id` |
| Clone Assistant | HTTP only | `POST /ai/assistants/{assistant_id}/clone` | Trigger a follow-up action in an existing workflow rather than creating a new top-level resource. | `assistant_id` |
| Get a deleted assistant | HTTP only | `GET /ai/assistants/{assistant_id}/deleted` | Fetch the current state before updating, deleting, or making control-flow decisions. | `assistant_id` |
| Enhance Assistant Instructions | HTTP only | `POST /ai/assistants/{assistant_id}/instructions/enhance` | Create or provision an additional resource when the core tasks do not cover this flow. | `assistant_id` |
| Restore an assistant | HTTP only | `POST /ai/assistants/{assistant_id}/restore` | Create or provision an additional resource when the core tasks do not cover this flow. | `assistant_id` |
| List scheduled events | HTTP only | `GET /ai/assistants/{assistant_id}/scheduled_events` | Fetch the current state before updating, deleting, or making control-flow decisions. | `assistant_id` |
| Create a scheduled event | HTTP only | `POST /ai/assistants/{assistant_id}/scheduled_events` | Create or provision an additional resource when the core tasks do not cover this flow. | `telnyx_conversation_channel`, `telnyx_end_user_target`, `telnyx_agent_target`, `scheduled_at_fixed_datetime`, +1 more |
| Get a scheduled event | HTTP only | `GET /ai/assistants/{assistant_id}/scheduled_events/{event_id}` | Fetch the current state before updating, deleting, or making control-flow decisions. | `assistant_id`, `event_id` |
| Delete a scheduled event | HTTP only | `DELETE /ai/assistants/{assistant_id}/scheduled_events/{event_id}` | Remove, detach, or clean up an existing resource. | `assistant_id`, `event_id` |
| Add Assistant Tag | HTTP only | `POST /ai/assistants/{assistant_id}/tags` | Create or provision an additional resource when the core tasks do not cover this flow. | `tag`, `assistant_id` |
| Remove Assistant Tag | HTTP only | `DELETE /ai/assistants/{assistant_id}/tags/{tag}` | Remove, detach, or clean up an existing resource. | `assistant_id`, `tag` |
| Get assistant texml | HTTP only | `GET /ai/assistants/{assistant_id}/texml` | Fetch the current state before updating, deleting, or making control-flow decisions. | `assistant_id` |
| Add Assistant Tool | HTTP only | `PUT /ai/assistants/{assistant_id}/tools/{tool_id}` | Modify an existing resource without recreating it. | `assistant_id`, `tool_id` |
| Remove Assistant Tool | HTTP only | `DELETE /ai/assistants/{assistant_id}/tools/{tool_id}` | Remove, detach, or clean up an existing resource. | `assistant_id`, `tool_id` |
| Test Assistant Tool | HTTP only | `POST /ai/assistants/{assistant_id}/tools/{tool_id}/test` | Trigger a follow-up action in an existing workflow rather than creating a new top-level resource. | `assistant_id`, `tool_id` |
| Get all versions of an assistant | HTTP only | `GET /ai/assistants/{assistant_id}/versions` | Fetch the current state before updating, deleting, or making control-flow decisions. | `assistant_id` |
| Get a specific assistant version | HTTP only | `GET /ai/assistants/{assistant_id}/versions/{version_id}` | Fetch the current state before updating, deleting, or making control-flow decisions. | `assistant_id`, `version_id` |
| Update a specific assistant version | HTTP only | `POST /ai/assistants/{assistant_id}/versions/{version_id}` | Create or provision an additional resource when the core tasks do not cover this flow. | `assistant_id`, `version_id` |
| Delete a specific assistant version | HTTP only | `DELETE /ai/assistants/{assistant_id}/versions/{version_id}` | Remove, detach, or clean up an existing resource. | `assistant_id`, `version_id` |
| Promote an assistant version to main | HTTP only | `POST /ai/assistants/{assistant_id}/versions/{version_id}/promote` | Trigger a follow-up action in an existing workflow rather than creating a new top-level resource. | `assistant_id`, `version_id` |
| List MCP Servers | HTTP only | `GET /ai/mcp_servers` | Inspect available resources or choose an existing resource before mutating it. | None |
| Create MCP Server | HTTP only | `POST /ai/mcp_servers` | Create or provision an additional resource when the core tasks do not cover this flow. | `name`, `type`, `url` |
| Get MCP Server | HTTP only | `GET /ai/mcp_servers/{mcp_server_id}` | Fetch the current state before updating, deleting, or making control-flow decisions. | `mcp_server_id` |
| Update MCP Server | HTTP only | `PUT /ai/mcp_servers/{mcp_server_id}` | Modify an existing resource without recreating it. | `mcp_server_id` |
| Delete MCP Server | HTTP only | `DELETE /ai/mcp_servers/{mcp_server_id}` | Remove, detach, or clean up an existing resource. | `mcp_server_id` |
| List Tools | HTTP only | `GET /ai/tools` | Inspect available resources or choose an existing resource before mutating it. | None |
| Create Tool | HTTP only | `POST /ai/tools` | Create or provision an additional resource when the core tasks do not cover this flow. | `type`, `display_name` |
| Get Tool | HTTP only | `GET /ai/tools/{tool_id}` | Fetch the current state before updating, deleting, or making control-flow decisions. | `tool_id` |
| Update Tool | HTTP only | `PATCH /ai/tools/{tool_id}` | Modify an existing resource without recreating it. | `tool_id` |
| Delete Tool | HTTP only | `DELETE /ai/tools/{tool_id}` | Remove, detach, or clean up an existing resource. | `tool_id` |

---

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

同类技能

• academy-guideStop and check this skill before finishing any reply to a question about how to use Claude or a Claude produ…
• career-opsOpen-source AI job search agent -- evaluate offers, generate CVs, scan portals, track applications. Use when…
• presentation-structureKnowledge about the presentation slide format, weight system, navigation, and section structure
• i-have-adhdShape output for a reader with ADHD: lead with the next action, number multi-step work, restate state across…
• ab-testingWhen the user wants to plan, design, or implement an A/B test or experiment, or build a growth experimentati…
• 13c-metabolic-fluxEstimates intracellular metabolic fluxes from steady-state carbon-13 isotope-tracing measurements using vali…