Voice 101 #2: API Integration
We have already talked about the voice services and explained how they work, but now it’s time time to learn more about the Voice API and the integration of it.
Voice messaging can inform customers about the latest promotions or offers, deliver information about updates or PINs for 2-Factor Authentication – depending on your business needs. It can reach landline phones and allow your brand communications to be more inclusive – they can be listened to by the visually impaired.
What you probably care about the most is the information flow security for your customers while you deliver sensitive information. An automated voice call, that can be initiated every time a fraud is attempted, assures the customer that his information has been handled with care. This is just one of the many examples of using voice messages, but check out the Voice API and give it a try.
How to use the Voice API
Our Voice API is a simple REST API. For originating calls, you must submit a POST HTTP request with well-structured body. In response to that request you will get a token, which is used for identifying originated calls. The token can be used for pooling the call status or call detailed record (CDR) – an object containing detailed information about call.
This API provides several features, which include playing voice message to the end user, recording the entire call and getting the download URL of the recorded file, retrying calls if necessary and providing user input in CDR.
Start integrating
After a short intro about voice messaging and voice API, it is time to start integrating. Voice API allows you to send a:
- Single voice message:
- Multiple voice message:
- Fully featured voice message, that includes sending an advanced voice message with all the available features and parameters:
Here are some additional tips and tricks when posting the request:
- a pause between words can be added to extend the duration of voice messages and it can be done by using the comma character “,” where each comma creates a pause of 0.5 seconds. If you want to have a 2 sec pause, each word it should look like this: “this,,,,is,,,,a,,,,test,,,,”
- there are no ring timeout limitations on the voice platform, but most of the operators have their own ring timeout limitations, so our advice is to keep the ringTimeout value up to 45secs
- answering machine detection is just an attempt based upon patterns in audio stream after receiving an answer signal from the operator. There are two possible values – disable and hangout. The default value, in case the machineDetection parameter is not set, is disable. This value represents no usage of AMD option, and during the call there won’t be any attempts in detecting answering machine. If the machineDetection parameter is set to hangup, voice platform will detect the answering machine, and in case it detects it, it will hang up immediately
Creating actions and action groups
Actions and action groups allow you to send interactive messages to your subscribers, giving them the opportunity to respond by simply pressing their phone keys. Actions are determined by a condition for which action groups are performed. Both, actions and action groups, are JSON formatted.
Actions can be set for any DTMF:
Or, they can be set for a specific DTMF:
Also, you can see the full example with actions and actionGroups parameters here, along with the response.
Delivery reports and message logs
To be sure that your voice message has been delivered you can check the delivery report. Delivery reports can be returned without any query parameters and only once, while any additional request would return an empty collection:
If you want to, you can get two initial delivery reports, too:
Similar to delivery reports, you can get logs for the last 48h, for sent voice messages. The message logs can be pulled without any query parameters, with filters (from, to and limit), or by multiple bulkIds.
A flexible API allows you to craft a solution that fits your needs. This more personalized way of communicating with your customers solves a major challenge of today’s communications. Knowing that you can very quickly and easily connect with your customers using this cost effective channel, without additional complications, deeply wideness your communications scope.