Sending TTS - Messaging API vs Calls API – Syniverse Developer Community

There are occasions in which it is necessary to contact a user to communicate information that could be time sensitive or related, not only to mobile numbers but, to land lines registered to a consumer as contact numbers. In such cases the capability to send SMS messages is not enough to reach all consumers or to contact effectively.

Syniverse SCG Message and Message_Request APIs can send TTS as easy as text short messages. It is possible to call the consumer and plays a TTS message through these APIs using a Voice capable sender Id, making it possible to reach any user to deliver a voice message to any phone in a real time manner.

Additionally, SCG offers the Calls API service. This is a Voice, functionality rich, service that enable the enterprise to implement interactive calls that could be used to deliver TTS Voice Messages with additional feedback from the API about the message.

Here we present information an example of how to send a TTS voice messages using Message/Message_Requests APIs for single voice message and the Calls API in an interactive way Voice message. As there is no difference between the Message/Message_Requests so we will refer only to the Message API and compare it with Calls API specifically to this functionality.

Messages API - TTS

The easiest way to send a TTS voice message in its most basic format, is by the SCG Message API. This API payload format for TTS is the same as the SMS payload format as the only difference is the requirement to provide a Sender Id with VOICE capability.

To send a message TTS we could use the cURL:

Example 1: Simple TTS

curl -X POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages' \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"to":"+1346787XXXX",
"from":"5XMje4rar39mBLXXXXXXX",
"body":"Hello, this is a test call sample for your review."
}'

R/ {"id":" bLMjduDTxrMf5XXXXXXXXX"}

This voice message as being processed by the SCG Message API are shown in the Voice & Messaging Console OUTBOX

example1 SCG console MessageAPI-TTS.jpg

As any SCG message, when double click in the message line, details can be reviewed:

example1 det SCG console MessageAPI-TTS.jpg

Example 2: Enhanced TTS

SCG supports SSML, we could use TTS with SSML for enhanced voice message like:

curl -X POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages' \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"to":"+1346787XXXX",
"from":"5XMje4rar39mBLXXXXXXX",
"body":"<speak>My name is <break time=\"1s\" />John Smith.</speak>"
}'

R/ {"id":"91CGXty7zUy4lGUDet4g2"}

For further information about the use of SSML in TTS click here.

Calls API - TTS

An alternative for sending TTS voice messages is the Calls API.

Certainly, Calls API requires additional API calls for this task, but as an interactive voice tool, it provides additional functionality and feedback.

For this example, we created a webhook for an ESS subscription with Topic "SCG-Voice-Call", event type "call_state_change" with a matching criteria new_state='ACTIVE'.

In the same example we can send the TTS using the below Voice API calls:

1. Open a Voice call:

curl -X POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls' \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"from": "AO5udYNmrmaKhAXXXXXXXX",
"to": "+5066173XXXX"
}'

R/ {OUlEXakd7SiD0RtbRPhVX5}

2. Wait the recipient to answer: the callback in the webhook will look like:

{
"topic": "SCG-Voice-Call",
"attempt": 1,
"event": {
"fld-val-list": {
"reason_code": "200",
"previous_state": "STARTED",
"company-id": XXXXXX,
"external_call_id": "",
"call_price": 0,
"new_state": "ACTIVE",
"to_address": "+5066173XXXX",
"reason_description": "SUCCESS",
"from_address": "12018XXXXXX",
"application_id": XXXXX,
"call_duration": 0,
"call_id": "OUlEXakd7SiD0RtbRPhVX5"
},
"evt-tp": "call_state_change",
"timestamp": "2023-07-31T23:25:50.628Z"
},
"event-id": "_dWCx6wNRl_Np2isqJNsAg"
}

3. Play the TTS message:

curl -X POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls/OUlEXakd7SiD0RtbRPhVX5/play_tts' \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello, this is a test call sample for your review."
}'

4. Hangup the call:

curl -X POST 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls/OUlEXakd7SiD0RtbRPhVX5' \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"state":"COMPLETED"
}'

We could also use TTS with SSML for enhanced voice calls.

In the Voice & Messaging Console we can see the call in the Reports / Calls option:

example1 call report SCG console VoiceAPI-TTS.jpg

When double click the call the details are displayed:

Messages API TTS status

As messages, the TTS messages status is no different.

The basic messages statuses are:

CREATED message was created and is in the queue of SCG
SENT message was sent to the outbound delivery system
DELIVERED message was delivered to end-device of the user
READ message was read by the user
FAILED

To retrieve the TTS message status, we could GET the message information with an API call as:

curl -X GET 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages?id=HxRWUnX8jucSafEwzl6Cb3' \
-H "Authorization: Bearer {token}"

R/
{
"list": [
{
"application_id": XXXXX,
"company_id": XXXXXX,
"created_date": 1691596909412,
"last_updated_date": 1691596922680,
"version_number": 3,
"id": "91CGXty7zUy4lGUDet4g2",
"message_request_id": "91CGXty7zUy4lGUDet4g2",
"direction": "MT",
"customer_sender_id": "5XMje4rar39mBLXXXXXXX",
"from_address": "1201882XXXX",
"to_address": "+1346787XXXX",
"state": "DELIVERED",
"body": "<speak>My name is <break time=\"1s\" />John Smith.</speak>",
"sent_date": 1691596909603,
"attachments": [],
"type": "VOICE",
"destination_country": "USA",
"price": 0.0,
"sender_id_alias": "5XMje4rar39mBLXXXXXXX",
"fragments_info": [
{
"fragment_id": "xcKUQwEDdnVWE6QtXBHhK",
"fragment_state": "SENT",
"charge": 0.0,
"external_id": "2cCNLFsJTmlc07IyOXXXXX",
"delivery_report_reference": "xcKUQwEDdnVWE6QtXBHhK"
}
],
"consent_requirement": "NONE",
"standalone": true,
"request_body": "<speak>My name is <break time=\"1s\" />John Smith.</speak>",
"contact_delivery_address_priority": [],
"from": "5XMje4rar39mBLXXXXXXX",
"mediaURL_attachIds": [],
"to": "+1346787XXXX",
"sender_id_sort_criteria": [],
"request_start_time": 1691596909395
}
],
"limit": 50,
"total": 1
}

Another way to get the TTS message status is to configure a DR subbscription. It is important to note that as in this case we are using the Messages API, the ESS subscription must use the topic related to messages: SCG-Message and use a status change event like message_state_change.

For further information about message status click here

Voice calls status

As calls very particular way of processing, SCG have a different set of calls status

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

Eventually, all calls are completed, as no call keeps active indefinitely. To gather information about how the call ended another field can be assessed: failure_code" and "failure_details":

Example: a completed call that ended by hang up. When the call is hanged up we can retrieve the call information from SCG with the cURL:

curl -X GET 'https://api.syniverse.com/scg-external-api/api/v1/calling/calls?id=HxRWUnX8jucSafEwzl6Cb3' \
-H "Authorization: Bearer {token}" 

R/
{
"list": [
{
"application_id": XXXXX,
"company_id": XXXXXX,
"created_date": 1691156612938,
"last_updated_date": 1691156644451,
"version_number": 4,
"id": "HxRWUnX8jucSafEwzl6Cb3",
"from": "5XMje4rar39mBLXXXXXXX",
"from_address": "1201882XXXX",
"to": "+5066173XXXX",
"to_address": "+5066173XXXX",
"destination_country": "CRI",
"answer_timeout": 30000,
"state": "COMPLETED",
"direction": "OUT",
"start_time": 1691156612936,
"answer_time": 1691156622952,
"end_time": 1691156644302,
"chargeable_duration": 60,
"failure_code": 1227,
"failure_details": "Call hangup",
"price": 0.0
}
],
"limit": 50,
"total": 1
}

The most common values in the failure information fields that are set when a call is COMLETED are:

"failure_code": 1201 "No answer"
"failure_code": 1202 "Call rejected"
"failure_code": 1227 "Call hangup"
"failure_code": 1229 "Call cancelled by the originator"
"failure_code": 400 "Invalid sender id/address: sender_id:****"
"failure_code": 500 "Server Error"

Another way to get the TTS call status is to configure a DR subscription. It is important to note that as in this case we are using the Calls API, the ESS subscription must use the topic related to calls: SCG-Voice-Call and use a status change event like call_state_change.

For further information about calls status click here

Messages API - TTS

Calls API - TTS

Messages API TTS status

Voice calls status

0 Comments