Viber over API

To send Viber messages over API, you need to set up your scenario. Please 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

{
  "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.

{
  "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

 {
      "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.

{
       "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.

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

{ 
   "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.

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.

 {
    "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"
    }]
}