Messaging - Authenticate using voice call
NOTE:
To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.
This page guides you step-by-step through how to use Telesign Messaging to authenticate an end user using a voice call. This authentication use case requires using otp_voice as the template name. It includes two parameters: otp_code and language.
Before you begin
Make sure you have the following before you start:
- Messaging: Contact our Customer Support team to request that Messaging is enabled in your account.
- Voice: Also request that our Customer Support team enable Voice in your account.
- Voice caller ID: Purchased from Telesign and enabled.
- Transaction Callback Service and GetStatus: These are available as optional features to provide additional details regarding your transactions. Contact our Customer Support team to enable these features in your account.
Steps
- Send a
POST /v1/omnichannelrequest. Go to Send a message with advanced features for more information. Include the following param values when sending a voice message:
| Parameter | Value | Description | Required? |
|---|---|---|---|
channels | array of channel objects | Add channel objects to the array in the order you want the service to try the channels. | yes |
channels[0] | {"channel":"voice"} | Include voice as the first channel. | yes |
channels[0].fallback_time | A time in seconds. | Specify the time to wait before cascading to the next channel. | no |
message.voice.template | otp_voice | The name of the template to use for this message. | yes |
message.voice.parameters.otp_code | OTP code provided by you. | The digits will be voiced over in the language provided by you. E.g. 1234 will be said as "one-two-three-four" (in English). | yes |
message.voice.parameters.language | Language provided by you. | This is the language in which the end user will hear during incoming calls. See this table for available language formats. English is the default language if one is not provided. | no |
Request example
{
"recipient": {
"phone_number": "9876543210"
},
"channels": [
{
"channel": "voice"
}
],
"message": {
"voice": {
"template": "otp_voice",
"parameters": {
"otp_code": "11111",
"language": "en"
}
}
},
"message_type": "OTP"
}
- If the request is processed successfully, you should see a response with a 3001 status code.
{
"status": {
"code": 3001,
"description": "Message in progress"
},
"reference_id": "35C8B5D509BC10689196FED2AD551B8A",
"external_id": null
}
-
If the voice call request is placed successfully, the end user receives a voice call on their device. When the call is answered by the end user, the authentication message will be played twice.
-
If the sending of voice call transaction fails, the service tries to send the next specified backup channel (if any).
-
Updates on the status of this message are sent to the callback URL for your Transaction Callback Service. GetStatus can be also used to get details about the status of the transactions.
Callback delivery status examples
Successful callback delivery status example
{
"body": {
"channel_status": [
{
"voice": {
"code": 3000,
"description": "Delivered",
"reference_id": "5646FAEF5E7C0264939050C56BB30003",
"updated_on": "2024-09-04T20:31:28.951"
}
}
],
"mcc": "220",
"mnc": "05;09;20;11",
"reference_id": "5646FAEF5D18010C91E24ACE1DF34065",
"status": {
"channel": "voice",
"code": 3000,
"description": "Delivered",
"updated_on": "2024-09-04T20:31:28.951"
}
}
}
Unsuccessful callback delivery status example
{
"channel_status": [
{
"voice": {
"code": 3110,
"description": "Invalid request",
"reference_id": "0716c630-22f4-4a50-b218-391c066993be",
"updated_on": "2024-08-05T09:54:46.083656Z"
}
}
],
"mcc": "220",
"mnc": "01",
"reference_id": "C64487D9DAB8010C89E54EAD1FFD0D67",
"status": {
"channel": "voice",
"code": 3003,
"description": "Delivery error",
"updated_on": "2024-08-05T09:54:46.083656Z"
}
}
GetStatus response examples
GET https://rest-ww.telesign.com/v1/omnichannel/5646FAEF5D18010C91E24ACE1DF34065
{
"status": {
"updated_on": "2024-09-04T20:31:28.951",
"code": 3000,
"description": "Delivered",
"last_channel": "voice"
},
"reference_id": "5646FAEF5D18010C91E24ACE1DF34065",
"additional_info": {
"mcc": "220",
"mnc": "05;09;20;11"
},
"channel_status": [
{
"voice": {
"code": 3000,
"description": "Delivered",
"reference_id": "5646FAEF5E7C0264939050C56BB30003",
"updated_on": "2024-09-04T20:31:28.951"
}
}
],
"verify": {
"code_entered": null,
"code_state": "UNKNOWN"
}
}
GET https://rest-ww.telesign.com/v1/omnichannel/5646FAEF5D18010C91E24ACE1DF34065?verify_code=12345
For this example, the path also includes verify_code as the query parameter - see line 23 to 25.
{
"status": {
"updated_on": "2024-09-04T20:31:28.951",
"code": 3000,
"description": "Delivered",
"last_channel": "voice"
},
"reference_id": "5646FAEF5D18010C91E24ACE1DF34065",
"additional_info": {
"mcc": "220",
"mnc": "05;09;20;11"
},
"channel_status": [
{
"voice": {
"code": 3000,
"description": "Delivered",
"reference_id": "5646FAEF5E7C0264939050C56BB30003",
"updated_on": "2024-09-04T20:31:28.951"
}
}
],
"verify": {
"code_entered": "12345",
"code_state": "VALID"
}
}
NOTE:
In addition to the reference ID for the Messaging transaction itself, the delivery status payload also includes a reference ID for the message-send on each channel. These can be useful for troubleshooting purposes.
Updated 10 days ago