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
}