VIBER API

DecisionTelecom Viber API allows you to send and receive Viber business messages to and from any country in the world via API. Each message is identified by a unique random ID, so users can always check the status of a message using given endpoint.

The Viber API uses HTTPS with access key that is used as the API authorization. Request and response payloads are formatted as JSON using UTF-8 encoding.

API Authorization - Base64 access key.

Please contact your account manager to get an API key.

Auth

Basic Auth

Example:

$userHashKey = 'User Hash Key provided by your account manager';
$ch = curl_init('https://web.it-decision.com/v1/api/send-viber');
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$userHashKey");
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestParams)); // 
$requestParams - raquest array with correct data 
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); 
$result = curl_exec($ch); 
curl_close($ch);

Send Viber message

POST

https://web.it-decision.com/v1/api/send-viber

Request POST:

Example for text-image-button messages:
{
	"source_addr": "Custom Company", 						
	"destination_addr": 8882222200,							
	"message_type":108, 									
	"text":"Message content", 										
	"image":"https://yourdomain.com/images/image.jpg", 		
	"button_caption":"Join Us", 							
	"button_action":"https://yourdomain.com/join-us",   	
	"source_type":1, 										
	"callback_url":"https://yourdomain.com/viber-callback",
	"validity_period":3600
}

Example for promotional text messages:
{
	"source_addr": "Custom Company", 						
	"destination_addr": 8882222200,	
	"message_type":106, 								
	"text":"Message content",
	"source_type":1, 	
	"callback_url":"https://yourdomain.com/viber-callback",
	"validity_period":3600
}

Example for send file:
{
	"source_addr": "Custom Company", 						
	"destination_addr": 8882222200,						
	"message_type":222, 
	"file_url":" https://yourdomain.com/files/custom.pdf ",	
	"source_type":1, 								
	"callback_url":"https://yourdomain.com/viber-callback",
	"validity_period":180
}

Example for transactional template messages:
{
	"source_addr": "Custom Company", 						
	"destination_addr": 8882222200,	
	"message_type":304, 
	"text":"Message content",							
	"source_type":2,
	"callback_url":"https://yourdomain.com/viber-callback",
	"validity_period":180
}

Parameters

source_addr:

from 3 to 20 characters - from whom the message

destination_addr:

from 11 to 20 digits - to whom the message

message_type (Type of message sent):

6 - only text (for primary device)

106 - only text (for all devices)

8 - text+image+button (for primary device)

108 - text+image+button (for all devices)

9 - text+ button (for primary device)

109 - text+button (for all devices)

222 - send file (for all devices) , supported formats: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx

301 - template transactional text (for primary device)

304 - template transactional text (for all devices)

text:

up to 1000 characters - text of Viber message

image (Correct URL with image for promotional message with button caption and button action):

jpg or jpeg (mime type is image/jpeg), maximum resolution 800x800 pixels

png (mime type is image/png), maximum resolution 800x800 pixels

button_caption:

from 1 to 30 characters - button caption

button_action:

Correct URL for transition when you press the button

source_type (Message sending procedure):

promotion message (the message can be with text, picture, button) - 1

transactional message (template text message) – 2

callback_url:

Correct URL for message status callback

validity_period:

TTL (Time to live) allows the sender to limit the lifetime of a message. In case the message did not get the status "delivered" before the time ended, the message will not be charged and will not be delivered to the user. In case no TTL was provided (no "ttl" parameter) Viber will try to deliver the message for up to 1 day.

promotion message - min TTL 60 seconds max TTL 43200 seconds (12 hours)

transactional message - min TTL 60 seconds max TTL 43200 seconds (12 hours)

file_url:

Only for 222 message type сorrect URL for document. Possible file extensions to send: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx The file name must contain an extension and must not exceed 25 characters. File size must be up to 200 MB.

Response:

JSON (POST)

{
    "message_id":4291235	
}

Values:

message_id:

Sent message ID

Receive Viber message

POST

 https://web.it-decision.com/v1/api/receive-viber

Request POST:

{
    "message_id":4291235
}

Parameters

message_id:

The ID of the message whose status you want to get (for the last 30 days)

Response JSON:

{
    "message_id":4291235, 			
    "status":1, 					
}

Values

message_id:

The ID of the message whose status you want to get (for the last 30 days)

status:

Current Viber message status

Receive bulk Viber messages

The number of verified messages is no more than 200 in one request.

POST

 https://web.it-decision.com/v1/api/receive-bulk-viber

Request POST:

[
     {"message_id":11017894},
     {"message_id":11017879},
     {"message_id":11017865},
     {"message_id": ... n}
]

Parameters

message_id:

The ID of the message whose status you want to get (for the last 30 days)

Response JSON:

{
    "11017894": {
        "message_id": 11017894,
        "status": 1
    },
    "11017879": {
        "message_id": 11017879,
        "status": 1
    },
    "11017865": {
        "name": "Empty parameter or parameter validation error",
        "message": "Invalid Parameter: message_id 11017865 is not accepted for you",
        "code": 1,
        "status": 400
    }
}

Values

message_id:

The ID of the message whose status you want to get (for the last 30 days)

status:

Current Viber message status

Callback

The callback will be returned to the URL specified when sending the message in the parameter callback_url

Response JSON:

{
    "message_id":4291235,                                 
    "status":1                                                                       
}

If the status is 3 (Rejected) then the additional parameter reject_code will be returned:
{
    "message_id":4291235,                                 
    "status":1,         
    "reject_code":9                                              
}

If the message type being sent is 301 or 304 (template transactional text) then the additional parameter matching_template_id will be returned
{
    "message_id":4291235,                                 
    "status":1,         
    "matching_template_id":11079289                                                            
}

Values

message_id:

The ID of the message

status:

Current Viber message status

reject_code:

code returned by Viber when rejecting a message:

1 - Internal server error.

2 - The ID wasn’t in use for over a year/The ID was recently created and

wasn’t uploaded to the server yet.

3 - An error in the request’s structure. Could be a missing comma, brackets,

text over 1000 characters, etc.

5 - Incorrect message type. Either a non-supported type or an incorrect value.

6 - Missing mandatory parameters.

7 - Indicates a server timeout on Viber’s end.

8 - The ID was blocked by the user/The user blocked business messages

completely on their device.

9 - The destination number is not registered as a Viber user.

10 - Not an Android or iOS device with a Viber version that supports Business

Messages.

11 - The request was sent from a non-whitelisted IP for this ID/An incorrect ID

that doesn’t belong to the partner was used in the request.

13 - An error in the billing process

18 - Missing value/Incorrect value in the request for “label” parameter.

28 - The file that is being attempted to be sent is not in a supported format for

this feature.

29 - The name of the file is more than the maximum 25 characters.

30 - In case the thumbnail URL is compiled of more than 1000 characters.

matching_template_id:

ID issued by Viber when registering a template. If the parameter is present and the parameter value is empty, it means the message does not match any of the registered templates and has been re-rated from transactional to promotional message on the Viber side.

Viber messages statuses

Name	Status code
sent	0
delivered	1
error	2
rejected	3
undelivered	4
pending	5
seen	6
unknown	20

Errors

Name	Too Many Requests
message	Rate limit exceeded
code	0
status	429

Name	Empty parameter or parameter validation error
message	Invalid Parameter: <param>
code	1
status	400

param:

source_addr more than 20 chars

destination_addrr more than 20 chars

wrong viber user account

source_type is wrong

source_type or message_type is wrong

source_type is wrong, because the account is another type

message_type is wrong

empty text

text more than 1000 chars

transaction message error - not empty image, button_caption or button_action

message_type is wrong - not empty image, button_caption or button_action

message_type is wrong - empty image, button_caption or button_action

message_type is wrong - empty button_caption or button_action

image is not url

image url wrong scheme

image not valid type

image is not valid

image size is more than 800x800

button_action is empty

button_caption is empty

button_caption or button_action is empty

image or button_action is empty

image or button_caption is empty

callback_url is not url

callback_url url wrong scheme

button_action is not url

button_action url wrong scheme

button_action more than 30 chars

message_id <message_id> is not accepted for you

file_url is not url

file_url wrong scheme

file_url contains an invalid file type or extension, possible file extensions to send: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx

button_caption is not applicable with file_url

button_action is not applicable with file_url

image is not applicable with file_url

wrong message type for file_url

file_url is not applicable in this context

Name	Internal server error
message	The server encountered an unexpected condition which prevented it from fulfilling the request
code	2
status	500

Name	Topup balance is required
message	Sender balance is empty
code	3
status	402

Name	Duplicate error
message	Duplicate Viber message detected
code	4
status	400

Name	Message Template error
message	The message does not match any template
code	5
status	400

Name	Authorization error
message	Unauthorized
code	6
status	401

Viber example

cUrl

curl --location --request POST 'https://web.it-decision.com/v1/api/send-viber' \
--header 'Authorization: Basic api key' \
--header 'Content-Type: application/json' \
--data-raw '{"source_addr": "Custom Company", "destination_addr": 8882222200,"message_type":106,"text":"Message content","image":"https://yourdomain.com/images/image.jpg","button_caption":"Join Us","button_action":"https://yourdomain.com/join-us","source_type":1,"callback_url":"https://yourdomain.com/viber-callback","validity_period":3600}'

С#

var client = new RestClient("https://web.it-decision.com/v1/api/send-viber");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Basic api key");
request.AddHeader("Content-Type", "application/json");
var body = @"{""source_addr"": ""Custom Company"", ""destination_addr"": 8882222200,""message_type"":106,""text"":""Message content"",""image"":""https://yourdomain.com/images/image.jpg"",""button_caption"":""Join Us"",""button_action"":""https://yourdomain.com/join-us"",""source_type"":1,""callback_url"":""https://yourdomain.com/viber-callback"",""validity_period"":3600}";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Golang

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://web.it-decision.com/v1/api/send-viber"
  method := "POST"

  payload := strings.NewReader(`{"source_addr": "Custom Company", "destination_addr": 8882222200,"message_type":106,"text":"Message content","image":"https://yourdomain.com/images/image.jpg","button_caption":"Join Us","button_action":"https://yourdomain.com/join-us","source_type":1,"callback_url":"https://yourdomain.com/viber-callback","validity_period":3600}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Basic api key")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"source_addr\": \"Custom Company\", \"destination_addr\": 8882222200,\"message_type\":106,\"text\":\"Message content\",\"image\":\"https://yourdomain.com/images/image.jpg\",\"button_caption\":\"Join Us\",\"button_action\":\"https://yourdomain.com/join-us\",\"source_type\":1,\"callback_url\":\"https://yourdomain.com/viber-callback\",\"validity_period\":3600}");
Request request = new Request.Builder()
  .url("https://web.it-decision.com/v1/api/send-viber")
  .method("POST", body)
  .addHeader("Authorization", "Basic api key")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

JavaScript

var myHeaders = new Headers();
myHeaders.append("Authorization", "Basic api key");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "source_addr": "Custom Company",
  "destination_addr": 8882222200,
  "message_type": 106,
  "text": "Message content",
  "image": "https://yourdomain.com/images/image.jpg",
  "button_caption": "Join Us",
  "button_action": "https://yourdomain.com/join-us",
  "source_type": 1,
  "callback_url": "https://yourdomain.com/viber-callback",
  "validity_period": 3600
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://web.it-decision.com/v1/api/send-viber", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

C – lib cUrl

CURL *curl;
CURLcode res;
curl = curl_easy_init();
if(curl) {
  curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
  curl_easy_setopt(curl, CURLOPT_URL, "https://web.it-decision.com/v1/api/send-viber");
  curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
  curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
  struct curl_slist *headers = NULL;
  headers = curl_slist_append(headers, "Authorization: Basic api key");
  headers = curl_slist_append(headers, "Content-Type: application/json");
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  const char *data = "{\"source_addr\": \"Custom Company\", \"destination_addr\": 8882222200,\"message_type\":106,\"text\":\"Message content\",\"image\":\"https://yourdomain.com/images/image.jpg\",\"button_caption\":\"Join Us\",\"button_action\":\"https://yourdomain.com/join-us\",\"source_type\":1,\"callback_url\":\"https://yourdomain.com/viber-callback\",\"validity_period\":3600}";
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
  res = curl_easy_perform(curl);
}
curl_easy_cleanup(curl);

NodeJs

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'web.it-decision.com',
  'path': '/v1/api/send-viber',
  'headers': {
    'Authorization': 'Basic api key',
    'Content-Type': 'application/json'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "source_addr": "Custom Company",
  "destination_addr": 8882222200,
  "message_type": 106,
  "text": "Message content",
  "image": "https://yourdomain.com/images/image.jpg",
  "button_caption": "Join Us",
  "button_action": "https://yourdomain.com/join-us",
  "source_type": 1,
  "callback_url": "https://yourdomain.com/viber-callback",
  "validity_period": 3600
});

req.write(postData);

req.end();

PHP

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://web.it-decision.com/v1/api/send-viber',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{"source_addr": "Custom Company", "destination_addr": 8882222200,"message_type":106,"text":"Message content","image":"https://yourdomain.com/images/image.jpg","button_caption":"Join Us","button_action":"https://yourdomain.com/join-us","source_type":1,"callback_url":"https://yourdomain.com/viber-callback","validity_period":3600}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic api key',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import http.client
import json

conn = http.client.HTTPSConnection("web.it-decision.com")
payload = json.dumps({
  "source_addr": "Custom Company",
  "destination_addr": 8882222200,
  "message_type": 106,
  "text": "Message content",
  "image": "https://yourdomain.com/images/image.jpg",
  "button_caption": "Join Us",
  "button_action": "https://yourdomain.com/join-us",
  "source_type": 1,
  "callback_url": "https://yourdomain.com/viber-callback",
  "validity_period": 3600
})
headers = {
  'Authorization': 'Basic api key',
  'Content-Type': 'application/json'
}
conn.request("POST", "/v1/api/send-viber", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Ruby

require "uri"
require "json"
require "net/http"

url = URI("https://web.it-decision.com/v1/api/send-viber")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Basic api key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "source_addr": "Custom Company",
  "destination_addr": 8882222200,
  "message_type": 106,
  "text": "Message content",
  "image": "https://yourdomain.com/images/image.jpg",
  "button_caption": "Join Us",
  "button_action": "https://yourdomain.com/join-us",
  "source_type": 1,
  "callback_url": "https://yourdomain.com/viber-callback",
  "validity_period": 3600
})

response = https.request(request)
puts response.read_body