> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK usage

> Initialize and configure the Telnyx Java client, make your first request, and execute calls asynchronously.

## Usage

```java theme={null}
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` and `telnyx.baseUrl` system properties
// Or configures using the `TELNYX_API_KEY` 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:

```java theme={null}
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

// Configures using the `telnyx.apiKey` and `telnyx.baseUrl` system properties
// Or configures using the `TELNYX_API_KEY` and `TELNYX_BASE_URL` environment variables
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
```

Or manually:

```java theme={null}
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:

```java theme={null}
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.builder()
    // Configures using the `telnyx.apiKey` and `telnyx.baseUrl` system properties
    // Or configures using the `TELNYX_API_KEY` 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`     | true     | -                             |
| `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:

```java theme={null}
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:

```java theme={null}
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` and `telnyx.baseUrl` system properties
// Or configures using the `TELNYX_API_KEY` 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:

```java theme={null}
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` and `telnyx.baseUrl` system properties
// Or configures using the `TELNYX_API_KEY` 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 `CompletableFuture`s.