Viber API

Create a Viber campaign

To create a Viber campaign, send a POST request to:

https://api.sendpulse.com/viber

Request parameters:

You can use either address_book, or recipients parameter to specify a list of recipients, one of these parameters is required.

You can send the following types of messages:

• System or promo (text only): message parameter only;
• Promo (text + button + image):  message, button, image parameters;
• Promo (text + button): message, button parameters;
• Promo (image): image parameter.

Please note:  when you send a system message ("message_type": 3), the text in the message parameter is checked. It must match the text of the approved template.  You can add and submit a template for approval in your personal account after registering a sender.

Request example to send a message of the Text+Button+Image format:

{
   "recipients":[ // recipients array
      380931111111,
      380931111112,
      380931111113
   ],
   "address_book":null,
    // there are two options avalable: send either an address book ID, or an array of recipients (1000 recipients maximum)
   "message":"Margaret, you have been approved for a 50% discount on all items in the Cosmetics category",
   "message_type":2,
   "message_live_time":1000, //seconds (60 seconds minimum, maximum 86400 seconds(24 hours),
   "sender_id":1, //id of the active user, the campaign will be sent from
   "send_date":"now", // or date in the following format YYYY-MM-DD HH:ii:ss
   "additional":{
      "button":{
         "text":"Buy all cosmetics",
         "link":"https://sendpulse.com/"
      },
      "image":{
         "link":"https://sendpulse.com/images/image.png"
      },
      "resend_sms":{
         "status":true,
         "sms_text":"Text of the sms message",
         "sms_sender_name":"sendpulse"
      }
   }
}

Request example to send a message containing only text:

{
  "recipients": [
    // array of recipients
    380931111111,
    380931111112,
    380931111113
  ],
  "address_book": null,
  // There are two options: either send the address book ID, or send the recipients array, 1000 recipients maximum
  "message": "Margaret, you have been approved for a 50% discount on all items in the "Cosmetics" category",
  // max lenghth is 1000 symbols
  "message_type": 2,
  "message_live_time": 1000,
  //seconds (min 60seconds, max 86400 seconds(24 hours),
  "sender_id": 1,
  //id of an active sender name
  "send_date": "now", 
  // or date in the following format YYYY-MM-DD HH:ii:ss
  "additional": {
    "resend_sms": {
       //status indicating that re-sending is engaged
        "status" : true,
        // sms text
        "sms_text" : "Text of the sms message",
        // sender name sms
        "sms_sender_name" : "sendpulse"
    }
  }
}

Request example to send a message containing only an image:

{
    "recipients": [
      // array of recipients
      380931111111,
      380931111112,
      380931111113
    ],
    "address_book": null,
    // There are two options: either send the address book ID, or send the recipients array, 1000 recipients maximum
    "message": null,    
    "message_type": 2,
    "message_live_time": 1000,
    //seconds (min 60s, max 86400s (24 hrs)
    "sender_id": 1,
    //ID of an active sender name
    "send_date": "now",
    // or date in the following format YYYY-MM-DD HH:ii:ss
    "additional": {
      // additional data
      "image": {
        // image in the message
        "link": "https://sendpulse.com/images/image.png" 
        //image link
      },
      "resend_sms": {
       //status indicating resend option is turned on
        "status" : true,
        // sms text
        "sms_text" : "Text of the sms",
        // sms sender name
        "sms_sender_name" : "sendpulse"
       }
    }
}

Request example to send a message containing text + button:

{
   "recipients":[
      // array of recipients
      380931111111,
      380931111112,
      380931111113
   ],
   "address_book":null,
   // either send the address book ID, or send the recipients array,
   "message":"Margaret, you have been approved for a 50% discount on all items in the ""Cosmetics"" category",
   // max lenghth is 1000 symbols
   "message_type":2,
   "message_live_time":1000,
   //seconds (min 60 seconds, max 86400 seconda(24 hours),
   "sender_id":1,
   "send_date":"now",
   "additional":{
      "button":{
         "text":"Buy all cosmetics",
         "link":"https://sendpulse.com"
      },
      "resend_sms":{
         "status":true,
         "sms_text":"Text of the sms",
         "sms_sender_name":"sendpulse"
      }
   }
}

Request example to send gradually:

{
   "recipients":[
      380683850429
   ],
   "message":"Test",
   "message_type":2,
   "message_live_time":1000,
   "sender_id":4647,
   "send_date":"now",
   "stretch_time":1
}

If request is successful, you will receive a response:

{
    "result": true,
    "data": {
        "address_book_id": null,
        "button_link": null,
        "button_text": null,
        "image_link": null,
        "message":  "Margaret, you have been approved for a 50% discount on all items in the "Cosmetics" category",
        "message_live_time": "1000",
        "message_type": 3,
        "resend_sms": 0,
        "send_date": "2019-03-26 12:40:05",
        "sender_id": 4501,
        "sms_sender_name": null,
        "sms_text": null,
        "task_id": 90241,
        "task_name": "Viber campaign for the personal list on 2019-03-26 12:40"
    }
}

Get a list of campaigns

To get a list of campaigns, send a GET request to:

https://api.sendpulse.com/viber/task

Request parameters:

If request is successful, you will receive a response:

[
    {
        "id": 9380939,
        "name": "Viber campaign for the personal list on 2019-03-26 15:02",
        "message":  "Jane, you have been approved for a 50% discount on all items in the "Cosmetics" category",
        "button_text": null,
        "button_link": null,
        "image_link": null,
        "address_book": null,
        "sender_name": "YAMAMAY",
        "sender_id": 4495,
        "message_live_time": 1000,
        "send_date": "2019-03-29 10:00:00",
        "status": "moderation",
        "created": "2019-03-26 12:50:02"
    },
    {
        "id": 9380926,
        "name": "Viber campaign for the personal list on 2019-03-26 14:48",
        "message":  "Margaret, you have been approved for a 50% discount on all items in the "Cosmetics" category",
        "button_text": null,
        "button_link": null,
        "image_link": null,
        "address_book": 0,
        "sender_name": "YAMAMAY",
        "sender_id": 4495,
        "message_live_time": 1000,
        "send_date": "2019-03-29 10:00:00",
        "status": null,
        "created": "2019-03-26 12:48:23"
    }
]

Response parameters:

Parameter	Type	Description
id	int	Campaign ID
name	string	Campaign name
message	string	Message text
button_text	string	Text on the button,- if not specified, will return null
button_link	string	Clickthrough link,- if not specified, will return null
image_link	string	Image link,- if not specified, will return null
address_book_id	int	Mailing list ID,- if keyed in manually, will return null
sender_name	string	Sender name, that was used to send the campaign
sender_id	int	Sender ID
message_live_time	int	Lifetime of the message (in seconds)
send_date	string	Date that the campaign was sent
status	string	Status of the task
created	string	Date the campaign was created

Get statistics on a campaign

To get statistics on a campaign, send a GET request to:

https://api.sendpulse.com/viber/task/{id}

Request parameters:

If request is successful, you will receive a response:

{
    "id": 19864149,
    "name": "Viber campaign by book",
    "message": "My viber message",
    "button_text": null,
    "button_link": null,
    "image_link": null,
    "address_book_ids": [
        1488435
    ],
    "sender_name": "my_sender",
    "sender_id": 4647,
    "message_live_time": 86400,
    "send_date": "2023-12-18 14:40:34",
    "status": "sent",
    "created": "2023-12-18 14:40:34",
    "stretch_time": 0,
    "resend_sms": true,
    "resend_sms_status": 2,
    "statistic": {
        "sent": 2,
        "delivered": 1,
        "read": 1,
        "redirected": 0,
        "undelivered": 1,
        "errors": 0
    }
}

Response parameters:

Parameter	Type	Description
id	int	Campaign ID
name	string	Campaign name
message	string	Campaign message
button_text	string	Text of the button,- if not specified, will return null
button_link	string	Link on the button,- if not specified, will return null
image_link	string	Image link,- if not specified, will return null
address_book_ids	int	Array of address book identifiers used to create the campaign, - if keyed in manually, will return null
sender_name	string	Sender name
sender_id	int	Sender identifier
message_live_time	int	Message lifetime (in seconds)
send_date	string	Campaign sending time
status	string	Campaign status
created	string	Campaign creation time
stretch_time	int	Campaign sending duration
resend_sms	boolean	Marker indicating whether sending through SMS is available
resend_sms_status	int	SMS send status,- if not specified, will return null 0 int Awaiting send 1 int SMS campaign creation in progress 2 int SMS campaign created 3 int Insufficient funds in the account 4 int SMS sender not registered
statistics	object	Contains campaign statistics information
		sent	int	Number of sent messages
		delivered	int	Number of delivered messages
		read	int	Number of read messages
		redirected	int	Button clickthrough rate
		undelivered	int	Number of undelivered messages
		errors	int	Number of not sent messages due to technical errors

Get a list of sender names

To get a list of sender names, send a GET request to:

https://api.sendpulse.com/viber/senders

If request is successful, you will receive a response: 

[
   {
      "id": 1,
      "status": "verified",
      "name": "myName",
      "service_type": "Test service",
      "web_site": "https://www.sendpulse.com",
      "description": "We are testing the final variant of the message",
      "country": "UK",
      "traffic_type": "Public information",
      "admin_comment": "Your name has been approved, thank you for choosing our service. Sendpulse team" 
   }
]

Response parameters:

Parameter	Type	Description
id	int	Sender ID
status	string	Current sender status
name	string	Sender name
service_type	string	Type of service
web_site	string	Website
description	string	Description of the service
country	string	Recipients' country
traffic_type	string	Type of traffic
admin_comment	string	Comment of the admin,- if the comment exists, text will be returned, otherwise, the API will return null

Get a sender name

To get a sender name, send a GET request to:

https://api.sendpulse.com/viber/senders/{id}

Request parameter:

If request is successful, you will receive a response: 

{
    "id": 1,
    "status": "verified",
    "name": "infoservice",
    "service_type": "Test service",
    "web_site": "https://www.sendpulse.com",
    "description": "We are testing the final variant of the message",
    "country": "UK",
    "traffic_type": "Public information",
    "admin_comment": "Your name has been approved, thank you for choosing our service. Sendpulse team" 
}

Response parameters:

Parameter	Type	Description
id	int	Sender ID
status	string	Current sender status
name	string	Sender name
service_type	string	Type of service
web_site	string	Website
description	string	Description of the service
country	string	Recipients' country
traffic_type	string	Type of traffic
admin_comment	string	Comment of the admin,- if the comment exists, text will be returned, otherwise, the API will return null

Get a list of Viber campaign recipients

To get a list of Viber campaign recipients, send a GET request to:

https://api.sendpulse.com/viber/task/{id}/recipients

Request parameter:

If request is successful, you will receive a response: 

{
    "task_id": 44,
    "recipients": [
        {
           "phone": 380934760182,
           "address_book_id": 850852,
           "status": "send",
           "send_date": "2017-06-23 08:54:01",
           "price": 0.74,
           "currency": "RUR",
           "last_update": "2017-06-23 08:53:38" 
        }
    ]
}

Response parameters:

Parameter	Type	Description
task_id	int	Campaign ID
recipients	array	List of recipients:
		phone	int	Recipient's phone number
		address_book_id	int	Mailing list ID containing the phone number, in the case of manual entry the API will return null
		status	string	Status of the message sent to this number (send; delivered; delivered and opened; delivered and read; delivered; read and a clickthrough followed; not delivered; error)
		send_date	string	Sending time
		price	float	Price for the message
		currency	string	Actual user's currency and price for the message are displayed in this currency
		last_update	string	Last statistics update

Get a list of contacts in the blacklist

To get a list of contacts in the blacklist, send a GET request to:

https://api.sendpulse.com/v2/viber-service/phone-exception

Request parameter:

If request is successful, you will receive a response: 

{
    "data": {
        "list": [
           {
                "id": 164,
                "user_id": 7046460,
                "phone": 73832370050,
                "description": "",
                "add_date": "2021-11-05 13:34:03"
            },
            {
                "id": 165,
                "user_id": 7046460,
                "phone": 73912050915,
                "description": "",
                "add_date": "2021-11-05 13:34:03"
            }
        ],
        "total": 29
    }
}

Add phone number to the blacklist 

To add a phone number to the blacklist, send a POST request to:

https://api.sendpulse.com/v2/viber-service/phone-exception

Request parameter:

If request is successful, you will receive a response: 

{
    "result": true,
    "counters": {
        "added": 7,
        "exists": 0
    }
}

Remove a phone number from the blacklist 

To remove a phone number from the blacklist, send a DELETE request to:

https://api.sendpulse.com/v2/viber-service/phone-exception

Request parameter:

If request is successful, you will receive a response: 

{
    "result": true,
    "deleted": 7
}