Send Viber over API

Use our simple API to send messages to your customers. Check out below on how to set up the scenario and send different types of messages via Viber using API.

Create Scenario 

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

Resource

https://{base_url}/omni/1/scenarios

Parameters

Property name

Type

Description

name*

string

OMNI scenario name.

from

string

Sender used in OMNI scenario's step for sending the message.

channel

string

Channel used in scenario's step for delivering the message (SMS, Voice, Viber, Facebook, Email, Push, VK, 

WhatsApp).

default

boolean

Indicates if this created scenario should be set as a default.

The connection itself has to be secured either by using Base64 hash combination of Infobip credentials, API keys or tokens as this is the most secure and recommended option. To enable a secure connection towards Infobip, refer to Security and Authorization.

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).

Request example

POST /omni/1/scenarios HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
  "name":"Test SMS or Viber",
  "flow": [
    {
      "from": "InfoSMS",
      "channel": "SMS"
    },
    {
      "from": "3045",
      "channel": "VIBER"
    }
  ],
  "default": false
}
NOTE

You need to create the scenario during the initial phase only. You are not required to go repeat this step every time you want to send a message. You only need to 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.

Response

{
  "key": "CD265875E3A6EA43478D5F37A635BE4A",
  "name":"Test SMS or Viber",
  "flow": [
    {
      "from": "InfoSMS",
      "channel": "SMS"
    },
    {
      "from": "3045",
      "channel": "VIBER"
    }
  ],
  "default": false
}

The “key” parameter needs to be stored as it will be used when sending the message.

Default Scenario

The first scenario created on the account will be used as the default scenario.

When sending OMNI messages, this default scenario will be used until another one is updated to be the default scenario. To set a scenario as a default one, change 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.

NOTE

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

Scenario

Parameter

Type

Description

key

string

Key used to uniquely identify OMNI scenario.

name

string

OMNI scenario name.

flow

step

Sender used in OMNI scenario’s step for sending the message.

default

boolean

Whether the scenario is a default scenario.

Step

Parameter

Type

Description

from

string

Sender used in OMNI scenario’s step for sending the message.

channel

string

Channel used in scenario’s step for delivering the message (SMS, Voice, Viber, Facebook, Email, Push).

Send OMNI Messages

Once you’ve created an 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.

First, the VIBER message will be sent to the defined phoneNumber.

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 will be sent using the SMS communication channel.

For sending OMNI messages, you can use the advanced API method. For more details on how to 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 channels.

Parameters

Property name

Type

Description

phoneNumber*

string

Destination phone number. Addresses must be in international format (e.g., 41793026727).

messageId

string

The ID that uniquely identifies the sent message.

scenarioKey

string

Scenario key that uniquely identifies the scenario which will be used when sending the message. If this field is not set, the default scenario will be used.

sms

object

SMS specific data. The data will be used if the message is sent through SMS channel.

viber

object

Viber specific data. The data will be used if the message is sent through Viber channel.

email

object

Email specific data. The data will be used if the message is sent through email channel.

text

string

Text of the message that will be sent.

validityPeriod

int

The message validity period. Unless specified differently in validityPeriodTimeUnit, it is expressed in minutes. When the period expires, the message will be automatically sent using the next OMNI step. Validity period that’s longer than 48h is not supported (in this case, it will be automatically set to 48h). Additionally, the validity period should be longer than 30 seconds.

validityPeriodTimeUnit

string (MINUTES)

The message validity period time unit, allowing finer time granulation. Supported values are: SECONDS, MINUTES, and HOURS.

sendAt

datetime

Date and time when the message is to be sent. Used for scheduled OMNI messaging (first message in the OMNI flow not sent immediately, but at scheduled time).

INFO

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

Response

POST /omni/1/advanced HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{ 
	"scenarioKey":"CC9F01A5DC7BEE2C2B829D203482A654",  
  "destinations":[ 
  	{ 
    	"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. The example also shows how to configure the custom validity period for each communication channel.

Parameters

Parameter

Type

Description

text

string

Text of the message that will be sent. Max 1000 characters.

imageURL

string

URL of the image sent in the Viber message.

buttonText

string

Viber button label. Max 20 characters.

buttonURL

string

Viber Button Call To Action. Should contain URL or telephone number to call. Format for telephone number is tel:.

isPromotional

boolean

Indicates if message is promotional.

validityPeriod

string

The message validity period in minutes. When the period expires, the message will be automatically sent using the next OMNI step. Validity period should be at least 40 seconds.

Any combination of text, image or buttons is allowed. The only constraint when sending the button that the buttonUrl and buttonText are mandatory!

Request example

POST /omni/1/advanced HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{ 
	"scenarioKey":"CC9F01A5DC7BEE2C2B829D203482A654",  
  "destinations":[ 
  	{ 
    	"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
  }
}
INFO

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.

GET /omni/1/reports HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

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

HTTP/1.1 200 OK
Content-Type: application/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.

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