Java SDK - Telnyx

The official telnyx package provides Java and Kotlin-compatible clients generated from the same OpenAPI definition as the API reference.

Requests, types, and pagination

Immutable request and response models, uploads, raw responses, and pagination.

Resource map

Search every SDK resource and method and open the matching REST endpoint.

Errors, retries, and timeouts

Handle structured errors and configure retry and timeout behavior.

Webhooks

Verify ED25519 signatures and process webhook events.

Advanced usage

Configure language-specific logging, transport, raw responses, and custom requests.

Install

Add com.telnyx.sdk:telnyx to the Gradle or Maven build using the current version published on Maven Central.

Requirements

This library requires Java 8 or later.

Initialize the client and make a request

Quickstart from the current SDK source, using TELNYX_API_KEY for authentication:

Usage

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.calls.CallDialParams;
import com.telnyx.sdk.models.calls.CallDialResponse;

// Configures using the `telnyx.apiKey`, `telnyx.publicKey`, `telnyx.clientId`, `telnyx.clientSecret` and `telnyx.baseUrl` system properties
// Or configures using the `TELNYX_API_KEY`, `TELNYX_PUBLIC_KEY`, `TELNYX_CLIENT_ID`, `TELNYX_CLIENT_SECRET` and `TELNYX_BASE_URL` environment variables
TelnyxClient client = TelnyxOkHttpClient.fromEnv();

CallDialParams params = CallDialParams.builder()
    .connectionId("conn12345")
    .from("+15557654321")
    .to("+15551234567")
    .webhookUrl("https://your-webhook.url/events")
    .build();
CallDialResponse response = client.calls().dial(params);

Client configuration

Configure the client using system properties or environment variables:

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

// Configures using the `telnyx.apiKey`, `telnyx.publicKey`, `telnyx.clientId`, `telnyx.clientSecret` and `telnyx.baseUrl` system properties
// Or configures using the `TELNYX_API_KEY`, `TELNYX_PUBLIC_KEY`, `TELNYX_CLIENT_ID`, `TELNYX_CLIENT_SECRET` and `TELNYX_BASE_URL` environment variables
TelnyxClient client = TelnyxOkHttpClient.fromEnv();

Or manually:

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

TelnyxClient client = TelnyxOkHttpClient.builder()
    .apiKey("My API Key")
    .build();

Or using a combination of the two approaches:

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

TelnyxClient client = TelnyxOkHttpClient.builder()
    // Configures using the `telnyx.apiKey`, `telnyx.publicKey`, `telnyx.clientId`, `telnyx.clientSecret` and `telnyx.baseUrl` system properties
    // Or configures using the `TELNYX_API_KEY`, `TELNYX_PUBLIC_KEY`, `TELNYX_CLIENT_ID`, `TELNYX_CLIENT_SECRET` and `TELNYX_BASE_URL` environment variables
    .fromEnv()
    .apiKey("My API Key")
    .build();

See this table for the available options:

Setter	System property	Environment variable	Required	Default value
`apiKey`	`telnyx.apiKey`	`TELNYX_API_KEY`	false	-
`publicKey`	`telnyx.publicKey`	`TELNYX_PUBLIC_KEY`	false	-
`clientId`	`telnyx.clientId`	`TELNYX_CLIENT_ID`	false	-
`clientSecret`	`telnyx.clientSecret`	`TELNYX_CLIENT_SECRET`	false	-
`baseUrl`	`telnyx.baseUrl`	`TELNYX_BASE_URL`	true	`"https://api.telnyx.com/v2"`

System properties take precedence over environment variables.

[!TIP] Don’t create more than one client in the same application. Each client has a connection pool and thread pools, which are more efficient to share between requests.

Modifying configuration

To temporarily use a modified client configuration, while reusing the same connection and thread pools, call withOptions() on any client or service:

import com.telnyx.sdk.client.TelnyxClient;

TelnyxClient clientWithOptions = client.withOptions(optionsBuilder -> {
    optionsBuilder.baseUrl("https://example.com");
    optionsBuilder.maxRetries(42);
});

The withOptions() method does not affect the original client or service.

Asynchronous execution

The default client is synchronous. To switch to asynchronous execution, call the async() method:

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.calls.CallDialParams;
import com.telnyx.sdk.models.calls.CallDialResponse;
import java.util.concurrent.CompletableFuture;

// Configures using the `telnyx.apiKey`, `telnyx.publicKey`, `telnyx.clientId`, `telnyx.clientSecret` and `telnyx.baseUrl` system properties
// Or configures using the `TELNYX_API_KEY`, `TELNYX_PUBLIC_KEY`, `TELNYX_CLIENT_ID`, `TELNYX_CLIENT_SECRET` and `TELNYX_BASE_URL` environment variables
TelnyxClient client = TelnyxOkHttpClient.fromEnv();

CallDialParams params = CallDialParams.builder()
    .connectionId("conn12345")
    .from("+15557654321")
    .to("+15551234567")
    .webhookUrl("https://your-webhook.url/events")
    .build();
CompletableFuture<CallDialResponse> response = client.async().calls().dial(params);

Or create an asynchronous client from the beginning:

import com.telnyx.sdk.client.TelnyxClientAsync;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClientAsync;
import com.telnyx.sdk.models.calls.CallDialParams;
import com.telnyx.sdk.models.calls.CallDialResponse;
import java.util.concurrent.CompletableFuture;

// Configures using the `telnyx.apiKey`, `telnyx.publicKey`, `telnyx.clientId`, `telnyx.clientSecret` and `telnyx.baseUrl` system properties
// Or configures using the `TELNYX_API_KEY`, `TELNYX_PUBLIC_KEY`, `TELNYX_CLIENT_ID`, `TELNYX_CLIENT_SECRET` and `TELNYX_BASE_URL` environment variables
TelnyxClientAsync client = TelnyxOkHttpClientAsync.fromEnv();

CallDialParams params = CallDialParams.builder()
    .connectionId("conn12345")
    .from("+15557654321")
    .to("+15551234567")
    .webhookUrl("https://your-webhook.url/events")
    .build();
CompletableFuture<CallDialResponse> response = client.calls().dial(params);

The asynchronous client supports the same options as the synchronous one, except most methods return CompletableFutures.

Source and releases

SDK releases can follow REST API changes at different times. Check the package registry for the current version and use the resource map to confirm method availability.

Requests, types, and pagination

Resource map

Errors, retries, and timeouts

Webhooks

Advanced usage

​Install

​Requirements

​Initialize the client and make a request

​Usage

​Client configuration

​Modifying configuration

​Asynchronous execution

​Source and releases