# VIBER API DecisionTelecom Viber API позволяет отправлять и получать деловые сообщения Viber в любую страну мира и из нее через API. Каждое сообщение идентифицируется уникальным случайным идентификатором, поэтому пользователи всегда могут проверить статус сообщения, используя заданную конечную точку. Viber API использует HTTPS с ключом доступа, который используется в качестве авторизации API. Полезные данные запросов и ответов форматируются как JSON с использованием кодировки UTF-8. **API Авторизация** - Базовый ключ доступа Base64. Чтобы получить ключ API, пожалуйста, свяжитесь с вашим менеджером по работе с клиентами. ## **Авторизация** ## Basic Auth #### Пример: ``` $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); ``` ## **Отправить Вайбер сообщение** {% tabs %} {% tab title="POST" %} ``` https://web.it-decision.com/v1/api/send-viber ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Request POST:" %} ```json 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":225, "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 } Example for carousel messages: { "source_addr": "Custom Company", "destination_addr": 8882222200, "message_type":901, "source_type":1, "validity_period":6800, "text":"Message content", "carousel": { "items": [ { "title": "50% Off on All Shoes!50%", "imageUrl": "https://example.com/images/sale.jpg", "primaryButton": { "label": "Shop Now", "actionUrl": "https://example.com/shoes-sale" }, "secondaryButton": { "label": "View Details", "actionUrl": "https://example.com/shoes-sale" } }, { "title": "New Arrivals: Summer Collection", "imageUrl": "https://example.com/images/sum.jpg", "primaryButton": { "label": "Explore", "actionUrl": "https://example.com/summer" }, "secondaryButton": { "label": "Learn More", "actionUrl": "https://example.com/summer-info" } } ] } } ``` {% endtab %} {% endtabs %} ### **Параметры** **source\_addr:** от 3 до 20 символов - от кого сообщение **destination\_addr:** от 11 до 20 цифр – кому сообщение **message\_type (тип отправленного сообщения):** 6 - только текст (для основного устройства) 225 - только текст (для всех устройств) 8 - текст+изображение+кнопка (для основного устройства) 108 - текст+изображение+кнопка (для всех устройств) 9 - текст+кнопка (для основного устройства) 109 - текст+кнопка (для всех устройств) 222 - отправить файл (для всех устройств), поддерживаемые форматы: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx 301 - транзакционный шаблонный текст (для основного устройства) 304 - транзакционный шаблонный текст (для всех устройств) 901 - карусель (для всех устройств) **text:** до 1000 символов - текст Viber сообщения **image (Правильный URL-адрес с изображением для рекламного сообщения с заголовком кнопки и действием кнопки):** jpg or jpeg (тип mime — изображение/jpeg), максимальное разрешение 800x800 пикселей png (тип mime — image/png), максимальное разрешение 800x800 пикселей **button\_caption:** от 1 до 30 символов - надпись на кнопке **button\_action:** Правильный URL для перехода при нажатии кнопки **source\_type (Процедура отправки сообщения):** promotion message (сообщение может быть с текстом, изображением, кнопкой) - 1 transactional message (текстовое шаблонное сообщение) – 2 **callback\_url:** Правильный URL для обратного вызова статуса сообщения **validity\_period:** TTL (время жизни) позволяет отправителю ограничить время жизни сообщения. В случае, если сообщение не получило статус «доставлено» до истечения времени, сообщение не будет списано и не будет доставлено пользователю. В случае, если TTL не был указан (нет параметра «ttl»), Viber будет пытаться доставить сообщение в течение 1 дня. promotion message - мин. TTL 60 секунд макс. TTL 43200 секунд (12 часов) transactional message - мин. TTL 60 секунд макс. TTL 43200 секунд(12 часов) **file\_url:** Параметр только для типа сообщений 222, должен содержать корректный URL документа.\ Расширения файлов, разрешённые к отправке: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx\ Файл должен содержать расширение и его название не может превышать 25 символов.\ Размер файла не должен превышать 200 MB. **carousel:** Тип сообщения позволяет компаниям отправлять одно сообщение с текстом и несколькими \ настраиваемыми лементами, каждый из которых может демонстрировать различные продукты или услуги. \ Тип сообщения позволяет представлять от 2 до 5 отдельных элементов. Каждый элемент карусели включает изображение, краткое описание и до 2-х настраиваемых кнопок. Все элементы в карусели могут иметь разные наборы кнопок. **items:** от 2 до 5 карусельных элементов. * title (Mandatory) - Текст заголовка элемента. От 2 до 38 символов UTF-8. * imageUrl (Mandatory) - Ожидаемые форматы - PNG, JPEG, jpg. Рекомендуемый размер: 215x185 * primaryButton (Mandatory) - Содержит набор основных параметров кнопки. * secondaryButton (Optional) - Содержит набор параметров вторичной кнопки. * label (Mandatory) - Параметр кнопки. Текст, который будет отображаться на кнопке действия. До 10 символов UTF-8 внутри primaryButton. До 12 символов UTF-8 внутри secondaryButton. * actionUrl (Mandatory) - Параметр кнопки. URL-адрес, на который перенаправляются пользователи, или действие, выполняемое при нажатии кнопки действия\или касании изображения. ### Response: {% tabs %} {% tab title="JSON (POST)" %} ```json { "message_id":4291235 } ``` {% endtab %} {% endtabs %} ### **Значения**: **message\_id:** Идентификатор отправленного сообщения ## **Получить Вайбер сообщение** {% tabs %} {% tab title="POST" %} ``` https://web.it-decision.com/v1/api/receive-viber ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Request POST:" %} ```json { "message_id":4291235 } ``` {% endtab %} {% endtabs %} ### **Параметры** **message\_id:** ID сообщения, статус которого вы хотите получить (за последние 30 дней) {% tabs %} {% tab title="Response JSON:" %} ```json { "message_id":4291235, "status":1, } ``` {% endtab %} {% endtabs %} ### **Значения** **message\_id:** ID сообщения, статус которого вы хотите получить (за последние 30 дней) **status:** Текущий статус сообщения Viber ## **Получить Вайбер сообщения массово** Количество проверяемых сообщений — не более 200 в одном запросе. {% tabs %} {% tab title="POST" %} ``` https://web.it-decision.com/v1/api/receive-bulk-viber ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Request POST:" %} ```json [ {"message_id":11017894}, {"message_id":11017879}, {"message_id":11017865}, {"message_id": ... n} ] ``` {% endtab %} {% endtabs %} ### **Параметры** **message\_id:** ID сообщения, статус которых вы хотите получить (за последние 30 дней) {% tabs %} {% tab title="Response JSON:" %} ```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 } } ``` {% endtab %} {% endtabs %} ### **Значения** **message\_id:** ID сообщения, статус которого вы хотите получить (за последние 30 дней) **status:** Текущий статус сообщения Viber ## **Получение Callback** Обратный вызов будет возвращен на URL, указанный при отправке сообщения в параметре callback\_url {% tabs %} {% tab title="Response JSON:" %} ```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 } ``` {% endtab %} {% endtabs %} ### Значения: **message\_id:** ID сообщения **status:** Текущий статус сообщения **reject\_code:** код, возвращаемый Viber при отклонении сообщения: 1 - Внутренняя ошибка сервера. 2 - Идентификатор не использовался более года/Идентификатор был недавно создан и еще не загружен на сервер. 3 - Ошибка в структуре запроса. Возможно, пропущена запятая, скобки, текст длиной более 1000 символов и т. д. 5 - Неверный тип сообщения. Либо неподдерживаемый тип, либо неверное значение. 6 - Отсутствуют обязательные параметры. 7 - Указывает на тайм-аут сервера на стороне Viber. 8 - Идентификатор был заблокирован пользователем/Пользователь полностью заблокировал деловые сообщения на своем устройстве. 9 - Номер назначения не зарегистрирован как пользователь Viber. 10 - Устройство не Android или iOS с версией Viber, поддерживающей деловые сообщения. 11 - Запрос был отправлен с IP-адреса, не входящего в белый список для этого идентификатора/В запросе использован неверный идентификатор, не принадлежащий партнеру. 13 - Ошибка в процессе выставления счета 18 - Отсутствует значение/Неверное значение в запросе параметра «label». 28 - Файл, который пытаются отправить, не имеет поддерживаемого формата для этой функции. 29 - Имя файла превышает максимально допустимые 25 символов. 30 - Если URL-адрес миниатюры состоит из более чем 1000 символов. 40 - Один из параметров сообщений списка не прошел проверку. 41 - Один из параметров сообщений карусели не прошел проверку. **matching\_template\_id:** ID, выданный Viber при регистрации шаблона. Если параметр присутствует и значение параметра пустое, это означает, что сообщение не соответствует ни одному из зарегистрированных шаблонов и было перетарифицировано с транзакционного на рекламное сообщение на стороне Viber. ## **Статусы сообщений Viber:** | Name | Status code | | ----------- | ----------- | | sent | 0 | | delivered | 1 | | error | 2 | | rejected | 3 | | undelivered | 4 | | pending | 5 | | seen | 6 | | unknown | 20 | ## **Ошибки:** | Name | Too Many Requests | | ------- | ------------------- | | message | Rate limit exceeded | | code | 0 | | status | 429 | | Name | Empty parameter or parameter validation error | | ------- | --------------------------------------------- | | message | Invalid Parameter: \ | | code | 1 | | status | 400 | #### param: 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 \ 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 | ## Примеры: {% tabs %} {% tab title="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}' ``` {% endtab %} {% tab title="С#" %} ``` 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); ``` {% endtab %} {% tab title="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)) } ``` {% endtab %} {% tab title="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(); ``` {% endtab %} {% tab title="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)); ``` {% endtab %} {% tab title="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); ``` {% endtab %} {% tab title="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(); ``` {% endtab %} {% tab title="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; ``` {% endtab %} {% tab title="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")) ``` {% endtab %} {% tab title="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 ``` {% endtab %} {% endtabs %}