MENU
    Search... Close
    View All Products
    Viber
    Shared Components

    Viber over API

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

    Business Messages API

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

    Follow the Authentication guide to secure your connection with Infobip.

    Outbound messages

    You can send the following types of messages over API:

    Bulk messages

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

    Message template

    Note

    This message type is available only in Russia, Belarus, and Ukraine.

    In Russia, Belarus, and Ukraine, 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.

    If your business is based in any of the countries listed in this section, and you want to send transactional messages to customers who are outside these countries, you must use two accounts - one to communicate with customers within the above countries and the other for customers in all other countries.

    Failover to SMS

    Add a failover to SMS option in case your Viber message does not reach the end user within the defined period. The failover option is applicable for all message types.

    Primary device

    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

    • 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, .gif, .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.

    Inbound messages

    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

    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 "notifyUrl" field 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.

    URL shortening and tracking

    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

    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:

    • Default shortened URL: Shortens the entire URL.

      Example:

      Message with original URL:
      "To find out more about business messages, go to https://www.infobip.com/docs/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 such that it retains the custom domain.

      You can use custom domain URL shortening only for URLs that contain a custom domain (subdomain). Example: www.dev.infobip.com. You cannot use custom domain URL shortening for URLs that contain a primary domain. Example: www.infobip.com.

      Example:

      Message with original URL:
      "To find out more about business messages, go to https://www.dev.infobip.com/docs/api/channels/viber"

      Message with custom domain shortened URL:
      "To find out more about business messages, go to https://www.dev.infobip.com/x5T3jd2Y"
      In this example, the URL content after the custom domain 'www.dev.infobip.com' is shortened.

    • Protocol removal: Removes the 'http' or 'https' prefix from the URL and shortens the URL as follows:

      • URLs that contain a primary domain: Shortens the entire URL.
        Example:

        Message with original URL:
        "To find out more about business messages, go to https://www.infobip.com/docs/viber/business-messages"

        Message with protocol removed and URL shortened:
        "To find out more about business messages, go to rrj.nu/x5T3jd2Y"

        In this example, the entire URL is shortened, and the protocol is removed.

      • URLs that contain a custom domain (subdomain). Shortens the URL such that it retains the custom domain.

        Example:

        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"

        In this example, the custom domain is retained, the URL content after the custom domain 'www.dev.infobip.com' is shortened, and the protocol is removed.

    URL tracking

    You can track the number of clicks for a URL.

    Specify the trackingUrl and set trackClicks to true.

    • JSON
    {
    ...
    "urlOptions": {
        "shortenUrl": true,
        "trackClicks": true,
        "trackingUrl": "https://webhook.site/077a5470-42f9-471f-a7f2-c67d5b*****",
        "removeProtocol": true,
        "customDomain": "m.infobip.com"
    }
}

    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
    {
  "notificationType": "CLICKED",
  "recipient": "38591*******",
  "url": "https://www.infobip.com",
  "sendDateTime": 1603440470723,
  "messageId": "303440456940035*****",
  "recipientInfo": {
    "deviceType": "Phone",
    "os": "Android 10",
    "deviceName": "Unknown"
  }
}

    OMNI API

    To send Viber messages over API, you need to set up your scenario. Refer to our API reference to help you out. 

    Create scenario 

    The first step is to create an OMNI scenario. In the OMNI scenario configuration, define the OMNI steps which will be executed separately.

    As the Viber sender (“channel”: “VIBER” flow) use the one provided during the activation process—the phone number in the international format that was activated for you (e.g., 385981234567). You need to have a secure connection. Either use Base64 hash combination of Infobip credentials, API keys (recommended), or tokens. Refer to API Authentication for instructions.

    Request example

    • JSON
    {
  "from": "InfoSMS",
  "channel": "SMS"
},
{
  "from": "3045",
  "channel": "VIBER"
}

    Create the scenario during the initial phase only. You are not required to repeat this step every time you want to send a message. You create a scenario when adding new channels in a failover scenario or when you want to change the sender.

    To use this as a default scenario, set the default value to true. From this point on, scenarioKey is not a mandatory parameter when sending the message.

    • JSON
    {
  "from": "InfoSMS",
  "channel": "SMS"
},
{
  "from": "3045",
  "channel": "VIBER"
}

    Store the key parameter because it will be used when sending the message.

    Default scenario

    The first scenario you create for the account will be used as the default scenario. It will be used until you set another scenario to be the default one. To change this, set the default value to true.

    Response format

    If successful, the response header HTTP status code will be 201 CREATED and the scenario will be created.

    If you try to create the scenario without authorization, you will receive a 401 Unauthorized error.

    If you use this method too often in a short period of time, you will get the status code 429 Too Many Requests. This prevents misusing the method to create a lot of unnecessary scenarios.

    Once you create your scenario, you can always reference it via the scenario key and reuse it as many times as you like for sending OMNI messages. There is no need to create a new scenario for each OMNI message.

    Send OMNI messages

    Once you’ve created your OMNI scenario (identified by the key parameter) as described in the Create Scenario section, you are ready to send your OMNI messages through defined Viber and SMS communication channels.

    1. Send a Viber message to the defined phoneNumber.
    2.  If, for some reason, the message is rejected on the Viber application or the end-user doesn’t have the Viber application installed, the message is sent via SMS.

    For sending OMNI messages, you can use the advanced API method. Refer to the OMNI: Send an advanced message article on our Infobip API Developer Hub.

    The parameters that should be set are the scenarioKey, phoneNumber and specific text for each communication channel.

    The default validity period in OMNI is 48h for both Viber and SMS messages.

    Response example

    • JSON
     {
      "to":{
      "phoneNumber": "41793026727"
    }
  }
],
"viber": {
  "text": "This Viber message will be delivered to Viber application on the user device."
},
"sms": {
  "text": "This is the SMS failover message"
}

    Send rich messages over Viber

    Here’s how to send Viber messages containing text, images, and CTA buttons. You can configure the custom validity period for each communication channel.

    Any combination of text, image or buttons is allowed. The buttonUrl and buttonText are mandatory.

    • JSON
    {
       "to":{
       "phoneNumber": "41793026727"
     }
   }
 ],
"viber": {
   "text": "This is the message which will be displayed in Viber Application. It can contain up to 1000 characters. ",
   "imageURL": "http://www.infobip.com/infobip-logo.png",
   "buttonText": "More information",
   "buttonURL": "http://www.infobip.com/",
   "isPromotional": true,
   "validityPeriod":1
 },
 "sms": {
   "text": "This text will be received via SMS if Viber message is not delivered.",
   "validityPeriod":1
 }

    Supported image formats: JPEG, JPG, PNG. Emojis can be sent over the Viber channel via API as well and enhance the end-user experience.

    Failover to SMS

    Add a failover to SMS option in case your Viber message does not reach the end user within the defined period. The failover option is applicable for all message types.

    Primary device

    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

    • 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, .gif, .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.

    Delivery reports

    Once you’ve successfully sent your message using the advanced API method you can check the status of sent messages using the OMNI reports method.

    The simplest way is to use the method without any query parameters. In that case, the response will contain all messages sent to a specific account.

    The response will contain all messages, both rejected and delivered, as shown in the example below.

    Response

    • JSON
    { 
   "results":[ 
      { 
         "messageId":"1215f543ab19-345f-adbd-12ad31451ed25f35",
         "to":"41793026731",
         "messageCount": 1,
         "sentAt":"2016-02-23T17:41:11.833+0100",
         "doneAt":"2016-02-23T17:41:11.843+0100",
         "mccMnc":"22801",
         "price":{ 
            "pricePerMessage":0.0104,
            "currency":"EUR"
         },
         "status":{ 
            "groupId":2,
            "groupName":"UNDELIVERABLE",
            "id":9,
            "name":"UNDELIVERABLE_NOT_DELIVERED",
            "description":"Message sent not delivered"
         },
         "error":{ 
            "groupId":1,
            "groupName":"HANDSET_ERRORS",
            "id":6,
            "name":"EC_ABSENT_SUBSCRIBER_SM",
            "description":"Absent Subscriber",
            "permanent":false
         },
        "channel": "VIBER"
      },
      { 
         "messageId":"2315d543441c-335f-1d3d-142d31451ed25f35",
         "to":"41793026731",
         "sentAt":"2016-06-23T17:40:31.773+0100",
         "doneAt":"2016-06-23T17:40:31.787+0100",
         "messageCount":1,
         "mccMnc":"22801",
         "price":{ 
            "pricePerMessage":0.01,
            "currency":"EUR"
         },
         "status":{ 
            "groupId":3,
            "groupName":"DELIVERED",
            "id":5,
            "name":"DELIVERED_TO_HANDSET",
            "description":"Message delivered to handset"
         },
         "error":{ 
            "groupId":0,
            "groupName":"OK",
            "id":0,
            "name":"NO_ERROR",
            "description":"No Error",
            "permanent":false
         },
        "channel": "SMS"
      }
   ]
}

    For a complete list of all API statuses and error codes, refer to the Response status and error codes article.

    NOTE

    You can also have delivery reports forwarded to your URL in real time. In that case, provide the URL to your dedicated Account Manager and they will set it up for you.

    Real-time delivery reports

    Delivery reports that are forwarded to your URL in real-time have a different format than the one that is retrieved using the OMNI reports method.

    • JSON
     {
    "results": [{
        "bulkId": "",
        "price": {
            "pricePerMessage": 0,
            "currency": "EUR"
        },
        "status": {
            "id": 5,
            "groupId": 3,
            "groupName": "DELIVERED",
            "name": "DELIVERED_TO_HANDSET",
            "description": "Message delivered to handset"
        },
        "error": {
            "id": 0,
            "name": "NO_ERROR",
            "description": "No Error",
            "groupId": 0,
            "groupName": "OK",
            "permanent": false
        },
        "messageId": "fb469d73-d362-463f-b30f-1e959b53badc",
        "doneAt": "2019-04-09T16:01:56.494-0300",
        "messageCount": 1,
        "sentAt": "2019-04-09T16:00:58.647-0300",
        "to": "41793026731",
        "channel": "VIBER"
    }]
}
    Manage Connection Reports and Insights
    PAGE CONTENT

    Copyright © 2006-2023 Infobip ltd.

    Elapsed time: 0.6916 / Memory usage: 8.1MB