Telnyx Ai Inference Java

Telnyx Ai Inference - Java

Installation

    com.telnyx.sdk
    telnyx
    6.36.0

// Gradle
implementation("com.telnyx.sdk:telnyx:6.36.0")

Setup

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();

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:

import com.telnyx.sdk.errors.TelnyxServiceException;

try {
    var result = client.messages().send(params);
} catch (TelnyxServiceException e) {
    System.err.println("API error " + e.statusCode() + ": " + e.getMessage());
    if (e.statusCode() == 422) {
        System.err.println("Validation error — check required fields and formats");
    } else if (e.statusCode() == 429) {
        // Rate limited — wait and retry with exponential backoff
        Thread.sleep(1000);
    }
}

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 a page. Use .autoPager() for automatic iteration: for (var item : page.autoPager()) { ... }. For manual control, use .hasNextPage() and .nextPage().

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

import com.telnyx.sdk.models.ai.audio.AudioTranscribeParams;
import com.telnyx.sdk.models.ai.audio.AudioTranscribeResponse;

AudioTranscribeParams params = AudioTranscribeParams.builder()
    .model(AudioTranscribeParams.Model.DISTIL_WHISPER_DISTIL_LARGE_V2)
    .build();
AudioTranscribeResponse response = client.ai().audio().transcribe(params);

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)

import com.telnyx.sdk.models.ai.chat.ChatCreateCompletionParams;
import com.telnyx.sdk.models.ai.chat.ChatCreateCompletionResponse;

ChatCreateCompletionParams params = ChatCreateCompletionParams.builder()
    .addMessage(ChatCreateCompletionParams.Message.builder()
        .content("You are a friendly chatbot.")
        .role(ChatCreateCompletionParams.Message.Role.SYSTEM)
        .build())
    .addMessage(ChatCreateCompletionParams.Message.builder()
        .content("Hello, world!")
        .role(ChatCreateCompletionParams.Message.Role.USER)
        .build())
    .build();
ChatCreateCompletionResponse response = client.ai().chat().createCompletion(params);

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

import com.telnyx.sdk.models.ai.conversations.ConversationListParams;
import com.telnyx.sdk.models.ai.conversations.ConversationListResponse;

ConversationListResponse conversations = client.ai().conversations().list();

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)

import com.telnyx.sdk.models.ai.conversations.Conversation;
import com.telnyx.sdk.models.ai.conversations.ConversationCreateParams;

Conversation conversation = client.ai().conversations().create();

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

import com.telnyx.sdk.models.ai.conversations.insightgroups.InsightGroupRetrieveInsightGroupsPage;
import com.telnyx.sdk.models.ai.conversations.insightgroups.InsightGroupRetrieveInsightGroupsParams;

InsightGroupRetrieveInsightGroupsPage page = client.ai().conversations().insightGroups().retrieveInsightGroups();

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)

import com.telnyx.sdk.models.ai.conversations.insightgroups.InsightGroupInsightGroupsParams;
import com.telnyx.sdk.models.ai.conversations.insightgroups.InsightTemplateGroupDetail;

InsightGroupInsightGroupsParams params = InsightGroupInsightGroupsParams.builder()
    .name("my-resource")
    .build();
InsightTemplateGroupDetail insightTemplateGroupDetail = client.ai().conversations().insightGroups().insightGroups(params);

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}

import com.telnyx.sdk.models.ai.conversations.insightgroups.InsightGroupRetrieveParams;
import com.telnyx.sdk.models.ai.conversations.insightgroups.InsightTemplateGroupDetail;

InsightTemplateGroupDetail insightTemplateGroupDetail = client.ai().conversations().insightGroups().retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e");

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)

import com.telnyx.sdk.models.ai.conversations.insightgroups.InsightGroupUpdateParams;
import com.telnyx.sdk.models.ai.conversations.insightgroups.InsightTemplateGroupDetail;

InsightTemplateGroupDetail insightTemplateGroupDetail = client.ai().conversations().insightGroups().update("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e");

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}

import com.telnyx.sdk.models.ai.conversations.insightgroups.InsightGroupDeleteParams;

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

import com.telnyx.sdk.models.ai.conversations.insightgroups.insights.InsightAssignParams;

InsightAssignParams params = InsightAssignParams.builder()
    .groupId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
    .insightId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
    .build();
client.ai().conversations().insightGroups().insights().assign(params);

Unassign Insight Template From Group

Remove an insight from a group

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

import com.telnyx.sdk.models.ai.conversations.insightgroups.insights.InsightDeleteUnassignParams;

InsightDeleteUnassignParams params = InsightDeleteUnassignParams.builder()
    .groupId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
    .insightId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
    .build();
client.ai().conversations().insightGroups().insights().deleteUnassign(params);

Get Insight Templates

Get all insights

GET /ai/conversations/insights

import com.telnyx.sdk.models.ai.conversations.insights.InsightListPage;
import com.telnyx.sdk.models.ai.conversations.insights.InsightListParams;

InsightListPage page = client.ai().conversations().insights().list();

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)

import com.telnyx.sdk.models.ai.conversations.insights.InsightCreateParams;
import com.telnyx.sdk.models.ai.conversations.insights.InsightTemplateDetail;

InsightCreateParams params = InsightCreateParams.builder()
    .instructions("You are a helpful assistant.")
    .name("my-resource")
    .build();
InsightTemplateDetail insightTemplateDetail = client.ai().conversations().insights().create(params);

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}

import com.telnyx.sdk.models.ai.conversations.insights.InsightRetrieveParams;
import com.telnyx.sdk.models.ai.conversations.insights.InsightTemplateDetail;

InsightTemplateDetail insightTemplateDetail = client.ai().conversations().insights().retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e");

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)

import com.telnyx.sdk.models.ai.conversations.insights.InsightTemplateDetail;
import com.telnyx.sdk.models.ai.conversations.insights.InsightUpdateParams;

InsightTemplateDetail insightTemplateDetail = client.ai().conversations().insights().update("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e");

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}

import com.telnyx.sdk.models.ai.conversations.insights.InsightDeleteParams;

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}

import com.telnyx.sdk.models.ai.conversations.ConversationRetrieveParams;
import com.telnyx.sdk.models.ai.conversations.ConversationRetrieveResponse;

ConversationRetrieveResponse conversation = client.ai().conversations().retrieve("550e8400-e29b-41d4-a716-446655440000");

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)

import com.telnyx.sdk.models.ai.conversations.ConversationUpdateParams;
import com.telnyx.sdk.models.ai.conversations.ConversationUpdateResponse;

ConversationUpdateResponse conversation = client.ai().conversations().update("550e8400-e29b-41d4-a716-446655440000");

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}

import com.telnyx.sdk.models.ai.conversations.ConversationDeleteParams;

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

import com.telnyx.sdk.models.ai.conversations.ConversationRetrieveConversationsInsightsParams;
import com.telnyx.sdk.models.ai.conversations.ConversationRetrieveConversationsInsightsResponse;

ConversationRetrieveConversationsInsightsResponse response = client.ai().conversations().retrieveConversationsInsights("550e8400-e29b-41d4-a716-446655440000");

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)

import com.telnyx.sdk.models.ai.conversations.ConversationAddMessageParams;

ConversationAddMessageParams params = ConversationAddMessageParams.builder()
    .conversationId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
    .role("user")
    .build();
client.ai().conversations().addMessage(params);

Get conversation messages

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

GET /ai/conversations/{conversation_id}/messages

import com.telnyx.sdk.models.ai.conversations.messages.MessageListParams;
import com.telnyx.sdk.models.ai.conversations.messages.MessageListResponse;

MessageListResponse messages = client.ai().conversations().messages().list("550e8400-e29b-41d4-a716-446655440000");

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

import com.telnyx.sdk.models.ai.embeddings.EmbeddingListParams;
import com.telnyx.sdk.models.ai.embeddings.EmbeddingListResponse;

EmbeddingListResponse embeddings = client.ai().embeddings().list();

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

…

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.