Viber API Documentation7.1.0

Docs / Viber REST API - Broadcast Message

Viber REST API - Broadcast Message

The Broadcast API is used to send messages to multiple recipients with a rate limit of 500 requests in a 10 seconds window.

Send Broadcast Message

The broadcast_message API allows accounts to send messages to multiple Viber users who subscribe to the account. Sending a message to a user will be possible only after the user has subscribed to the Public Account by pressing the subscribe button or by sending a message, or by sending a message to a bot. The ability to send broadcast messages is only opened on application and approval from Viber account managers.

The API supports a variety of message types: text, picture, video, file, location, sticker, contact, carousel content and URL.

Validation

Maximum total JSON size of the request is 30kb. The maximum list length is 300 receivers.

Resource URL

https://chatapi.viber.com/pa/broadcast_message

Parameters

This API method uses the same parameters as the send REST API method with a few variations described below.

broadcast_list

This mandatory parameter defines the recipients for the message. Every user must be subscribed and have a valid user id. The maximum list length is 300 receivers. For example (this should be a part of the full JSON body):

{  
   "broadcast_list":[  
      "ABB102akPCRKFaqxWnafEIA==",
      "ABB102akPCRKFaqxWna111==",
      "ABB102akPCRKFaqxWnaf222=="
   ]
}

Place holders

Broadcast message can contain place holders that will be replaced with receiver information (each receiver will get it’s own information). The place holders can appear anywhere in the message, even in tracking data. The list of the place holders:

Post example

The following example demonstrates send carousel content with place holders (replace_me_with_receiver_id, replace_me_with_url_encoded_receiver_id, replace_me_with_user_name) to 4 receivers:

{
   "sender":{
      "name":"John McClane",
      "avatar":"http://avatar.example.com"
   },
   "min_api_version":2,
   "type":"rich_media",
   "broadcast_list":[
      "pttm25kSGUo1919sBORWyA==",
      "2yBSIsbzs7sSrh4oLm2hdQ==",
      "EGAZ3SZRi6zW1D0uNYhQHg==",
      "kBQYX9LrGyF5mm8JTxdmpw=="
   ],
   "rich_media":{
      "Type":"rich_media",
      "BgColor":"#FFFFFF",
      "Buttons":[
         {
            "ActionBody":"https://www.google.com",
            "ActionType":"open-url",
            "Text":"Should get back my ID instead of replace_me_with_receiver_id"
         },
         {
            "ActionBody":"https://www.google.com",
            "ActionType":"open-url",
            "Text":"Should get back my URL encoded ID instead of replace_me_with_url_encoded_receiver_id"
         },
         {
            "ActionBody":"https://www.google.com",
            "ActionType":"open-url",
            "Text":"Should get back my name instead of replace_me_with_user_name"
         }
      ]
   }
}

Response example

Response parameters

Name Description Possible values
message_token Unique ID of the message  
status Action result 0 for success. In case of failure – appropriate failure status number. See error codes table for additional information
status_message ok or failure reason Success: ok. Failure: invalidUrl, invalidAuthToken, badData, missingData and failure. See error codes table for additional information
failed_list Contains all the receivers to which the message could not be sent properly See error codes table for additional information
{
   "message_token":40808912438712,
   "status":0,
   "status_message":"ok",
   "failed_list":[
      {
         "receiver":"pttm25kSGUo1919sBORWyA==",
         "status":6,
         "status_message":"Not subscribed"
      },
      {
         "receiver":"EGAZ3SZRi6zW1D0uNYhQHg==",
         "status":5,
         "status_message":"Not found"
      }
   ]
}