Разработчики SIPNET неоднократно решали сложные задачи по интеграции с различными публичными и массовыми сервисами, но и простые пользователи также не забыты. Есть несколько возможностей для автоматизации взаимодействия и интеграции с CRM системами.
SIPNET готов сотрудничать с компаниями, предоставляющими свои услуги и интегрирующими услуги SIPNET в свои продукты.
Наглядный пример, это сервис Mail.Ru, который многие годы предоставлял возможность пользователям программы "Агент Mail.Ru" звонить через сеть SIPNET.
Можно обсудить разработку любого API под задачу и интеграцию любых сервисов с SIPNET. Мы открыты для сотрудничества.
Наиболее популярные функции нашего API описаны в статьях этой категории.
Для получения информации в реальном времени нужно использовать WebHook, который реализован в рамках новой версии API.
Описание новой версии API читайте в формате PDF
Какие данные передаются:
call_id (uuid)
sip_id
caller_id
callee_id
created (rfc3339)
state
direction
cid (number)
duration (number)
event_created (rfc3339)
WebHook работает только по одному адресу. Если прописано 2 адреса, тот адрес который указан последним и будет использован.
Авторизации сервера не требуется. Запросить может любой клиент, с любого устройства или из программы.
Наш сервер отвечает на запросы в таких форматах:
https://balance.sipnet.ru/?sipuid=sipuid&password=password или https://balance.sipnet.ru/sip_balance?sipuid=sipuid&password=password (такой запрос используется в телефонах Yealink для получения остатка средств на счете) или https://balance.sipnet.ru/?operation=balance&sipuid=sipuid&password=password
Возможно использовать имя сервера https://api.sipnet.ru, но у него не прописаны короткие пути, поэтому ссылка будет длинной:
https://api.sipnet.ru/cgi-bin/Exchange.dll/sip_balance?operation=balance&sipuid=sipuid&password=password
Запросы принимаются методами POST или GET.
Все запросы поддерживают следующие необязательные переменные, определяющие формат ответов.
Переменные format и lang задают нужный способ форматирования ответа и язык сообщений.
Доступные форматы:
0 – xml (по умолчанию)
1 – plain
2 – json
Доступные языки:
ru – Русский (По умолчанию, кодировка UTF8)
en – Английский
[operation=balance]
sipuid=<логин или SIPID>
password=<пароль>
[format={0,1,2}]
[lang={en,ru}]
operation=cabinetmain
sipuid=<логин или SIPID>
password=<пароль>
[format={0,1,2}]
[lang={en,ru}]Замечание
Возвращает одноразовую ссылку, с помощью которой клиент может войти в свой личный кабинет, на главную страницу.
operation=cabinetpayment
sipuid=<логин или SIPID>
password=<пароль>
[format={0,1,2}]
[lang={en,ru}]Замечание
Возвращает одноразовую ссылку, с помощью которой клиент может войти в свой личный кабинет, на страницу платежных систем.
operation=chronopay
sipuid=<логин или SIPID>
password=<пароль>
money=<Сумма платежа например 100.00>
[format={0,1,2}]
[lang={en,ru}]Замечание
Возвращает подписанную ссылку, с помощью которой клиент может совершить платеж банковской карточкой, на странице платежной системы ChronoPay.
Данный запрос позволяет получить тариф звонка на номер телефона не инициируя звонок.
operation=getphoneprice
sipuid=<логин или SIPID>
password=<пароль>
Phone=<номер>
[format={0,1,2}]
[lang={en,ru}]Замечание
Для вычисления тарифа заказа на соединении двух номеров телефона нужно сделать два запроса (по одному для каждого номера), затем полученные данные сложить.
operation=getAONphones
sipuid=<логин или SIPID>
password=<пароль>
[format={0,1,2}]
[lang={en,ru}]
В тех случаях, когда есть необходимость раздельно учитывать звонки пользователей CRM системы, целесообразно каждому пользователю CRM системы создать соответствующий дочерний аккаунт в SIPNET и звонки пользователей CRM инициировать от имени их дочерних аккаунтов. На основном аккаунте SIPNET необходимо настроить способ оплаты звонков дочерних аккаунтов. Доступны два варианта:
Подробнее о дочерних счетах смотрите в личном кабинете Счет -> Дочерние счета
operation=children
sipuid=<логин или SIPID>
password=<пароль>
[format={0,1,2}]
[lang={en,ru}]Замечание
Все действия с дочерними аккаунтами можно производить только от имени основного аккаунта.
operation=addchild
sipuid=<логин или SIPID>
password=<пароль>
[format={0,1,2}]
[lang={en,ru}]
Замечание 1
Все действия с дочерними аккаунтами можно производить только от имени основного аккаунта.
Замечание 2
Обычному пользователю SIPNET позволяется создать до 100 дочерних аккаунтов, если Вам требуется больше, обратитесь в службу поддержки.
operation=addmoney
sipuid=<логин или SIPID>
password=<пароль>
childrenLogin=<логин или SIPID дочернего аккаунта>
childrenMoney=<сумма переводимых средств в валюте основного аккаунта>
[format={0,1,2}]
[lang={en,ru}]Замечание 1
Пополнение дочернего аккаунта возможно только за счет средств основного аккаунта.
Замечание 2
Для перевода средств с дочернего аккаунта на основной, выполнить пополнение на отрицательную сумму.
operation=aonnumberslist
sipuid=<логин или SIPID>
password=<пароль>
[format={0,1,2}]
[lang={en,ru}]
operation=addaonnumber
sipuid=<логин или SIPID>
password=<пароль> phone=<Номер телефона, который нужно проверить>
[checktype={1,2}] # тип проверки 1- звонком(по умолчанию), 2-SMS (доступно только для мобильных номеров)
[checkAON=<Номер телефона АОН для проверочного звонка>] # Не реализовано. Можно указать один из номеров АОН уже подключенных или купленный у Sipnet номер.
[format={0,1,2}]
[lang={en,ru}]
operation=keyaonnumber
sipuid=<логин или SIPID>
password=<пароль> key=<Код проверки номер телефона>
[format={0,1,2}]
[lang={en,ru}]
operation=delaonnumber
sipuid=<логин или SIPID>
password=<пароль> phone=<Номер телефона, который нужно удалить> # Удаляем АОН с акrаунта. [format={0,1,2}]
[lang={en,ru}]
operation=genCall
sipuid=<логин или SIPID>
password=<пароль>
[SrcPhone=<номер 1>]
DstPhone=<номер 2> [Delay=<задержка в секундах>]
[prompt=<ссылка на звуковой файл приветствия>]
[format={0,1,2}]
[lang={en,ru}]Замечание 1
SIPNET может записывать звонки и хранить их в течении некоторого времени. Подробнее об этом см. Запись звонков.
Замечание 2
Если SrcPhone не указан, то подставляется номер, выбранный пользователем как "АОН по умолчанию".
Замечание 3
В поле SrcPhone и DstPhone можно указать SIPID в формате sip:<SIPID>[@sipnet.ru].
Замечание 4
В ответ на запрос возвращается дополнительное поле ID означающее идентификатор заказанного соединения например id="30239923". Данный идентификатор можно сохранить и с его помощью идентифицировать соединение в статистике звонков используя метод CALLS2.
Замечание 5
В поле prompt подразумевается передача имени файла со звуковым приветствием оператору первого плеча разговора. Файл можно загрузить на сервер SIPNET, или создать с помощью text to speech генератора, доступного в виртуальной АТС. Реальное имя файла, которое необходимо указать в поле prompt, можно узнать только через технического специалиста службы поддержки. В качестве примера для тестирования можно использовать файл "ivr-022381-000398.wav". Формат файла в случае его загрузки - wav 8 khz 16 bit mono.
Запрос ID для номера телефона в первом плече CallBack звонка. Делается один раз (повторный запрос возвращает новый ID и отменяет действие предыдущего), полученный ID можно использовать многократно.
operation=registerphone1
sipuid=<логин или SIPID>
password=<пароль>
Phone=<номер телефона>
[format={0,1,2}]
[lang={en,ru}]Замечание 1
Результатом является уникальная идентифицирующая строка, ID которую нужно использовать при дальнейшем заказе звонков.
Замечание 2
Переменная Phone принимает номер телефона в формате E.164 или SIPID в формате sip:<SIPID>.
В функции gencall вместо идентификаторов sipuid, password и SrcPhone можно указать ID = "id из результата запроса registerphone1".
operation=genCall
id=<id из результата запроса registerphone1>
DstPhone=<номер 2> [Delay=<задержка в секундах>] [prompt=<ссылка на звуковой файл приветствия>]
[format={0,1,2}]
[lang={en,ru}]
Стандартный запрос данных из БД. Возвращает информацию по всем кнопкам, созданным у пользователя.
operation=webbuttons
sipuid=<логин или SIPID>
password=<пароль>
[format={0,1,2}]
[lang={en,ru}]Замечание 1
Результатом является список всех кнопок, созданных на Вашем аккаунте. Поле cid в ответе это data-token который должен указываться в коде кнопки, размещаемой на странице Вашего сайта.
Замечание 2
Поле cid связывает настройки поведения кнопки сохраненные через ЛК (WEB интерфейс, или через API), с фактическим кодом размещенным на Вашем сайте.
Замечание 3
Если необходимо изменить внешний вид кнопки, или установить счетчик нажатий на кнопку, вы можете это сделать. см. инструкцию Яндекс Метрика и Категория: Fast2Call
Позволяет создать новую кнопку и возвращает её идентификатор cid. Только параметр phone является обязательным, но и он может быть изменен в дальнейшем.
operation=addwebbutton
sipuid=<логин или SIPID>
password=<пароль>
phone=<Номер телефона на который звонит WEBRTC кнопка>
[color=Цвет] # Цвет кнопки. По умолчанию #008735. [btntype={1,2,3}] # Тип кнопки. По умолчанию "2".
[text=Текст] # Текст который выводится на кнопке если тип кнопки "3".
[descr=Описание] # Описание кнопки выводится в ЛК клиента и возвращается в методе webbuttons. По умолчанию "Кнопка через API".
[dtmf={Y,N}] # Поддержка кнопкой функций набора DTMF. Нужно для перехода по IVR. По умолчанию "N".
[format={0,1,2}]
[lang={en,ru}]
Позволяет изменить параметры кнопки, в том числе телефон, на который она звонит. Внешний вид кнопки зависит от HTML кода размещенного на странице сайта. Изменение большинства параметров повлияет только на внешний вид кнопок в ЛК и код кнопки, который можно получить там-же, но не на кнопки размещенные на страницах сайта.
operation=editwebbutton
sipuid=<логин или SIPID>
password=<пароль>
cid=<ID кнопки> # Cid это главная часть кода кнопки, размещаемая на странице Вашего сайта.
phone=<Номер телефона на который звонит WEBRTC кнопка> [color=Цвет] # Цвет кнопки. По умолчанию #008735.
[btntype={1,2,3}] # Тип кнопки. По умолчанию "2".
[text=Текст] # Текст который выводится на кнопке если тип кнопки "3".
[descr=Описание] # Описание кнопки выводится в ЛК клиента и возвращается в методе webbuttons. По умолчанию "Кнопка через API".
[dtmf={Y,N}] # Поддержка кнопкой функций набора DTMF. Нужно для перехода по IVR. По умолчанию "N".
[format={0,1,2}]
[lang={en,ru}]
Стандартный запрос удаления данных из БД.
operation=delwebbutton
sipuid=<логин или SIPID>
password=<пароль>
cid=<ID кнопки>
[format={0,1,2}]
[lang={en,ru}]
operation=calls
sipuid=<логин или SIPID>
password=<пароль>
[D1=<дата с>] # по умолчанию сегодня [D2=<дата по>] # по умолчанию сегодня
[showchild=1] # Добавить в вывод звонки дочерних аккаунтов. По умолчанию showchild=0
[format={0,1,2}]
[lang={en,ru}]
Внимание
Метод calls не предполагает использования для получения информации в реальном времени. Его не нужно использовать чаще, чем раз в 10 минут. Для получения информации в реальном времени нужно использовать WebHook, который реализован в рамках новой версии API. Описание читайте в формате PDF https://newapi.sipnet.ru/apidoc.pdf
Замечание 1
Переменные D1 и D2 принимают даты в формате DD/MM/YYYY.
Замечание 2
Если переменные D1 и D2 заданы не верно или отсутствуют то возвращаются данные за сегодня.
Замечание 3
Если в личном кабинете клиента настроена запись разговоров, то в ответе на запрос присутствует ссылка на файл (см. примеры ответов). Ссылки действительны в течении текущих суток по GMT, затем нужно получать новую ссылку. Скачать файл можно только с того же IP, с которого производился запрос
Метод для поиска пропущенных звонков в ВАТС. Имеется в виду звонки, которые попали в ВАТС но не были приняты оператором.
operation=pbxcalls
sipuid=<логин или SIPID>
password=<пароль>
[D1=<дата с>] # по умолчанию сегодня
[D2=<дата по>] # по умолчанию сегодня
[format={0,1,2}]
[lang={en,ru}]
Значения некоторых полей ответа:
Метод предназначен для получения информации о двуплечевых звонках, которые составляют один разговор. Каждый такой разговор содержит ID заказа.
operation=calls2
sipuid=<логин или SIPID>
password=<пароль>
[ID=<ID конкретного заказа>] [D1=<дата с>] # по умолчанию сегодня
[D2=<дата по>] # по умолчанию сегодня
[format={0,1,2}]
[lang={en,ru}]Замечание 1
Переменные D1 и D2 принимают даты в формате DD/MM/YYYY.
Замечание 2
Если переменные D1 и D2 заданы не верно или отсутствуют то возвращаются данные за сегодня.
Замечание 3
Если указана переменная ID, то из данных за период D1 - D2 выбираются только звонки относящиеся к данному заказу, т.е. работает как фильтр конкретного заказа.
Замечание 4
Если в личном кабинете клиента настроена запись разговоров, то в ответе на запрос присутствует ссылка на файл (см. примеры ответов). Ссылки действительны в течении текущих суток по GMT, затем нужно получать новую ссылку. Скачать файл можно только с того же IP, с которого производился запрос.
Замечание 5
Если при настройке записи разговоров клиент указал пароль, то ссылка на запись позволяет скачать zip архив, а не mp3 файл. Сведения о типе скачиваемого файла имеются в заголовке HTML и скрипт может их анализировать. см. примеры использования API.
Пока не реализовано.
<html>
<head lang="ru">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Связь клиента и оператора</title>
</head>
<body>
<h1>Ваш рабочий инструмент</H1>
<form method="POST" action="https://api.sipnet.ru/cgi-bin/Exchange.dll/sip_balance">
<input type=hidden name="operation" value="genCall">
<input type=hidden name="sipuid" value="sipid"> <-- sipid - заменить на реальный SIPID -->
<input type=hidden name="password" value="password"> <-- password - заменить на реальный пароль -->
<input type=hidden name="SrcPhone" value="Номер"> <-- Номер - заменить на номер телефона оператора -->
Введите телефон клиента: <input type="text" name="DstPhone" maxlength="32" size="16" VALUE="">
<input type=hidden name="format" value="1">
<input class="button" type="submit" value="Звонок">
</form>
</body>
</html>
<html>
<head lang="ru">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1251"/>
<title>Добавить новую дочку</title>
</head>
<body>
<h1>Ваша кнопка для добавления дочерних аккаунтов</H1>
<form method="POST" action="https://api.sipnet.ru/cgi-bin/Exchange.dll/sip_balance">
<input type=hidden name="operation" value="addchild">
Введите SIP ID: <input type="text" name="sipuid" maxlength="32" size="16" VALUE="">
Введите Пароль: <input type="password" name="password" maxlength="32" size="16" VALUE="">
<input type=hidden name="format" value="1">
<input class="button" type="submit" value="Добавить дочку">
</form>
</body>
</html>
Положительный XML.
<protocol namespace="SIPNET" ver="1.0">
<response>
<balance value="3.52" currency="USD" mbaccount="A_Zotov_I"/>
<result>0</result>
</response>
</protocol>
Положительный JSON.
{"Result": true,"mbaccount": "A_Zotov_I","currency": "USD","balance": "3.52"}Ошибка в запросе XML.
<protocol namespace="SIPNET" ver="1.0">
<response>
<result>1</result>
<comment>Лицевой счёт не найден</comment>
</response>
</protocol>Ошибка в запросе JSON.
{"Result": false,"ResultStr": "Лицевой счёт не найден"}
Положительный XML.
<protocol namespace="SIPNET" ver="1.0">
<response>
<phoneprice minprice="0.00000" maxprice="0.00000" currency="USD" mbaccount="A_Zotov_I"/>
<result>0</result>
</response>
</protocol>
Положительный JSON.
{"Result": true,"minprice": "0.02500","maxprice": "0.02500","mbaccount": "A_Zotov_I","currency": "USD"}
Ошибка в запросе XML.
<protocol namespace="SIPNET" ver="1.0">
<response>
<result>2</result>
<comment>Неправильный номер.</comment>
</response>
</protocol>
<protocol namespace="SIPNET" ver="1.0">
<response>
<result>1</result>
<comment>Лицевой счёт не найден</comment>
</response>
</protocol>
Ошибка в запросе JSON.
{"Result": false,"ResultStr": "Неправильный номер."}
{"Result": false,"ResultStr": "Лицевой счёт не найден"}
Положительный XML (включая ID заказа звонка)
<protocol namespace="SIPNET" ver="1.0">
<response>
<gencall value="Звонок инициирован" mbaccount="A_Zotov_I" id="30239177" />
<result>0</result>
</response>
</protocol>
Положительный JSON
{"Result": true,"gencall": "Звонок инициирован","mbaccount": "A_Zotov_I","id": "30239177"}
Ошибка в запросе JSON.
{"Result": false,"ResultStr": "Неправильный исходный номер."}
Положительный XML
<protocol namespace="SIPNET" ver="1.0">
<response>
<calls mbaccount="A_Zotov_I">
<call gmt="20/07/2016 07:28:20" phone="2777777@sipnet.ru" account="A_Zotov_I_1" cid="592239713" calltype="22" aon="A_Zotov_I_1@sipnet.ru" direction="SIP ID (OUT)" duration="1087" cost="0.00000"/>
<call gmt="20/07/2016 13:33:48" phone="74953643333" account="A_Zotov_I" cid="592713163" calltype="10" aon="" direction="Russia Moscow" duration="112" cost="0.02053" url="https://api.sipnet.ru/cgi-bin/exchange.dll/ListenRec.mp3?id=F97E4613BE54D7182B702A4C46661AB97DA030D7336A463D"/>
<call gmt="20/07/2016 15:29:13" phone="00000@sipnet.ru" account="A_Zotov_I" cid="592800290" calltype="22" aon="a_zotov_i@sipnet.ru" direction="SIP ID (OUT)" duration="11" cost="0.00000"/>
<call gmt="20/07/2016 15:30:12" phone="00000@sipnet.ru" account="A_Zotov_I" cid="592800678" calltype="22" aon="a_zotov_i@sipnet.ru" direction="SIP ID (OUT)" duration="7" cost="0.00000"/>
</calls>
<result>0</result>
</response>
</protocol>
Ошибка в запросе XML
<protocol namespace="SIPNET" ver="1.0">
<response>
<result>1</result>
<comment>Лицевой счёт не найден</comment>
</response>
</protocol>Положительный JSON
{"Result": true,
"calls": [
{"gmt": "20/07/2016 07:28:20",
"phone": "2777777@sipnet.ru",
"account": "A_Zotov_I_1",
"cid": "592239713",
"calltype": "22",
"aon": "A_Zotov_I_1@sipnet.ru",
"direction": "SIP ID (OUT)",
"duration": "1087",
"cost": "0.00000"},
{"gmt": "20/07/2016 13:33:48",
"phone": "74953643333",
"account": "A_Zotov_I",
"cid": "592713163",
"calltype": "10",
"aon": "",
"direction": "Russia Moscow",
"duration": "112",
"cost": "0.02053",
"url": "https://api.sipnet.ru/cgi-bin/exchange.dll/ListenRec.mp3?id=F97E4613BB23DF212B702A4C46661AB960A6CF09336A463D"},
,{"gmt": "20/07/2016 15:29:13",
"phone": "00000@sipnet.ru",
"account": "A_Zotov_I",
"cid": "592800290",
"calltype": "22",
"aon": "a_zotov_i@sipnet.ru",
"direction": "SIP ID (OUT)",
"duration": "11",
"cost": "0.00000"}
,{"gmt": "20/07/2016 15:30:12",
"phone": "00000@sipnet.ru",
"account": "A_Zotov_I",
"cid": "592800678",
"calltype": "22",
"aon": "a_zotov_i@sipnet.ru",
"direction": "SIP ID (OUT)",
"duration": "7",
"cost": "0.00000"}],
"mbaccount": "A_Zotov_I"}
Ошибка в запросе JSON.
{"Result": false,"ErrorStr": "Лицевой счёт не найден"}
Положительный XML (Включая ID заказа и две части звонка)
<protocol namespace="SIPNET" ver="1.0">
<response>
<calls2 mbaccount="A_Zotov_I">
<call id="30239177" gmt="20/05/2015 13:53:23" phonesrc="79255006612" phonedst="97239723366" cidsrc="399621968" directionsrc="Russia Mobile - Megafon" durationsrc="19" costsrc="0.02787" gmtsrc="20/05/2015 13:53:34" ciddst="399621969" directiondst="Israel Proper" durationdst="12" costdst="0.02787" gmtdst="20/05/2015 13:53:41"/>
<call id="30239671" gmt="20/05/2015 14:37:53" phonesrc="79255006612" phonedst="97239723366" cidsrc="399639474" directionsrc="Russia Mobile - Megafon" durationsrc="17" costsrc="0.02493" gmtsrc="20/05/2015 14:38:11" ciddst="399639475" directiondst="Israel Proper" durationdst="11" costdst="0.02493" gmtdst="20/05/2015 14:38:17"/>
<call id="30239693" gmt="20/05/2015 14:39:50" phonesrc="79255006612" phonedst="97239723366" cidsrc="399640156" directionsrc="Russia Mobile - Megafon" durationsrc="2" costsrc="0.00293" gmtsrc="20/05/2015 14:40:04"/>
</calls2>
<result>0</result>
</response>
</protocol>
Положительный JSON
{"Result": true,
"calls2": [
{"gmt": "20/05/2015 13:53:23",
"phonesrc": "79255006612",
"phonedst": "97239723366",
"id": "30239177"
"cidsrc":"399621968",
"directionsrc":"Russia Mobile - Megafon",
"durationsrc":"19",
"costsrc":"0.02787",
"gmtsrc":"20/05/2015 13:53:34",
"ciddst":"399621969",
"directiondst":"Israel Proper",
"durationdst":"12",
"costdst":"0.02787",
"gmtdst":"20/05/2015 13:53:41"}
{"gmt": "20/05/2015 14:37:53",
"phonesrc": "79255006612",
"phonedst": "97239723366",
"id": "30239671"
"cidsrc":"399639474",
"directionsrc":"Russia Mobile - Megafon",
"durationsrc":"17",
"costsrc":"0.02493",
"gmtsrc":"20/05/2015 14:38:11",
"ciddst":"399639475",
"directiondst":"Israel Proper",
"durationdst":"11",
"costdst":"0.02493",
"gmtdst":"20/05/2015 14:38:17"}
{"gmt": "20/05/2015 14:39:50",
"phonesrc": "79255006612",
"phonedst": "97239723366",
"id": "30239693"
"cidsrc":"399640156",
"directionsrc":"Russia Mobile - Megafon",
"durationsrc":"2",
"costsrc":"0.00293",
"gmtsrc":"20/05/2015 14:40:04"}],
"mbaccount": "A_Zotov_I"}
Ошибка в запросе JSON
{"Result": false,"ErrorStr": "Лицевой счёт не найден"}