API-запрос соединения 2х номеров(простой метод Callback)

Для оперативности обработки заявок от клиентов, вы можете настроить автоматический перезвон клиенту, который отправляет заполненную форму регистрации или заказа на вашем сайте.
Аналогично можно инициировать звонок из карточки клиента в вашей CRM.

Обратите внимание, этот метод нельзя использовать на Front End. В целях безопасности и сохранения личных данных использование такого запроса на Front End не доступно.

Важное условие для работы метода

Значением параметра 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 запроса

Имя параметра	Описание
`content-type`	application/json
`Auth-key`	"unique_auth_key_string"

Body запроса

Имя параметра	Описание
`jsonrpc`	Версия протокола. Значение `2.0`
`id`	Любое число, используется для установки соответствия между запросом и ответом
`method`	Метод на сервере Ringostat. Значение `Api\\V2\\Callback.external`

Параметры запроса

Имя параметра	Описание
`callee_type`	Позволяет указать тип направления на которое инициируем звонок `default` – номер телефона `scheme` – схема переадресации
`caller`	Номер телефона или SIP-аккаунт звонящего
`callee`	Номер телефона или SIP-аккаунт, адресата звонка
`direction`	Параметр определяет тип звонка в Журнале звонков: `in` - отобразится как входящий с метками источников `out` - отобразиться в журнале звонков как исходящий (тип данных string)
`manager_dst`	Параметр определяет тип первого направления: 0 - звонок сначала поступит менеджеру, после поднятия трубки инициируется звонок клиенту 1 - звонок сначала поступит клиенту, после поднятия трубки инициируется звонок менеджеру
`clientIp`	IP-адрес посетителя
`utmSource`	источник перехода
`utmMedium`	канал перехода
`utmCampaign`	Кампания
`utmTerm`	ключевое слово
`utmContent`	Содержимое
`clientId`	Client ID Google Analytics
`clientUserAgent`	Клиентское приложение

Для передачи данных о сессии посетителя – их нужно собирать самостоятельно и добавить в запрос.
Для примера, utm-метки перехода, можно извлечь из куки-файла rngst2(если установлен скрипт подмены), а ClientID Google Analytics из куки-файла _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-аккаунта, на который совершён звонок).

Журнал звонков(direction out).

Указан параметр direction: Значение out – в журнале звонков звонок записывается как исходящий, следующим образом:

Кто звонил — значение параметра callee (номер с которого совершен звонок, SIP-аккаунт с которого совершен звонок);
Куда звонили — значение параметра caller (номер телефона или логин 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) на дзвінок:

Другие статьи по теме

Как настроить интеграцию с вашей системой через Ringostat API

API Ringostat. Экспорт журнала звонков

API Ringostat. Проверка доступности SIP-аккаунта

Webhook номер

API Ringostat. Экспорт данных о сотрудниках проекта