telnyx-ai-assistants-java

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

# Telnyx AI Assistants - Java

## Installation

```text
<!-- Maven -->
<dependency>
    <groupId>com.telnyx.sdk</groupId>
    <artifactId>telnyx</artifactId>
    <version>6.36.0</version>
</dependency>

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

## Setup

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

```java
import com.telnyx.sdk.models.ai.assistants.AssistantCreateParams;
import com.telnyx.sdk.models.ai.assistants.InferenceEmbedding;
AssistantCreateParams params = AssistantCreateParams.builder()
    .instructions("You are a helpful assistant.")
    .model("openai/gpt-4o")
    .name("my-resource")
    .build();
InferenceEmbedding assistant = client.ai().assistants().create(params);
```

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

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

`client.ai().assistants().create()` — `POST /ai/assistants`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes |  |
| `model` | string | Yes | ID of the model to use. |
| `instructions` | string | Yes | System instructions for the assistant. |
| `tools` | array[object] | No | The tools that the assistant can use. |
| `toolIds` | array[string] | No |  |
| `description` | string | No |  |
| ... | | | +12 optional params in [references/api-details.md](references/api-details.md) |

```java
import com.telnyx.sdk.models.ai.assistants.AssistantCreateParams;
import com.telnyx.sdk.models.ai.assistants.InferenceEmbedding;

AssistantCreateParams params = AssistantCreateParams.builder()
    .instructions("You are a helpful assistant.")
    .model("openai/gpt-4o")
    .name("my-resource")
    .build();
InferenceEmbedding assistant = client.ai().assistants().create(params);
```

Primary response fields:
- `assistant.id`
- `assistant.name`
- `assistant.model`
- `assistant.instructions`
- `assistant.createdAt`
- `assistant.description`

### Chat with an assistant

Chat is the primary runtime path. Agents need the exact assistant method and the response content field.

`client.ai().assistants().chat()` — `POST /ai/assistants/{assistant_id}/chat`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | The message content sent by the client to the assistant |
| `conversationId` | string (UUID) | Yes | A unique identifier for the conversation thread, used to mai... |
| `assistantId` | string (UUID) | Yes |  |
| `name` | string | No | The optional display name of the user sending the message |

```java
import com.telnyx.sdk.models.ai.assistants.AssistantChatParams;
import com.telnyx.sdk.models.ai.assistants.AssistantChatResponse;

AssistantChatParams params = AssistantChatParams.builder()
    .assistantId("550e8400-e29b-41d4-a716-446655440000")
    .content("Tell me a joke about cats")
    .conversationId("42b20469-1215-4a9a-8964-c36f66b406f4")
    .build();
AssistantChatResponse response = client.ai().assistants().chat(params);
```

Primary response fields:
- `response.content`

### Create an assistant test

Test creation is the main validation path for production assistant behavior before deployment.

`client.ai().assistants().tests().create()` — `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... |
| `telnyxConversationChannel` | object | No | The communication channel through which the test will be con... |
| `maxDurationSeconds` | integer | No | Maximum duration in seconds that the test conversation shoul... |
| ... | | | +1 optional params in [references/api-details.md](references/api-details.md) |

```java
import com.telnyx.sdk.models.ai.assistants.tests.AssistantTest;
import com.telnyx.sdk.models.ai.assistants.tests.TestCreateParams;

TestCreateParams params = TestCreateParams.builder()
    .destination("+15551234567")
    .instructions("Act as a frustrated customer who received a damaged product