# VIBER API DecisionTelecom Viber API дозволяє надсилати та отримувати ділові повідомлення Viber у будь-яку країну світу та з неї через API. Кожне повідомлення ідентифікується унікальним випадковим ідентифікатором, тому користувачі можуть перевірити статус повідомлення, використовуючи задану кінцеву точку. Viber API використовує HTTPS з ключем доступу, який використовується як авторизація API. Корисні дані запитів та відповідей форматуються як JSON за допомогою кодування UTF-8. **API Авторизація** - Базовий ключ доступу Base64. Щоб отримати ключ API, будь ласка, зв'яжіться з вашим менеджером по роботі з клієнтами. ## Авторизація ## 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); ``` ## **Надіслати Вайбер повідомлення** {% 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 символів - from whom the message **destination\_addr:** от 11 до 20 цифр - to whom the message **message\_type (Type of message sent):** 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 Мб. **carousel:** Тип повідомлення дозволяє компаніям надсилати одне повідомлення, що містить текст і кілька розділів (елементів), що налаштовуються, кожен з яких демонструє різні продукти або послуги. \ Тип повідомлення дозволяє представляти від 2 до 5 окремих елементів. Кожен елемент каруселі містить зображення, короткий опис і пропонує до 2 кнопок, що налаштовуються. Усі елементи в каруселі можуть мати різні набори кнопок. **items:** from 2 to 5 carousel items. * 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:** Поточний статус повідомлення Viber **reject\_code:** код, що повертається Viber при відхиленні повідомлення: 1 – Внутрішня помилка сервера. 2 - Ідентифікатор не використовувався більше року/Ідентифікатор нещодавно був створений і ще не завантажений на сервер. 3 – Помилка у структурі запиту. Можливо, пропущена кома, дужки, текст довжиною понад 1000 символів тощо. 5 - Неправильний тип повідомлення. Або непідтримуваний тип, чи неправильне значення. 6 - Відсутні обов'язкові параметри. 7 - Вказує на тайм-аут сервера на боці Viber. 8 - Ідентифікатор був заблокований користувачем/Користувач повністю заблокував ділові повідомлення на своєму пристрої. 9 - Номер призначення не зареєстрований як Viber. 10 - Пристрій не Android або iOS з версією Viber, яка підтримує ділові повідомлення. 401 - Запит було надіслано з IP-адреси, що не входить до білого списку для цього ідентифікатора/У запиті використано невірний ідентифікатор, що не належить партнеру. 13 - Помилка у процесі виставлення рахунку 18 - Відсутнє значення/Неправильне значення у запиті параметра "label". 28 - Файл, який намагаються надіслати, не має підтримуваного формату для цієї функції. 29 - Ім'я файлу перевищує максимально допустимі 25 символів. 30 - Якщо URL-адреса мініатюри складається з більш ніж 1000 символів. 40 – Один із параметрів повідомлень списку не пройшов перевірку. 41 – Один із параметрів повідомлень каруселі не пройшов перевірку. **matching\_template\_id:** ID, виданий Viber під час реєстрації шаблону. Якщо параметр є і значення параметра порожнє, це означає, що повідомлення не відповідає жодному із зареєстрованих шаблонів і було перетарифіковано з транзакційного на рекламне повідомлення на стороні Viber. ## **Статуси повідомлень Вайбер** | 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 %}