Viber Business over API

View as Markdown

Make sure that you are familiar with compliance and guidelines and details of message types before sending Viber messages.

Use the Viber Business Messages API to send conversational, promotional, and transactional messages to the end users.

Follow the Authentication guide to secure your connection with Infobip.

Outbound messages [#outbound-messages-business-messages-api]

You can send the following types of messages over API:

Template
Text
Image
Video
File
Text + call-to-action button
Text + image
Text + video
Text + image + call-to-action button
Text + video + call-to-action button

Message template [#message-template-business-messages-api]

Any transactional (informative) messages that you send to end users must use registered templates that are approved by Viber. These templates must follow a predefined message structure and follow Viber guidelines.

If you send a transactional message that does not use a registered message template, you will be charged at the standard promotional message rate.

To send message templates, contact your dedicated Infobip Account Manager or contact our Sales team by using the Infobip Contact form.

Primary device [#primary-device-business-messages-api]

This section is applicable only for Text and Message templates.

An end user can have Viber installed on more than one device. Example: smartphone, tablet, and desktop. Either the smartphone or tablet is their primary device, and the others are secondary devices.

Any Viber message that you send to the end user will be delivered to all the devices. If you want to force the message to be delivered only to the end user’s primary device, set the toPrimaryDeviceOnly parameter to true in your API request.

Recommendations [#recommendations-business-messages-api]

To send formatted messages, add markdowns to the text string. Refer to the Outbound messages > Text > Text Formatting section. You cannot use text formatting in message templates.
To make sure that media URLs sent over the API are parsed and the content is displayed correctly, follow these guidelines:
- Use only secured HTTPS links in the request.
- Make sure that image URLs are not protected by captcha.
Use the following file formats for images: .jpg, .jpeg, .png, .bmp, .svg, .webp. For detailed specifications, refer to the Outbound messages > Image section.
Use the following file formats for video: .3gp, .m4v, .mov, .mp4. For detailed specifications, refer to the Outbound messages > Video section.
Use the following file formats for files: .csv, .doc, .docx, .dot, .dotx, .eps, .fods, .fodt, .info, .odf, .ods, .odt, .pdax, .pdf, .rtf, .txt, .xls, .xlsx, .xltx, .xps, xlsm. For detailed specifications, refer to the Outbound messages > File section.

Remember to add supplementary options to your send request in case you would like to benefit from our additional features.

Message options [#message-options-business-messages-api]

Additional message options can be applied to your API request.

Bulk messages [#bulk-messages-business-messages-api]

You can send multiple text messages or message templates in a single API request.

Scheduling messages [#scheduling-messages-business-messages-api]

Every communication can be scheduled. You can set a start date, time and time zone. This feature comes in handy when you don’t want to disturb your customers during the night, or you want to send messages only during a specific period for optimal conversion.

json

2 "SendAt": 2015-07-07T17:00:00.000+01:00

An additional scheduling option is to set sending speed limit. For example, you can limit the sending speed when sending messages in bulk to deliver messages over a longer period of time. This feature can be beneficial when you expect recipients to react to your call-to-action embedded within the dispatched message. In that way you could avoid overwhelming your system or agents with an influx of responses from end customers and avoid operational strain. You can set the number (amount) of messages that will be sent periodically. Available time units are: minutes, hours, days.

json

2 "sendingSpeedLimit": {

3 "amount": 30,

4 "timeUnit": "HOUR"

5 }

You can also set a specific message delivery window outside of which messages won’t be delivered. You can set start time (hour/minute), end time (hour/minute) and days of the week. Time is expressed in the UTC time zone.

json

2 "deliveryTimeWindow": {

3 "days": [

4 "MONDAY",

5 "TUESDAY",

6 "WEDNESDAY",

7 "THURSDAY",

8 "FRIDAY",

9 "SATURDAY",

10 "SUNDAY"

11 ],

12 "from": {

13 "hour": 6,

14 "minute": 0

15 },

16 "to": {

17 "hour": 15,

18 "minute": 30

19 }

20 }

Validity period [#validity-period-business-messages-api]

There is a specific time period for messages during which the system will try to deliver them. For example, when you want to send a message to your audience and some users have their cell phones turned off, the system will retry delivery to these users until the validity period passes. The default and also the maximum validity period is 48 hours. It does not need to be set for each request. If you want to set a shorter period, you should define it under Validity period. Available time units are: seconds, minutes, hours. Default value is minutes.

json

2 "validityPeriod": {

3 "amount": 30,

4 "timeUnit": "MINUTES"

5 }

SMS failover [#sms-failover-business-messages-api]

Add a failover to SMS option in case your Viber message does not reach the end user within the defined period. You can also set a validity period for the SMS message.

json

2 "smsFailover": {

3 "sender": "41793026726",

4 "text": "Failover message text",

5 "validityPeriod": {

6 "amount": 2,

7 "timeUnit": "HOURS"

8 }

9 }

Platform [#platform-business-messages-api]

Viber APIs work seamlessly with CPaaS X. This gives you greater flexibility in managing your configurations and resources in whatever manner that suits your needs. For more information about CPaaS X, refer to our CPaaS X documentation.

json

2 "platform": {

3 "entityId": "priorityCustomer",

4 "applicationId": "clientTestEnvironment"

5 }

Webhooks [#webhooks-business-messages-api]

Use the webhooks > delivery > url parameter option if you want users to be able to set the URL where they want to receive API responses. Define the URL under the webhooks parameter of the API request.

json

2 "webhooks": {

3 "delivery": {

4 "url": "https://www.example.com/viberbm"

5 },

6 }

URL shortening and tracking [#url-shortening-and-tracking-business-messages-api]

You can shorten URLs and track the number of clicks for these URLs. You can enable URL shortening without enabling URL tracking. However, to enable URL tracking, you must enable URL shortening.

URL shortening and tracking is supported for the following message combinations:

Text only: URL in the text
Text + image: URL in the text
Text + video: URL in the text
Text + CTA button: URLs in the text and the CTA button
Image + text + CTA button: URLs in the text and the CTA button
Video + text + CTA button: URLs in the text and the CTA button
File: Media URL

URL shortening [#url-shortening-business-messages-api]

Use URL shortening to reduce the length of the URLs that you share with end users. The URL is shortened when you add it to the message body.

You can use the following types of URL shortening:

Type		Description	Example
Default shortened URL		Shortens the entire URL.	Message with original URL: To find out more about business messages, go to `../viber/business-messages` . Message with default shortened URL: To find out more about business messages, go to `https://rrj.nu/x5T3jd2Y` .
Custom domain shortened URL		Shortens the URL in such a way that it retains the custom domain. You can use custom domain URL shortening only for URLs that contain a custom domain (subdomain), for example: `www.dev.infobip.com` . You cannot use custom domain URL shortening for URLs that contain a primary domain, for example `www.infobip.com` .	Message with original URL: To find out more about business messages, go to `https://www.dev.infobip.com/docs/api/channels/viber` . Message with default shortened URL: To find out more about business messages, go to `https://www.dev.infobip.com/x5T3jd2Y` .
Protocol removal	URLs that contain a primary domain	Removes the 'http' or 'https' prefix from the URL and shortens the URL. If a URL contains a primary domain, the entire URL gets shortened.	Message with original URL: To find out more about business messages, go to `../viber/business-messages` . Message with protocol removed and URL shortened: To find out more about business messages, go to `rrj.nu/x5T3jd2Y` .
Protocol removal	URLs that contain a custom domain (subdomain)	Removes the 'http' or 'https' prefix from the URL and shortens the URL. If an URL contains a custom domain (subdomain), the URL is shortened in such a way that it retains the custom domain.	Message with original URL: To find out more about business messages, go to `https://www.dev.infobip.com/docs/api/channels/viber` . Message with protocol removed and URL shortened: To find out more about business messages, go to `www.dev.infobip.com/x5T3jd2Y` .

URL tracking [#url-tracking-business-messages-api]

You can track the number of clicks for a URL.

Specify the trackingUrl and set trackClicks to true.

json

2 {

3 ...

4 "tracking": {

5 "shortenUrl": true,

6 "trackClicks": true,

7 "trackingUrl": "https://webhook.site/077a5470-42f9-471f-a7f2-c67d5b *",

8 "removeProtocol": true,

9 "customDomain": "m.infobip.com"

10 }

11 }

When an end user clicks the URL in the message body, an event is returned to Infobip. This event is recorded in reports and notifications, and you will receive a click notification.

The structure of the data that is passed in the click notification is shown below.

json

2 {

3 "notificationType": "CLICKED",

4 "recipient": "38591 ***",

5 "url": "https://www.infobip.com",

6 "sendDateTime": 1603440470723,

7 "messageId": "303440456940035 *",

8 "recipientInfo": {

9 "deviceType": "Phone",

10 "os": "Android 10",

11 "deviceName": "Unknown"

12 }

13 }

Inbound messages [#inbound-messages-business-messages-api]

Incoming messages are forwarded to you in real-time when you use the API for two-way communication. The messages are forwarded to the endpoint that you provided when you set up your Viber account on Infobip solutions.

To enable messages from the Infobip web interface to be forwarded to an API endpoint, you must grant the relevant permission to the API endpoint. Use additional authorization headers to secure connections.

You can receive the following types of messages from end users:

Text
Image
Video
File

Reports [#reports-business-messages-api]

After you successfully send a message, you can check the status of the sent message. The following reports are forwarded to a defined endpoint:

You can have delivery and seen reports forwarded to your URL in real time. To set this feature, provide the URL to your Infobip Account Manager.

(Optional) You can define the endpoint in the webhooks > delivery > url parameter of the API request of a message. If you do not define this endpoint, the reports are forwarded to the endpoint that is defined in the platform.

Was this page helpful?