/telnyx-voice-java

name: telnyx-voice-java
description: >-
  Programmatic call control: make/receive calls, transfer, bridge, gather DTMF,
  stream audio. Real-time call events via webhooks.
metadata:
  author: telnyx
  product: voice
  language: java
  generated_by: telnyx-openapi-pipeline
  contract: v2

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

Telnyx Voice - Java

Installation

<!-- Maven -->
<dependency>
    <groupId>com.telnyx.sdk</groupId>
    <artifactId>telnyx</artifactId>
    <version>6.95.0</version>
</dependency>

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

Setup

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

// fromEnv() reads TELNYX_API_KEY and TELNYX_PUBLIC_KEY (the public key is required for
// client.webhooks().unwrap() — webhook verification)
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.models.calls.CallDialParams;
import com.telnyx.sdk.models.calls.CallDialResponse;
import com.telnyx.sdk.errors.TelnyxServiceException;

try {
    CallDialParams params = CallDialParams.builder()
        .connectionId("7267xxxxxxxxxxxxxx")
        .from("+18005550101")
        .to("+18005550100")
        .build();
    CallDialResponse response = client.calls().dial(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, then retry the request (bounded exponential backoff)
        Thread.sleep(1000);
        // ...retry the call here (give up after a few attempts)
    }
    throw e; // Re-throw: a failed request must never look like success to the caller
}

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

Operational Caveats

• Call Control is event-driven. After `dial()` or an inbound webhook, issue follow-up commands from webhook handlers using the `call_control_id` in the event payload.
• Outbound and inbound flows are different: outbound calls start with `dial()`, while inbound calls must be answered from the incoming webhook before other commands run.
• A publicly reachable webhook endpoint is required for real call control. Without it, calls may connect but your application cannot drive the live call state.

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).
• Before reading or matching webhook fields beyond the inline examples, read [the webhook payload reference](references/api-details.md#webhook-payload-fields).

Core Tasks

Dial an outbound call

Primary voice entrypoint. Agents need the async call-control identifiers returned here.

`client.calls().dial()` — `POST /calls`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string (E.164) | Yes | The DID or SIP URI to dial out to. | | `from` | string (E.164) | Yes | The `from` number to be used as the caller id presented to t... | | `connectionId` | string (UUID) | Yes | The ID of the Call Control App (formerly ID of the connectio... | | `timeoutSecs` | integer | No | The number of seconds that Telnyx will wait for the call to ... | | `billingGroupId` | string (UUID) | No | Use this field to set the Billing Group ID for the call. | | `clientState` | string | No | Use this field to add state to every subsequent webhook. | | ... | | | +59 optional params in [references/api-details.md](references/api-details.md) |

import com.telnyx.sdk.models.calls.CallDialParams;
import com.telnyx.sdk.models.calls.CallDialResponse;

CallDialParams params = CallDialParams.builder()
    .connectionId("7267xxxxxxxxxxxxxx")
    .from("+18005550101")
    .to("+18005550100")
    .build();
CallDialResponse response = client.calls().dial(params);

Primary response fields:

• `response.data.callControlId`
• `response.data.callLegId`
• `response.data.callSessionId`
• `response.data.isAlive`
• `response.data.recordingId`
• `response.data.callDuration`

Answer an inbound call

Primary inbound call-control command.

`client.calls().actions().answer()` — `POST /calls/{call_control_id}/actions/answer`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `callControlId` | string (UUID) | Yes | Unique identifier and token for controlling the call | | `billingGroupId` | string (UUID) | No | Use this field to set the Billing Group ID for the call. | | `clientState` | string | No | Use this field to add state to every subsequent webhook. | | `webhookUrl` | string (URL) | No | Use this field to override the URL for which Telnyx will sen... | | ... | | | +29 op