# Dialing via Voice API v2

Beta
Dialing via Voice API v2 is currently in beta. It is fully functional, but interfaces and behavior may change before general availability. [Voice API v2](/docs/voice-2.0) itself is available as a public preview.

The JavaScript SDK can place calls that are routed through the [Sinch Voice API v2](/docs/voice-2.0/overview) platform. We call these calls *dials*. A dial starts in your app, just like any other outgoing call, but how it's handled is decided by your Voice API v2 configuration. You can use dials to reach phone numbers, SIP endpoints, audio streams and Voice Relay.

## Why use dial?

Calls made from your app with dials are handled by the Voice API v2 platform. This lets you:

- **Control the call from your Voice API v2 service.** The call follows your service configuration. That can be predefined [SVAML commands](/docs/voice-2.0/api-reference/svaml) or webhooks to your backend that decide what happens next in real time. See [how Voice API v2 works](/docs/voice-2.0/overview#how-it-works).
- **Reach more destinations from the app.** Besides phone numbers and SIP endpoints, a dial can connect the user to an audio stream or to Voice Relay. This makes it easy to, for example, connect your users to an AI voice agent.
- **Use Voice API v2 features.** Dials use the same call model, events and features as the rest of Voice API v2. See [What is new in Voice v2?](/docs/voice-2.0/whatsnew) for an overview.


## Supported destinations

| Destination | Description | Learn more |
|  --- | --- | --- |
| Phone number | A phone on the regular telephone network (PSTN). Specify the number in [E.164 format](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537), prefixed with `+`. | [Outbound calls](/docs/voice-2.0/tutorials/outbound-tts) |
| SIP endpoint | A SIP destination, such as your PBX or contact center. | [SIP outbound](/docs/voice-2.0/api-reference/sip/outbound) |
| Audio stream | A two-way audio stream to your WebSocket server. | [Voice Streams](/docs/voice-2.0/api-reference/x-voice-stream), [Audio streaming](/docs/voice-2.0/tutorials/stream-audio) |
| Voice Relay | A WebSocket connection with speech-to-text and text-to-speech, for example for chatbots and AI agents. | [Voice Relay](/docs/voice-2.0/api-reference/x-voice-relay), [Call chatbots with Voice Relay](/docs/voice-2.0/tutorials/voice-relay) |


Service configuration takes precedence
The SDK provides a dial method for each destination type, but your Voice API v2 service has the final say on where the call goes. Your service configuration in the [dashboard](https://dashboard.sinch.com/) can set the destination statically, using [service call behaviors](/docs/voice-2.0/api-reference/voice/services/updateservice#services/updateservice/t=request&path=callbehavior), or dynamically, using [webhooks](/docs/voice-2.0/api-reference/voice/webhooks) to your backend. If such a configuration is present, it always takes precedence over the destination passed to the SDK dial method.

Note
*App-to-app* calls, including video calls, aren't available via Voice API v2 yet. They continue to use the existing in-app calling on Voice API v1. See [Audio calling](/docs/in-app-calling/js/calling) and [Video calling](/docs/in-app-calling/js/video-calling).

## Before you begin

- Set up a Voice API v2 service in your project. It defines how your dials are handled. See [Getting started with Voice API v2](/docs/voice-2.0/getting-started).
- When dialing a phone number, the same rules apply as for *app-to-phone* calls: you need a valid CLI (Calling Line Identifier), trial accounts can only call verified numbers, and your account needs sufficient credits. See [Presenting a number to the destination you are calling](/docs/in-app-calling/js/calling#presenting-a-number-to-the-destination-you-are-calling).


Note:
You can choose which Voice API v2 service handles a dial. If you don't specify a service, your project's default service is used.

## Placing a dial

Dials are placed using the `CallClient`, just like other calls. There is one dial method for each destination type: phone number, SIP endpoint, audio stream and Voice Relay. Each method takes the destination and optional, destination-specific options, such as the Voice API v2 service to use, the caller identifier or custom call headers. For the full list of methods and options, see the [Reference Documentation](https://download.sinch.com/js/latest/reference/index.html).

```javascript
const callClient = sinchClient.callClient;
const call = await callClient.dialPhoneNumber('+14155550101');
call.addListener(...);
```

For complete examples of each destination type, see the dialing samples in the [Sinch reference applications (JavaScript)](https://github.com/sinch/rtc-reference-applications/tree/master/javascript) on GitHub.

## Handling the call

A dial returns a regular `Call` object. Follow its progress with the same `CallListener` you use for other outgoing calls: you're notified when the call is progressing, answered, established and ended. See [Audio calling](/docs/in-app-calling/js/calling) for details.

Dials are audio-only.

## More resources

- [Reference Documentation](https://download.sinch.com/js/latest/reference/index.html) for the dial methods and their options.
- [Sinch reference applications](https://github.com/sinch/rtc-reference-applications) with dialing samples.
- [Release notes](/docs/in-app-calling/js/release-notes) to see which SDK version introduced dialing and any later changes.
- [Voice API v2 documentation](/docs/voice-2.0) for services, SVAML commands, webhooks and events.