Messaging - Send Viber verification message
NOTE:
To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.
This page walks you step-by-step through how to use Telesign Messaging to send a Viber verification message to an end user. Viber’s verification messages are designed for sending one-time passwords (OTP) using a pre-designed and pre-approved template. By sending messages using this type of transaction, you could get the lowest rate for domestic traffic compared to SMS and other Viber business message types.
Before you begin
Make sure you have the following before you start:
- Transaction Callback Service: You need to have this set up so Telesign can send you delivery status updates for your Messaging requests. See Messaging - Callback service for more details.
- Viber account details: To send a message using Viber, you first need to provide the details specified on the Set up Viber for your account page to our Customer Support Team.
NOTE:
The Transaction Callback Service is where you get delivery status updates from the recipient of your message. While this page uses Transaction Callback Service for delivery status updates, you can also use Get transaction status to get delivery status and other details for any Messaging transaction.
CAUTION:
If an end user does not have Viber, the Viber send will fail. We recommend either ensuring your end users have Viber on their devices or including a fallback channel for users without Viber.
Steps
- Send a
POST /v1/omnichannel
request. Include the following param values:
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 |
channel[0] | {"channel":"viber"} | Include viber 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 |
channels[1] | {"channel":"sms"} | Include sms as the backup channel. | yes (if SMS is used for backup) |
message.viber.template | otp_verify | Specify the name of the predefined template used for a Viber verification message. | yes |
message.viber.parameters.otp_code | String | Specify the one-time password (OTP) to display in the message. | yes |
message.viber.parameters.language | String | Specify the optional language used for the verification template. If not provided, defaults to English. | no |
message.sms.template | text | Specify SMS as your preferred backup channel, using the text template. You can use a different backup channel and template if you prefer. | no |
message.sms.parameters.text | Some text. | Text to display in the message. | yes (if text template is used for backup) |
Request example
POST /v1/omnichannel HTTP/1.1
Content-Type: application/json
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Host: rest-ww.telesign.com
{
"channels": [
{
"channel": "viber",
"fallback_time": 600
}
],
"phone_number": "15558675309",
"message": {
"viber": {
"template": "otp_verify",
"parameters": {
"otp_code": "12345",
"language": "it"
}
}
},
"message_type": "OTP"
}
- If the request is processed successfully, you should see a response with a
3001
status code.
Response example
HTTP/1.1 200 OK
Server: nginx/1.17.7
Date: Wed, 14 Oct 2020 21:25:54 GMT
Content-Type: application/json
Content-Length: 137
Connection: keep-alive
Allow: GET,POST,HEAD
{
"status": {
"code": 3001,
"description": "Message in progress"
},
"reference_id": "35C8B5D509BC10689196FED2AD551B8A",
"external_id": null
}
- If the send in Viber format is successful, your end user receives a message on their device that looks like this. This message has pre-defined content by Viber and cannot be changed.
- If the send in Viber format fails, the service tries to send the next specified backup channel (if any). If an invalid language code is sent, HTTP status code 3110 (Invalid request) is returned.
- Updates on the status of this message are sent to the callback URL for your Transaction Callback Service. The general callback schema common to both this and other products is described on Transaction Callback Service. Modifications to the callback schema for this product are described on Messaging - Callback service. Search for these callbacks based on the reference ID in the response to your original Messaging request. Each callback payload includes an object with the status of the send for each channel that is tried.
Callback example
GET /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
"reference_id": "35C8B5D509BC10689196FED2AD551B8A",
"external_id": "null",
"status": {
"code": 3000,
"description": "Delivered",
"last_channel": "viber",
"updated_on": "2020-05-04 22:07:01:226"
},
"channel_status": [
{
"viber": {
"code": 3000,
"description": "Delivered",
"reference_id": "65C77D4A6C5C09085694EFB6C554D2BF",
"updated_on": "2020-05-04 22:07:01:226"
}
}
]
}
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.
Localization
The template is localized to 33 languages which can be selected when sending the message.
The message.viber.parameters.language
is optional when sending the request. If a language is not specified, the default value will be the device language. If device language is not supported, the message will be presented in English. The language code will be validated according to ISO 639-1 two-letter encoding.
Language | Code (ISO 639-1) |
---|---|
English | en |
Arabic | ar |
Belarusian | be |
Bulgarian | bg |
Burmese | my |
Croatian | hr |
Czech | cs |
Danish | da |
Dutch | nl |
Finnish | fi |
French | fr |
German | de |
Greek | el |
Hebrew | he |
Hungarian | hu |
Indonesian | id |
Italian | it |
Japanese | ja |
Norwegian | nb |
Persian | fa |
Polish | pl |
Portuguese (Brazil) | br |
Portuguese (Portugal) | pt |
Romanian | го |
Russian | ru |
Serbian | sr |
Slovak | sk |
Spanish | es |
Swedish | sv |
Thai | th |
Turkish | tr |
Ukrainian | uk |
Vietnamese | vi |
Updated 9 days ago