Все коллекции
API и Webhooks
API
API Ringostat. API-запрос соединения 2х номеров
API Ringostat. API-запрос соединения 2х номеров
Katerina Tverdochleb avatar
Автор: Katerina Tverdochleb
Обновлено больше недели назад

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 запроса

Имя параметра

Описание

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) на дзвінок:

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

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

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

Другие статьи по теме
Как настроить интеграцию с вашей системой через Ringostat API
API Ringostat. Экспорт журнала звонков
API Ringostat. Проверка доступности SIP-аккаунта
Webhook номер
API Ringostat. Экспорт данных о сотрудниках проекта
Нашли ответ на свой вопрос?