Messaging - Send video with Viber
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 message to an end-user that includes a video file. The video file is hosted by you. This page only documents the use of the video
template. Telesign also supports two other templates that send video messages in Viber: text_video
and url_action_video
. Contact us if you need assistance using any of these templates.
Format and size restrictions
Video format: Viber accepts .3gp, .m4v, .mov, .mp4 videos.
Video file size: The size limitation for a video file is 200 MB. To ensure that your video meets the size requirements, Telesign handles the requirements for providing the size of the video file (in bytes), the duration (in seconds), and the video’s thumbnail URL when you send the request.
The video will be downloaded to the user’s device by pressing it in the received message only if the file meets the size and format limitations.
Content requirements
Although this restriction is subject to change, Viber currently does not allow the use of links which navigate to the following apps:
- Line
- Signal
- Telegram
This restriction is applied both to the content of messages and links that you use in your Viber commercial account and business chat info pages (business website, description etc.)
See Viber's documentation for any other content restrictions.
Validation
Viber uses a validation process runs in its backend for each sent request to confirm that it meets all of its mandatory API requirements including any specific parameter requirements.
To ensure that all your sent files are validated and downloadable, each video’s server host must allow Viber’s client the ability to verify the file header to make sure the file meets its technical limitations. A video that will not allow a headers investigation might not allow users who receive it to download the file or play the content. The URL you upload your video file to must be hosted on a server that allows HEAD methods and includes the file Content-Length
in the server reply. It is recommended that the video URL include the file extension (.mp4), otherwise, Viber cannot guarantee the URL will be parsed correctly for all devices.
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 also where you would receive inbound replies from the recipient of your message.
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 |
channels[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) |
recipient | An object. | Contains contact information needed to communicate with a recipient for a particular channel. At least one sub-property must be included. | If the phone_number parameter is not included in this request, this parameter is required. |
recipient.phone_number | A string. | The recipient's phone number, as digits without spaces or special characters, beginning with the country dialing code. | yes |
message.viber.template | video | Specify the predefined template that sends a video file in the message. | yes |
message.viber.parameters.reply_id | A string. | This is sent back to the provider when a message sent to a end user is answered. The end user’s reply is linked to the tracking data value that is set in the request. | yes |
message.viber.parameters.url | A fully-qualified URL. | The URL where you are hosting your video file. | yes |
message.sms.template | video | Specify SMS as your preferred backup channel, using the video template. You can use a different backup channel that supports video such as MMS or WhatsApp. | no |
message.sms.parameters.url | A fully-qualified URL | The URL where you are hosting your video file. | yes (if video template is used for backup) |
message_type | MKT | The purpose for which the message is being sent. Since videos are promotional, choose MKT for marketing messages. | yes |
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"
},
{
"channel": "sms"
}
],
"recipient": {
"phone_number": "11234567890"
},
"message": {
"viber": {
"template": "video",
"parameters": {
"reply_id": "nxjs634!",
"url": "https://example.com/viber/video_placeholder_name.mp4"
}
},
"sms": {
"template": "video",
"parameters": {
"url": "https://example.com/viber/video_placeholder_name.mp4"
}
}
},
"message_type": "MKT"
}
NOTE:
If the url is the same for the fallback channel, you can also make request like this one:
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" }, { "channel": "sms" } ], "recipient": { "phone_number": "11234567890" }, "message": { "default": { "template": "video", "parameters": { "reply_id": "nxjs634!", "url": "https://example.com/viber/video_placeholder_name.mp4" } } }, "message_type": "MKT" }
- 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 includes the video file.
-
If the send in Viber format fails, the service tries to send to the next specified backup channel (if any).
You will need to ensure that you select a fallback channel that supports video such as MMS or WhatsApp . Alternatively, you can choose to send simple text (no video) with SMS as your backup channel.
-
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": "sms",
"updated_on": "2020-05-04 22:07:01:226"
},
"channel_status": [
{"viber": {
"code": 3056,
"description": "Message failed to deliver in specified fallback time",
"reference_id": "65C77D4A6C5C09085694EFB6C554D2BF",
"updated_on": "2020-05-04 22:05:00.325"
}},
{"sms": {
"code": 3000,
"description": "Delivered",
"reference_id": "65C77D4A6C5C09085694EFB6C558B4C7",
"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.
Updated 13 days ago