Voice API User Guide

The Voice Calling API services provides a set of features and functionalities that allows Customers to trigger Outbound calling to one or more recipients. Support for Voice API services is available in over 200 countries.

Prerequisites

Customers are required to subscribe to the Voice & Messaging Service offering via the Syniverse Developer Community portal.
Customers should familiarize themselves with the concepts and features of Voice and Messaging services
Customer should familiarize themselves with our Omni-Channel API Reference documentation.
Configure the Event Manager on the Syniverse Developer Community portal to enable you to receive call back events via POST to your application

Related Services

Voice Calling API can be used solely to enable the Voice calling service. Events relative to the calling service are delivered via the Event Manager. Customer can configure callback delivery to their application services using the Event Manager.

To use Event Manager, please subscribe to the service on the Syniverse Developer Community Portal

Voice services Use cases:

Make an Outbound Calling
Text-to Speech (TTS)

Key Features:

Play DTMF on a call
Play Audio on a call
Play TTS
TTS Templates
Support for SSML tags and language voices

Key Voice Service Limitations and Restrictions

Outbound Calling

Outbound calling does not include the following:
- 911 / E911
- Operator Services
- Collect Calling
- Any and all other operator, assisted, or intercept calling services
- Class 5 Features; and/or 976, 900, and 1010xxx calling.
A valid Voice-capable Sender Address (Telephone number) is required. Additional registration and approval may be required
Outbound calling to Premium is blocked by default.

Country Specific Restrictions and Limitations:

For information on Country specific restrictions and limitation, please visit our Voice Service knowledgebase

Basic Flows for Voice Service

Voice Capable Sender Address

The Sender address entity represents a communication medium and a specific channel endpoint from which applications can send and receive messages or calls. A certain base amount of information is needed for any channel used, with channel specific attributes required based on the type of channel.

In order to make a call, a Customer must first purchase at least one voice-capable Sender Address . A Voice capable sender address is an E.164 format number that is country specific and can be used to make Outbound calling and receive inbound calls.

Voice Number Overview & Purchase Requirements

Depending on country specific regulations, in some cases numbers require that users are located within the same region as the numbers they are purchasing.

It is essential that a valid business or residential address is provided during the purchasing of these virtual numbers. If the virtual numbers are intended to be used by an individual, the residential address of the end user should be provided. Virtual numbers purchased by a business entity should provide the registered address of the business.

There are 2 types of address requirements:

Requires an address from the same country as the number
Requires an address from the same region (City or State) as the number

In a few cases such as Hong Kong or Singapore, proof of address is also required when requesting a virtual number.

When purchasing virtual numbers with address requirements, Syniverse will require you to file a qualifying address with us before you are able to purchase the number.

For countries where an address is required to purchase a number, Customer should contact Syniverse Customer Care support or their Account representative

Using your own Telephone number as a Caller Line ID (CLI) for Outbound calls

Syniverse supports the functionality that allows Enterprise customers to use their own Telephone number as a Caller Line ID (CLI) for outbound calls. This number can be:

Regular Landline number
Toll-Free number

In both cases, the number must be an active number registered to the Enterprise. An active number is a number that can make and receive calls. The Enterprise must prove ownership by submitting a verifiable copy of an invoice showing they own the number and be able to furnish a Local contact address including a name of an authorized user associated with the company and number. Syniverse does not support spoofing of CLI. This is subject to approval by the Carrier.

Please note that while this can serve as an outbound calling ID, the number may also receive phone calls from your users. Incoming calls to this number will not be routed through Syniverse.

Making an Outbound Call (Available in US/Canada and International destinations)

Ensure you have a valid Sender ID ( Phone number) that has been provisioned with Voice capability before attempting to make a call. A caller ID (response Id) is returned.

curl -L -X POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls' -H 'Authorization: Bearer {Token} -H 'Content-Type: application/json' --data-raw '{"from":"NdET2v9bQGVws4DOJui711","to":"+14085551212"}

Making an Conversational Call ( Available in US and Canada only)

A Conversation call is an active call between 2 parties. SCG Calling API can be used to establish a Conversational call from a calling party to a recipient. A valid voice-capable Sender Address (Telephone number) is required. Customer can initiate the call by going through the following steps:

Create a Bridge resources. The API will return the bridge_id for this bridge.
Create a Call resource with the bridge_id and the calling party’s address in the "to" field.
Create a Call resource with the bridge_id and the recipient address in the "to" field.
Calling party and recipient can now talk.

See information on calling resources below on how to use the bridge resources. Additonal info is also available in the Call section of the API reference guide.

Example Curls:

Create a bridge.

curl 'https://api.syniverse.com/scg-external-api/api/v1/calling/bridges' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
}'

Make a call to the calling party

curl 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data-raw '{
"from":"{{senderid}}",
  "to":"{{DestinationNumber}}",
  "bridge_id":"{{bridgeId}}"
}'

Making a call to the recipient

curl --location --request POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"from":"{{senderid}}",
"to":"+{{DestinationNumber}}",
"external_id": "External_customID"
}'

Hangup a call:

curl --location --globoff --request POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls/{Call_ID}' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"state":"COMPLETED"
}'

Making a TTS call (Available in all destinations)

Customer can make a Text-to-speech (TTS) call to a recipient using the Syniverse CPaaS API for Voice services

curl --location --request POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
    "to": "+{{DestinationNumber}}",
    "from": "sender_id:{{senderId}}",
    "options": {
        "tts:voice": "Joanna",
        "tts:max_repetitions":2
    },
    "body": "<speak> <p> Do not share </p> <prosody rate=\"x-slow\"> <say-as interpret-as=\"digits\">1 2 3 4</say-as> </prosody> <p> is your Syniverse one-time passcode.</p></speak>"
}'

Answering an Inbound Call (Available in US and Canada only)

The CPaaS Voice Calling API can be used to establish an Inbound call from a calling party to a recipient. This is done by the Customer with a valid voice-capable Sender Address. This Customer can answer an Inbound call by going through the following steps:

When an end user places a call to the phone number associated with the SenderID, System will generate an Call_Incoming_Received event. This event will be sent to any configured delivery configuration end points and includes the Incoming call_id.
To answer the call, the answering party should create a Bridge resources. The API will return the bridge_id for this bridge.
Create a new Call resource with the answering party’s address in the "to" field. This will generate a call_id
Update the Bridge resource and add the two call Ids (Incoming call and the Answering call) to the "call_ids" field.
Answer the Incoming call.
Calling party and recipient can now talk.

Example Curls:

Create a bridge.

curl 'https://api.syniverse.com/scg-external-api/api/v1/calling/bridges' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
}'

Make a call to the answering party

curl --location --request POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"from":"{{senderid}}",
"to":"+{{DestinationNumber}}",
"external_id": "External_customID"
}'

Add both Calls to the bridge:

curl --globoff 'https://api.syniverse.com/scg-external-api/api/v1/calling/bridges/{Bridge_ID}' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"call_ids":["{{CallID#1}}", "{{CallID#2}}"],
"bridge_audio":true
}'

Answer the Incoming Call:

curl -X POST -H "Authorization: Bearer {{AUTH TOKEN}}"  -H 'Content-Type: application/json' -d '{"state":"ACTIVE"}' https://api.syniverse.com/scg-external-api/api/v1/calling/calls/{{CallID}}

Creating a Conference and Adding Members ( Available in US and Canada only)

Voice Calling API can be used to create a Conference bridge. Conference members can then be created and added to this bridge. The customer can create a Conference bridge and add members through the following steps:

Create a Conference Resource using a Voice capable SenderID. The API will return the conference_id for this bridge.
Create a new Call resource with the answering party’s address in the "to" field.
Create a new member for this Conference resource by using the Call Id.
Repeat the previous two steps for other members.
The Conference members can now talk to each other.

Example Curls:

Create a Conference.

curl 'https://api.syniverse.com/scg-external-api/api/v1/calling/conferences' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"from":"{{senderId}}"
}'

Make a call to the answering party

curl --location --request POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"from":"{{senderid}}",
"to":"+{{DestinationNumber}}",
"external_id": "External_customID"
}'

Add the Member to the Conference

curl -X POST -H "Authorization: Bearer {{AUTH TOKEN}}" -H "Content-Type: application/json" -d '{"callId":"{{CallID}}"}' https://api.syniverse.com/scg-external-api/api/v1/calling/conferences/{{ConferenceID}}/

Playing Audio on a Call or Conference

Once a call is established, the Voice API can be used to play audio on the call using DTMF tones, Text to speech or an Audio file. This is accomplished by generating a POST request to the play_dtmf, play_tts of play_audio sub-resource of the specific Call, Conference or Conference Member resource. Please note that audio playback on a Conference call is only available where Conference calls are supported. Currently only in the US and Canada.

Note: DTMF tones can only be used with Call resources.

Audio can be sourced from either an attachment of a URL. For more information on how to invoke this, please see details in the play audio on an active call resource below

Example Curls:

Make a call to the answering party

curl --location --request POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"from":"{{senderid}}",
"to":"+{{DestinationNumber}}",
"external_id": "External_customID"
}'

Play audio during an active call

curl -X POST -H "Authorization: Bearer {token}"  -H 'Content-Type: application/json' -d '{"source_type": "ATTACHMENT", "source": "0H7FIOJLvouKIndAR95aY4"}' https://api.syniverse.com/scg-external-api/api/v1/calling/calls/FOd2BRzeF8kS8FCHFf8G01/play_audio

Digit Collections

This resource lets user collect digits from keys entered on a phone during a call. e.g DTMF tones that can be used to advance a menu or trigger a response. The digits collected with have a unique identifier which users can reference in the future. The digits can be collected and POST back to the customer's application via the events service. For more information on the Digits collector resource, see Digits collector in the resource guide

Voice Calling API Resource Descriptions

Call Request

A Call resource represents a voice call between 2 parties.

Call State

A call can have multiple states which represented in the Call resource state attribute. The table below outlines the possible call states

State	Description
Started	The call is ringing
Active	The call has been answered
Rejected	The call recipient within the time out period
Completed	The active call has been completed. Both parties hang up

Call Request Recipient List

The API supports calling of a single recipient using the following recipient reference:

The recipient is specified by including the recipient telephone number in the "to" field of the Call resource

The type of recipient that each address refers to is denoted with a prefix added to the address in the to field

The available prefix are:

Phone numbers
- This is the number of the recipient in e.164 format

Bridge Resource

A Bridge resource represents a calling bridge that connects the calling party to the recipient party. Call resources are associated with a Bridge resource to connect the calls. A call and a bridge can be associated in 2 ways:

A bridge_id can be associated with a call when it is created
Existing calls can be associated with a bridge by adding the call IDs to the bridge resource

A Bridge resource can have the following states:

State	Description
Created	The bridge is ready to accept calls
Active	The bridge has one or more active calls associated with it
Completed	The bridge has been closed.
Error	Bridge failed to be created or ended due to an error

Call ID

A bridge has associated set of call IDs. These IDs are the unique identifiers for the calls that are bridged. The call IDs can be obtained from the Call resource ID field.

Conference Call Resource

A Conference resource represents a multi-party conference bridge that connects the multiple parties. Members are added to a conference using Call Ids from active calls.

A Conference resource can have the following states:

State	Description
Created	The conference is created but has no members.
Active	The conference is active and has members
Completed	The conference is completed and has no members.
Error	Bridge failed to be created or ended due to an error

Conference Call Member Resource

A Conference Member resource represents a member of a conference call. Members can be added and removed from conferences.

A Conference Member resource can have the following states:

State	Description
Active	The member's call is active in the Conference.
Complete	The member is no longer active in the conference.

play_dtmf on an active call

A Post to this resource results in playing of DTMF tones on a call. This is a sub-resource of the Call resource.

To play a DTMF, make sure a Call in already in an "ACTIVE" state and you have a Caller ID.

curl 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls/{{CALLID}}/play_dtmf' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"dtmfText": "12345#"
}'

Play DTMF POST body fields:

Field	Description
dtmfText	The digits that will be played as DTMF tones on the call.

play_tts on an active call

A POST to this resource results in playing of the text as speech on a call. This is a sub-resource of the Call, Conference, and Conference Member resource.

To play a TTS on a Call, make sure the call in in an "ACTIVE" state and you have a called ID

curl 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls/{{CALLID}}/play_tts' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"voice":"mathew",
"text": "Your account has been activated, thank you for using our services"
}'

Play TTS POST body fields:

Field	Description
text	The text to be spoken.
language	For supported languages, please refer to the Voice/Language matrix
gender	The gender of the speaker. Supported values are: - female - male
voice	One of the supported voices. Voice implies gender and language. Supported values are can be found here

You can find an extensive list of supported voices and SSML tags in this knowledgebase article

play_audio on an active call

A Post to this resource results in playing of the audio file on a call. This is a sub-resource of the Call, Conference, and Conference Member resource.

To play an audio on a Call, make sure the call in in an "ACTIVE" state and you have a called ID. You have the option of using our Attachment services to upload your audio file or insert a URL in your payload.

curl 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls/{{CALLID}}/play_audio' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"source_type":"URL",
"source": "http://www.sample-videos.com/audio/mp3/crowd-cheering.mp3"
}'

Play Audio POST body fields:

Field	Description
source_type	This is the type of the source. Supported values are: - ATTACHMENT - URL
source	The attachment ID or URL value for the audio file.

Hangup a Call

You can hangup a call that is in an "ACTIVE" state by making an API to change the state to "COMPLETED"

curl --location --globoff --request POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls/{Call_ID}' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer {{AUTH TOKEN}}' `
--data '{
"state":"COMPLETED"
}'

Voice API User Guide

Prerequisites

Related Services

Voice services Use cases:

Key Features:

Key Voice Service Limitations and Restrictions

Outbound Calling

Country Specific Restrictions and Limitations:

Basic Flows for Voice Service

Voice Capable Sender Address

Voice Number Overview & Purchase Requirements

Using your own Telephone number as a Caller Line ID (CLI) for Outbound calls

Making an Outbound Call (Available in US/Canada and International destinations)

Making an Conversational Call ( Available in US and Canada only)

Example Curls:

Making a TTS call (Available in all destinations)

Answering an Inbound Call (Available in US and Canada only)

Example Curls:

Creating a Conference and Adding Members ( Available in US and Canada only)

Example Curls:

Playing Audio on a Call or Conference

Example Curls:

Digit Collections

Voice Calling API Resource Descriptions

Call Request

Call State

Call Request Recipient List

Bridge Resource

Call ID

Conference Call Resource

Conference Call Member Resource

play_dtmf on an active call

play_tts on an active call

play_audio on an active call

Hangup a Call

Getting Started

API Reference

User Guides

Knowledge Articles

Libraries & SDKs

Whats New