API-запит з'єднання 2-х номерів (простий метод Callback)
Для оперативності обробки заявок від клієнтів, ви можете налаштувати автоматичний передзвін клієнту, який надсилає заповнену форму реєстрації або замовлення на вашому сайті.
Аналогічно можна ініціювати дзвінок із картки клієнта у вашій CRM.
Важлива умова для роботи методу
Значенням параметра extension може бути лише номер телефону з проєкта (номер має бути підключений до проєкту як "вхідний", у розділі "Віртуальна АТС" -> "Підключення номерів")
Опис параметрів запиту
Адреса API-запиту: https://api.ringostat.net/callback/outward_call ;
Метод — POST;
Auth-key — це електронний ключ для доступу до вашого проекту в Ringostat.
Extension — Номер телефона, з якого дзвонити
(номер має бути підключений до проєкту як "вхідний", у розділі у розділі "Віртуальна АТС" -> "Підключення номерів");Destination — Номер телефона або логін SIP-акаунта, на який дзвонити
Content-Type: 'application/x-www-form-urlencoded'
Приклад для Node.js:
const https = require('https);
const config = {
host: 'api.ringostat.net',
path: '/callback/outward_call',
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Auth-key': 'unique_auth_key_string'
}
};
const callback = response => {
let result = Buffer.alloc(0);
response.on('data', chunk => {
result = Buffer.concat([ result, chunk ]);
});
response.on('end', () => {
//handler response
});
};
const request = https.request(config, callback);
const body = `extension=380441112233&destination=380671112233`;
request.write(body);
request.end();API-запит з'єднання 2-х номерів (розширений метод Callback)
Розширений метод дозволяє здійснити дзвінок між будь-якими двома сторонами, навіть з тими, яких немає в Ringostat (наприклад, потрібним вам номером або sip акаунтом менеджера та номером клієнта). Джерела такого дзвінка відобразяться у статистиці так само, як при стандартному дзвінку з віджету Callback.
Цей метод підійде для виклику дзвінка з CRM системи, обробки заявок, які клієнт залишає на вашому сайті, або classified рішень (дошок оголошень).
Опис параметрів запиту
Адреса API-запиту: https://api.ringostat.net/a/v2 ;
Метод — POST;
Auth-key — це електронний ключ для доступу до вашого проєкту в Ringostat.
clientIP — ви можете встановити справжню або рандомну IP-адресу.
caller — номер або SIP-акаунт, на який потрібно передзвонити;
callee — номер або SIP-аккаунт, який має відповісти на дзвінок;
projectId — ID проекта Ringostat.
Headers запиту
Ім'я параметра | Опис |
| application/json |
| "unique_auth_key_string" |
Body запиту
Имя параметра | Описание |
| Версія протоколу. Значення 2.0 |
| Будь-яке число, використовується для встановлення відповідності між запитом та відповіддю |
| Метод на сервері Ringostat. |
Параметри запиту
Ім'я параметра | Опис |
| Дозволяє вказати тип напряму, на який ініціюємо дзвінок default – номер телефону scheme – схема переадресації |
| Номер телефону або SIP-аккаунт того, хто телефонує |
| Номер телефону або SIP-аккаунт, адресата дзвінка |
| Параметр визначає тип дзвінка у Журналі дзвінків: in - відобразиться як вхідний з мітками джерела переходу out - відобразитися в журналі дзвінків як вихідний (Тип даних string) |
| Параметр визначає тип першого напряму: 0 - дзвінок спочатку надійде менеджеру, після підняття слухавки ініціюється дзвінок клієнту 1 - дзвінок спочатку надійде клієнту, після підняття слухавки ініціюється дзвінок менеджеру |
| IP-адреса відвідувача |
| джерело переходу |
| канал переходу |
| Кампанія |
| ключове слово |
| Вміст |
| Client ID Google Analytics |
| Додаток клієнта |
Для передачі даних про сесію відвідувача – їх потрібно збирати самостійно та додати до запиту.
Для прикладу, utm-мітки переходу, можна витягти з файлу cookie rngst2 (якщо встановлено скрипт підміни), а ClientID Google Analytics з файлу cookie _ga.
Приклад для Node.js:
const https = require('https');
const config = {
host: 'api.ringostat.net',
path: '/a/v2',
method: 'POST',
headers: {
'Auth-key': 'unique_auth_key_string'
}
};
const callback = response => {
let result = Buffer.alloc(0);
response.on('data', chunk => {
result = Buffer.concat([ result, chunk ]);
});
response.on('end', () => {
//handler response
});
};
const request = https.request(config, callback);
const body = `{
"jsonrpc": "2.0",
"id": 777,
"method": "Api\\V2\\Callback.external",
"params": {
"callee_type": "default",
"caller_type": "default",
"caller": "380671112233",
"callee": "380632223344",
"manager_dst": 1,
"direction": "out",
"projectId": "11111",
"clientIp": "10.10.10.10",
"utmSource": "ringostat",
"utmMedium": "referral",
"utmCampaign": "extended_callback",
"utmTerm": "test_api_request",
"utmContent": "content",
"clientId": "111111111.2222222222",
"clientUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
}
}`;
request.write(body);
request.end();
Можливі помилки запиту
400 Bad Request – відсутня передача одного з параметрів / caller або callee не валідні / значення об'єкта JavaScript не перетворено на рядок JSON
401 Unauthorized – відсутній або некоректний заголовок HTTP Auth-Key
403 Forbidden – відмовлено у доступі, не правильний HTTP-заголовок Auth-Key
Розглянемо детально роботу розширеного методу за різних варіантів налаштування.
Приклад із SIP-акаунтом (caller).
Ситуація: Значення Caller – SIP-акаунт, Callee – номер телефону
Клієнту буде здійснено дзвінок з номера телефона, який встановлено в налаштуваннях вихідного зв'язку за замовчуванням.
Приклад із номером клієнта (caller).
Ситуація: Значення Caller – номер клієнта, Callee – SIP-аккаунт
Клієнту буде здійснено дзвінок з номера телефона, який встановлено у правилі, у налаштуваннях вихідного зв'язку.
Для коректної роботи налаштувань вихідного зв'язку та відображення правильних номерів у відповідності до правил – рекомендуємо вам використовувати цей приклад налаштування. |
Приклад:
Клієнт замовляв дзвінок на свій номер формату +380ХХХХХХХХХ через форму на сайті (використано розширений метод API-Callback).
Клієнт побачить вхідний дзвінок з номером із правила для напряму +380
Другий клієнт замовив дзвінок на свій номер формату +7495ХХХХХХХ.
Клієнт побачить вхідний дзвінок з номером із правила для напряму +7
Приклад зі схемою переадресації (callee).
Ситуація: Значення Caller – номер клієнта, Callee – схема переадресації проекту.
Приклад:
Клієнт замовляв дзвінок на свій номер формату +380ХХХХХХХХХ через форму на сайті (використано розширений метод API-Callback).
Дзвінок необхідно переадресувати на схему переадресації проекту.
Приклад запиту:
"callee_type": "scheme",
"caller_type": "default",
"callee": "XXXXX",*
"caller": "380ХХХХХХХХХ"**
*callee — id схеми переадресації, на який буде йти переадресація дзвінка.
**caller — номер клієнта
Щоб дізнатися, який ID присвоєний потрібній схемі переадресації, в меню навігації перейдіть до розділу Віртуальна АТС -> Переадресація та у потрібної схеми натисніть кнопку Редагувати схему:
Журнал дзвінків (direction in).
Вказано параметр direction: Значення in – у журналі дзвінків дзвінок записується як вхідний, таким чином:
Хто дзвонив — Значення параметра caller (номер телефону або логін SIP-акаунта, на який здійснено дзвінок);
Куди дзвонили - значення параметра callee (номер з якого здійснено дзвінок, SIP-аккаунт з якого здійснено дзвінок);
З ким з'єднаний — значення caller (номер телефону або логін SIP-акаунта, на який здійснено дзвінок).
Тест запиту
Ви можете побачити, як виглядає запит на різних мовах програмування на сторінці https://ringostat.readme.io/reference/post_callback-outward-call
1. API-запит з'єднання 2-х номерів (простий метод Callback)
2. API-запит з'єднання 2-х номерів (розширений метод Callback)
Також там можна вказати потрібні параметри (1) та Auth-key (2), і надіслати тестовий запит (3) на дзвінок:
