If you want to use the content of this page with an AI tool, or if you are an AI agent, use the Markdown version of this page: https://developers.sinch.com/docs/voice-2.0/getting-started.md

Sinch Voice API: Choosing between v1 and v2

For all new projects, please use Voice API v2. This is especially important for projects involving:

AI capabilities like Streams and Voice Relay
Voice campaigns like Batch calling

You should only use the older Voice API v1 if one of the following is a strict requirement:

The project must be in General Availability (GA).
The project requires In-App voice or Conferencing (until these features are available in v2).

Getting started

Step 1

Accept T&C

Step 2

Get and assign your number

Handle an incoming call

Account required!

Using the Voice API v2 requires signing up for a free account on the Sinch Build Dashboard. If you haven't already done so, sign up now!

Follow the steps below to learn how to quickly start making calls using the Sinch Voice API v2:

1. Accept the terms and conditions

In the Sinch Build Dashboard, navigate to the Programmable Voice and accept the terms and conditions. When you sign up for an account, a default Voice service is automatically created and now it will be available to use.

2. Get and assign your number

Get your free Sinch testing number. When you sign up for a Sinch Build Dashboard account, you get a free virtual number for testing. You must activate your test number before you can use it. To activate your number, simply click the link. In the modal window that is displayed when activating your number, you can add Voice configuration to the number. Select your Programmable Voice default service.

3. Get your credentials

Then, create your access key. Access keys are used to authenticate calls when using Voice API v2. Access keys are generated in the Sinch Build Dashboard.

You'll need this info later!

Make sure you have your access key, access key secret, and project ID readily available. This information will be required when making the API request to make a phone call. The access key and access key secret must be recorded during access key creation. The project ID can be found on the Sinch Build Dashboard's Project Settings page.

4. Make a call

Now you're ready to get started making a phone call using the Voice API v2.

If you already have experience making API requests, you can create an application that makes the phone call in your preferred coding language.

The payload, along with instructions on how to populate placeholder variables, is below. Alternatively, each tab features a guide that will walk you through setting up a simple application in the identified coding language (make sure you bring all the information you gathered during this process!):

To initiate an outbound call, send a POST request to the /v2/projects/{projectId}/calls endpoint. You can use the panel below to make your request:

The placeholder values included in the payload above are detailed in the table below:

Placeholder value	Your value
{YOUR_Number}	This is your test number that you activated in a previous step.
{YOUR_Destination_number}	This is a number you have verified in the Build dashboard.

When you make the request, don't forget to include your project ID, and your access key and secret. Since this guide is intended for testing purposes, you can use your access key and access secret to authenticate using basic authentication.

Congratulations! You have successfully initiated your first outbound call.

5. Handle an incoming call

You can also call the phone number assigned to your Voice service and handle that incoming call. The Voice API v2 can respond to incoming calls in one of two ways:

Sending an event to the webhook configured on your Voice service when a call is received
Configuring static SVAML code to your Voice service which triggers when a call is received.

Setting up your own server to listen for incoming requests takes more steps than this guide covers in the languages below — if you want to skip that setup, see the Sinch Functions tab instead, or continue on and this guide will show you how to configure your Voice service with static SVAML code.

If you already have experience making API requests, you can create an application that updates your service in your preferred coding language.

To update your service with static SVAML, send a PATCH request to the /v2/projects/{projectId}/services/{serviceId} endpoint. You will update the call behavior of the service as shown below:

Payload

{
  "description": "Service with webhooks",
  "callBehavior": {
    "type": "WEBHOOK",
    "webhook": { … }
  }
}

Now that you've updated your service, call the phone number assigned to your Voice service. The call should be answered and you'll hear the text of the SAY command in the SVAML.

Next steps

Now that you know how to make an outbound call and handle an incoming call, you can start to build more complex solutions. Check out the following guides to see what you can do with Voice API v2:

Additional resources

View the whole API Reference.