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

You may also connect to our documentation MCP server by clicking the Connect MCP button:

Getting started

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:

1. Get 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.

2. 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.

3. Assign your number

In the Sinch Build dashboard, navigate to the Numbers section and locate Your virtual numbers.

Click on your number to go into the details for that number. Scroll down to the Voice Configuration section and click Edit. There you can select your default service. Make sure to save your settings.

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. The SVAML payload should be included in the commands field:

application/json

{
  "commands": [
    { … }
  ]
}

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.

Since setting up your own server to listen for incoming requests can be a bit intensive, 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:

application/json

{
  "description": "Service with static SVAML",
  "callBehavior": {
    "type": "STATIC",
    "static": { … }
  }
}

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.