Telnyx Ai Inference Javascript

Telnyx Ai Inference - JavaScript

Installation

npm install telnyx

Setup

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

All examples below assume client is already initialized as shown above.

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:

try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}

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

• Pagination: List methods return an auto-paginating iterator. Use for await (const item of result) { ... } to iterate through all pages automatically.

Transcribe speech to text

Transcribe speech to text. This endpoint is consistent with the OpenAI Transcription API and may be used with the OpenAI JS or Python SDK.

POST /ai/audio/transcriptions

const response = await client.ai.audio.transcribe({ model: 'distil-whisper/distil-large-v2' });

console.log(response.text);

Returns: duration (number), segments (array[object]), text (string)

Create a chat completion

Chat with a language model. This endpoint is consistent with the OpenAI Chat Completions API and may be used with the OpenAI JS or Python SDK.

POST /ai/chat/completions — Required: messages

Optional: api_key_ref (string), best_of (integer), early_stopping (boolean), enable_thinking (boolean), frequency_penalty (number), guided_choice (array[string]), guided_json (object), guided_regex (string), length_penalty (number), logprobs (boolean), max_tokens (integer), min_p (number), model (string), n (number), presence_penalty (number), response_format (object), stream (boolean), temperature (number), tool_choice (enum: none, auto, required), tools (array[object]), top_logprobs (integer), top_p (number), use_beam_search (boolean)

const response = await client.ai.chat.createCompletion({
  messages: [
    { role: 'system', content: 'You are a friendly chatbot.' },
    { role: 'user', content: 'Hello, world!' },
  ],
});

console.log(response);

List conversations

Retrieve a list of all AI conversations configured by the user. Supports PostgREST-style query parameters for filtering. Examples are included for the standard metadata fields, but you can filter on any field in the metadata JSON object.

GET /ai/conversations

const conversations = await client.ai.conversations.list();

console.log(conversations.data);

Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)

Create a conversation

Create a new AI Conversation.

POST /ai/conversations

Optional: metadata (object), name (string)

const conversation = await client.ai.conversations.create();

console.log(conversation.id);

Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)

Get Insight Template Groups

Get all insight groups

GET /ai/conversations/insight-groups

// Automatically fetches more pages as needed.
for await (const insightTemplateGroup of client.ai.conversations.insightGroups.retrieveInsightGroups()) {
  console.log(insightTemplateGroup.id);
}

Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)

Create Insight Template Group

Create a new insight group

POST /ai/conversations/insight-groups — Required: name

Optional: description (string), webhook (string)

const insightTemplateGroupDetail = await client.ai.conversations.insightGroups.insightGroups({
  name: 'my-resource',
});

console.log(insightTemplateGroupDetail.data);

Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)

Get Insight Template Group

Get insight group by ID

GET /ai/conversations/insight-groups/{group_id}

const insightTemplateGroupDetail = await client.ai.conversations.insightGroups.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateGroupDetail.data);

Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)

Update Insight Template Group

Update an insight template group

PUT /ai/conversations/insight-groups/{group_id}

Optional: description (string), name (string), webhook (string)

const insightTemplateGroupDetail = await client.ai.conversations.insightGroups.update(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateGroupDetail.data);

Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)

Delete Insight Template Group

Delete insight group by ID

DELETE /ai/conversations/insight-groups/{group_id}

await client.ai.conversations.insightGroups.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

Assign Insight Template To Group

Assign an insight to a group

POST /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign

await client.ai.conversations.insightGroups.insights.assign(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  { group_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
);

Unassign Insight Template From Group

Remove an insight from a group

DELETE /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign

await client.ai.conversations.insightGroups.insights.deleteUnassign(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  { group_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
);

Get Insight Templates

Get all insights

GET /ai/conversations/insights

// Automatically fetches more pages as needed.
for await (const insightTemplate of client.ai.conversations.insights.list()) {
  console.log(insightTemplate.id);
}

Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)

Create Insight Template

Create a new insight

POST /ai/conversations/insights — Required: instructions, name

Optional: json_schema (object), webhook (string)

const insightTemplateDetail = await client.ai.conversations.insights.create({
  instructions: 'You are a helpful assistant.',
  name: 'my-resource',
});

console.log(insightTemplateDetail.data);

Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)

Get Insight Template

Get insight by ID

GET /ai/conversations/insights/{insight_id}

const insightTemplateDetail = await client.ai.conversations.insights.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateDetail.data);

Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)

Update Insight Template

Update an insight template

PUT /ai/conversations/insights/{insight_id}

Optional: instructions (string), json_schema (object), name (string), webhook (string)

const insightTemplateDetail = await client.ai.conversations.insights.update(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateDetail.data);

Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)

Delete Insight Template

Delete insight by ID

DELETE /ai/conversations/insights/{insight_id}

await client.ai.conversations.insights.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

Get a conversation

Retrieve a specific AI conversation by its ID.

GET /ai/conversations/{conversation_id}

const conversation = await client.ai.conversations.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(conversation.data);

Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)

Update conversation metadata

Update metadata for a specific conversation.

PUT /ai/conversations/{conversation_id}

Optional: metadata (object)

const conversation = await client.ai.conversations.update('550e8400-e29b-41d4-a716-446655440000');

console.log(conversation.data);

Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)

Delete a conversation

Delete a specific conversation by its ID.

DELETE /ai/conversations/{conversation_id}

await client.ai.conversations.delete('550e8400-e29b-41d4-a716-446655440000');

Get insights for a conversation

Retrieve insights for a specific conversation

GET /ai/conversations/{conversation_id}/conversations-insights

const response = await client.ai.conversations.retrieveConversationsInsights('550e8400-e29b-41d4-a716-446655440000');

console.log(response.data);

Returns: conversation_insights (array[object]), created_at (date-time), id (string), status (enum: pending, in_progress, completed, failed)

Create Message

Add a new message to the conversation. Used to insert a new messages to a conversation manually ( without using chat endpoint )

POST /ai/conversations/{conversation_id}/message — Required: role

Optional: content (string), metadata (object), name (string), sent_at (date-time), tool_call_id (string), tool_calls (array[object]), tool_choice (object)

await client.ai.conversations.addMessage('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { role: 'user' });

Get conversation messages

Retrieve messages for a specific conversation, including tool calls made by the assistant.

GET /ai/conversations/{conversation_id}/messages

const messages = await client.ai.conversations.messages.list('550e8400-e29b-41d4-a716-446655440000');

console.log(messages.data);

Returns: created_at (date-time), role (enum: user, assistant, tool), sent_at (date-time), text (string), tool_calls (array[object])

Get Tasks by Status

Retrieve tasks for the user that are either queued, processing, failed, success or partial_success based on the query string. Defaults to queued and processing.

GET /ai/embeddings

const embeddings = await client.ai.embeddings.list();

console.log(embeddings.data);

Returns: bucket (string), created_at (date-time), finished_at (date-time), status (enum: queued, processing, success, failure, partial_success), task_id (string), task_name (string), user_id (string)

Embed documents

Perform embedding on a Telnyx Storage Bucket using an embedding model. The current supported file types are:

• PDF
• HTML
• txt/unstructured text files
• json
• csv
• audio / video (mp3, mp4, mpeg, mpga, m4a, wav, or webm ) - Max of 100mb file size. Any files not matching the above types will be attempted to be embedded as unstructured text.

POST /ai/embeddings — Required: bucket_name

Optional: document_chunk_overlap_size (integer), document_chunk_size (integer), embedding_model (object), loader (object)

const embeddingResponse = await client.ai.embeddings.create({ bucket_name: 'bucket_name' });

console.log(embeddingResponse.data);

Returns: created_at (string), finished_at (string | null), status (string), task_id (uuid), task_name (string), user_id (uuid)

List embedded buckets

Get all embedding buckets for a user.

GET /ai/embeddings/buckets

const buckets = await client.ai.embeddings.buckets.list();

console.log(buckets.data);

Returns: buckets (array[string])

Get file-level embedding statuses for a bucket

Get all embedded files for a given user bucket, including their processing status.

GET /ai/embeddings/buckets/{bucket_name}

const bucket = await client.ai.embeddings.buckets.retrieve('bucket_name');

console.log(bucket.data);

Returns: created_at (date-time), error_reason (string), filename (string), last_embedded_at (date-time), status (string), updated_at (date-time)

Disable AI for an Embedded Bucket

Deletes an entire bucket's embeddings and disables the bucket for AI-use, returning it to normal storage pricing.

DELETE /ai/embeddings/buckets/{bucket_name}

await client.ai.embeddings.buckets.delete('bucket_name');

Search for documents

Perform a similarity search on a Telnyx Storage Bucket, returning the most similar num_docs document chunks to the query. Currently the only available distance metric is cosine similarity which will return a distance between 0 and 1. The lower the distance, the more similar the returned document chunks are to the query.

POST /ai/embeddings/similarity-search — Required: bucket_name, query

Optional: num_of_docs (integer)

const response = await client.ai.embeddings.similaritySearch({
  bucket_name: 'bucket_name',
  query: 'What is Telnyx?',
});

console.log(response.data);

Returns: distance (number), document_chunk (string), metadata (object)

Embed URL content

Embed website content from a specified URL, including child pages up to 5 levels deep within the same domain. The process crawls and loads content from the main URL and its linked pages into a Telnyx Cloud Storage bucket.

POST /ai/embeddings/url — Required: url, bucket_name

const embeddingResponse = await client.ai.embeddings.url({
  bucket_name: 'bucket_name',
  url: 'https://example.com/resource',
});

console.log(embeddingResponse.data);

Returns: created_at (string), finished_at (string | null), status (string), task_id (uuid), task_name (string), user_id (uuid)

Get an embedding task's status

Check the status of a current embedding task. Will be one of the following:

• queued - Task is waiting to be picked up by a worker
• processing - The embedding task is running
• success - Task completed successfully and the bucket is embedded
• failure - Task failed and no files were embedded successfully
• partial_success - Some files were embedded successfully, but at least one failed

GET /ai/embeddings/{task_id}

const embedding = await client.ai.embeddings.retrieve('task_id');

console.log(embedding.data);

Returns: created_at (string), finished_at (string), `stat

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: team-telnyx
• Source: team-telnyx/ai
• License: MIT

Install and usage instructions live in the source repository linked above.