Viber API
Create a Viber Campaign
To create a Viber campaign, send a POST request to:
https://api.sendpulse.com/viber |
Request parameters:
Parameter | Type | Description | |||||
task_name | string | Campaign name | required | ||||
message_type* | int | Message type: 2 - promo, 3 - system |
required | ||||
sender_id | int | Active sender name ID, from which you send campaigns; you can get sender_id in "Get a List of Sender Names" method, to use it you must have registered the sender name in the service settings |
required | ||||
message_live_time | int | Message lifetime (seconds), minimum 60s, maximum 86400 seconds (24 hours) | required | ||||
send_date | string | Sending time. Use now if you need to send the message immediately, or specify the time in the format YYYY-MM-DD HH:MM:SS if you need to schedule it for the future |
required | ||||
address_book* | int | Mailing list ID | required | ||||
recipients* | array | List of phone numbers in [180931111111,180931111112, 180931111113] format |
required | ||||
message* | string | Message text (maximum length is 1000 characters) | required | ||||
stretch_time | int | Gradual message sending. You can set values from 0 to 5 hours, and your campaign will be sent to all recipients in smaller parts within the specified time frame. | optional | ||||
additional | object | Additional parameters: | optional | ||||
button* | Button parameters: | ||||||
text | string | Button text | optional | ||||
link | string | Button link | optional | ||||
image* | Image parameters: | ||||||
link | string | Link to your uploaded image | optional | ||||
resend_sms | Function of re-sending messages via SMS service: | ||||||
status | boolean | true if enabled, false if disabled |
optional | ||||
sms_text | string | SMS message text | optional | ||||
sms_sender_name | string | SMS Sender ID | optional |
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"
}
}
Edit a Viber Campaign
To edit a Viber campaign, send a POST request to:
https://api.sendpulse.com/viber/update |
Request parameters:
Parameter | Type | Description | |
main_task_id | int | Campaign ID | required |
task_name | string | Campaign name | optional |
message | string | Message text | optional |
message_type | int | Message type: 2 — marketing, 3 — transactional |
required |
button_text | string | Text of the button; if not specified, null response will follow |
optional |
button_link | string | Transfer link; if not specified, null response will follow |
optional |
image_link | string | Image location; if not specified, null response will follow |
optional |
address_book | int | Mailing list; if not specified, null response will follow |
optional |
sender_id | int | Sender ID (at the time of sending); you can get it in "Get a List of Sender Names" method; make sure user has registered sender ids in service settings |
required |
message_live_time | int | Message lifetime (in seconds) | optional |
send_date | string | Date of sending | optional |
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",
"send_date": "2019-03-26 15:16:00",
"sender_id": "4495",
"task_id": 9380939,
"task_name": "Viber campaign for the personal list on 2019-03-26 15:15"
}
}
Cancel a Viber campaign
To cancel a scheduled Viber campaign, send a PUT request to:
https://api.sendpulse.com/v2/viber-service/tasks/cancel |
Request parameters:
Parameter | Type | Description | |
task_id | int | Campaign ID | required |
If request is successful, you will receive a response:
{
"data": {
"result": true
}
}
Get a List of Campaigns
To get a list of campaigns, send a GET request to:
https://api.sendpulse.com/viber/task |
Request parameters:
Parameter | Type | Description | |
limit | int | Number of records | optional |
offset | int | Offset (first record to be displayed) | optional |
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:
Parameter | Type | Description | |
id | int | Campaign ID | required |
If request is successful, you will receive a response:
{
"id": 38,
"name": "Viber_Campaign_38",
"message": "Viber message text",
"button_text": "Button",
"button_link": "https://sendpulse.com",
"image_link": null,
"address_book": null,
"sender_name": "infoservice",
"send_date": "2017-06-22 09:51:35",
"status": "send",
"statistic": {
"send": 1,
"delivered": 1,
"read": 0,
"redirected": 0,
"undelivered": 0,
"errors": 0
},
"created": "2017-06-22 09:51:22"
}
Response parameters:
Parameter | Type | Description | ||
id | int | Campaign ID | ||
name | string | Campaign name | ||
message | string | Message text | ||
button_text | string | Text of 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 | Task status | ||
statistics | object | Campaign statistics: | ||
send | 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 errors | ||
created | string | Date that the campaign was created |
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:
Parameter | Type | Description | |
id | int | Sender ID | required |
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:
Parameter | Type | Description | |
id | int | Campaign ID | required |
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:
Parameter | Type | Description | |
limit | int | Number of records | optional |
offset | int | Offset (first record to be displayed) | optional |
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:
Parameter | Type | Description | |
phones | array | List of the phone numbers, for example ["380977217975", "380977217977", "380977217978"] | required |
description | string | Description of the reason for adding a number to the blacklist | optional |
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:
Parameter | Type | Description | |
phones | array | List of the phone numbers, for example ["380977217975", "380977217977", "380977217978"] | required |
If request is successful, you will receive a response:
{
"result": true,
"deleted": 7
}
veya