Интерфейс прикладного программирования (API)
для SIP Resident
ООО «Сарапульские системы», 2023
Сервер API по умолчанию работает на TCP порте 9100. Требуется его включение в настройках. Взаимодействие с сервером осуществляется при помощи HTTP-запросов. Запрос может включать дополнительные параметры, упакованные в структуру JSON. В этом случае они передаются методом POST. Ответ содержит структуру JSON, либо файл, в случае если в ответе ожидается файл.
URI запроса выглядит следующим образом:
http://<ip>:<port>/<cmd>
где ip - адрес устройства, port - порт сервера API, cmd - команда.
Ответ, представляющий собой структуру JSON имеет 1 обязательное поле error.
Пример:
{
“error”: “OK”
}
Определены следующие возможные значения этого поля.
|
Значение |
Пояснение |
| OK | Запрос выполнен без ошибок |
| PARSE_ERROR | Некорректная структура JSON |
| WRONG_FUNCTION | Неверное название команды |
| WRONG_ARGS | Параметры имеют некорректный тип либо их значения выходят за границы диапазона допустимых значений |
| ARGUMENTS_REQUIRED | Не хватает одного или нескольких обязательных параметров |
| PROCESSING_ERROR | Во время выполнения запроса произошла ошибка |
Если значением поля error не является “OK”, то ответ также будет содержать дополнительное строковое поле error_msg, которое содержит подробности возникшей ошибки.
Получение информации об устройстве.
| Параметр | Пояснение | |
| tags | Обязательный параметр. Массив строковых значений, по которым определяется какие данные необходимо получить. Возможные значения. | |
|
Значение |
Назначение |
|
| disk_space | Сведения о занятом пространстве | |
| license | Сведения о лицензии и коде активации | |
| version | Версия ПО | |
| date_time | Текущие дата, время и часовой пояс | |
| devicemark | Метка устройства | |
Запрос:
{
"tags" : [ "disk_space", "license", "version", "date_time", "devicemark" ]
}
Ответ:
{
"data" :
{
"date_time" :
{
"date" : "29.12.2022",
"time" : "11:38:19",
"tz" : "Europe/Moscow"
},
"devicemark" : "",
"disk_space" :
{
"total" : "29.68G",
"used" : "18.18G",
"used_percent" : 61
},
"license" :
{
"activation_code" : "activation_code…",
"channels" : 1
},
"version" : "0.4.0-1"
},
"error" : "OK"
}
Получает сведения о разговорах и записях.
Все параметры являются необязательными.
|
Параметр |
Тип |
Пояснение |
|
| from | число | Задает с какой из найденных записей начать составлять набор. Нумерация начинается с 0. Значение по умолчанию - 0. Кроме того, можно указать отрицательное значение from для получения последних записей. Например, указав -2, можно получить сведения о 2-х последних записях. | |
| count | число | Задает кол-во получаемых записей. Максимально - 100. Значение по умолчанию - 10. Можно указать 0 для получения только общего кол-ва записей. | |
| callid | строка | SIP-идентификатор разговора | |
| caller_num | строка | Номер вызывающей стороны | |
| called_num | строка | Номер вызываемой стороны | |
| num | строка | Номер любой из сторон. Не сочетается с параметрами caller_num и called_num | |
| caller_name | строка | Имя вызывающей стороны, если определено, в противном случае будет совпадать с caller_num | |
| called_name | строка | Имя вызываемой стороны, если определено, в противном случае будет совпадать с called_num | |
| name | строка | Имя любой из сторон. Не сочетается с параметрами caller_num и called_num | |
| status | строка | Статус разговора. Возможные значения | |
|
Значение |
Назначение |
||
| STATUS_ANSWERED | Вызов принят | ||
| STATUS_MISSED | Вызов пропущен | ||
| STATUS_REJECTED | Вызов отклонен | ||
| STATUS_UNKNOWN | Статус неизвестен | ||
| statuses | массив строк | Массив значений параметров status, не сочетается с параметром status. | |
| error | строка | Ошибка или предупреждение. Возможные значения. | |
|
Значение |
Назначение |
||
| ERROR_OK | Успешно обработано | ||
| ERROR_MAX_CHANNELS | Достигнуто ограничение по кол-ву каналов | ||
| ERROR_UNSUPPORTED_CODECS | В разговоре присутствовали неподдерживаемые кодеки | ||
| ERROR_UNABLE_TO_PROCESS | Ошибка обработки | ||
| ERROR_NO_MEDIA_DATA | Медиаданных не обнаружено | ||
| ERROR_RECORD_DISABLED | Запись отключена в настройках | ||
| ERROR_DECLINED_BY_LIST | Запись не произведена, т.к. абонент входит в “черный”/”белый” список | ||
| ERROR_RECORD_TOO_SHORT | Запись слишком короткая | ||
| ERROR_UNKNOWN | Неизвестная ошибка | ||
| errors | массив строк | Массив значений параметров error, не сочетается с параметром error. | |
| since | строка | Начало диапазона дат в формате “yyyy-MM-dd hh-mm-ss” | |
| until | строка | Конец диапазона дат в формате “yyyy-MM-dd hh-mm-ss” | |
| duration_min | число | Минимальная длительность | |
| duration_max | число | Максимальная длительность | |
| order_by | массив объектов |
Критерии сортировки записей. Массив содержит объекты с критерием сортировки и ее направлением (asc или desc). Пример объекта: {“caller_num”: “asc”} Порядок объектов в массиве имеет значение. |
|
|
Значение |
Критерий сортировки |
||
| caller_num | По номеру вызывающей стороны | ||
| called_num | По номеру вызываемой стороны | ||
| caller_name | По имени вызывающей стороны | ||
| called_name | По имени вызываемой стороны | ||
| date | По дате (по умолчанию) | ||
| duration | По длительности | ||
Ответ на запрос будет содержать следующее.
|
Поле |
Пояснение |
|
| from | Переданный параметр from | |
| count | Кол-во возвращаемых элементов | |
| total_count | Общее кол-во элементов, подходящий под заданные критерии | |
| records | Массив объектов, содержащих сведения о записях. Объекты следующие. | |
|
Поле |
Пояснение |
|
| cid | Идентификатор записи | |
| callid | SIP-идентификатор разговора | |
| caller_num | Номер вызывающей стороны | |
| called_num | Номер вызываемой стороны | |
| caller_name | Имя вызывающей стороны, если определено, либо будет совпадать с caller_num | |
| called_name | Имя вызываемой стороны, если определено, либо будет совпадать с called_num | |
| status | Статус разговора | |
| error | Ошибка или предупреждение | |
| date | Дата в формате “yyyy-MM-dd hh-mm-ss” | |
| duration | Длительность | |
| content_type | Тип контента файла записи: “audio/wav”, “audio/mpeg”, либо пустое значение если файл отсутствует | |
| size | Размер файла | |
Пример:
Запрос:
{
"count": 5,
"num": "123",
"status": "STATUS_ANSWERED",
"order_by": [{"duration":"desc"}, {"date":"desc"}]
}
Ответ:
{
"data" :
{
"count" : 2,
"from" : 0,
"records" :
[
{
"called_name" : "123",
"called_num" : "123",
"caller_name" : "124",
"caller_num" : "124",
"callid" : "OpcePgxR4.4sxaXBdoezmGVPecQ08vJF",
"content_type" : "audio/mpeg",
"date" : "2016-11-30 19:47:23",
"duration" : 12,
"error" : "ERROR_OK",
"cid" : "2",
"size" : 51840,
"status" : "STATUS_ANSWERED"
},
{
"called_name" : "124",
"called_num" : "124",
"caller_name" : "Alexey",
"caller_num" : "123",
"callid" : "f048f0cd4f5d4398a4672295875aa1c9",
"content_type" : "",
"date" : "2022-12-12 16:34:08",
"duration" : 0,
"error" : "ERROR_OK",
"cid" : "787454545",
"size" : 0,
"status" : "STATUS_ANSWERED"
}
],
"total_count" : 2
},
"error" : "OK"
}
Получить файл записи.
Возвращает файл записи, либо код HTTP 404, если файл не найден.
|
Параметр |
Пояснение |
| cid | Идентификатор записи разговора, полученный командой /GetRecordsInfo. Обязательный параметр |
Запрос:
{
"cid" : "2"
}
Команда, аналогичная /GetRecordFile, но идентификатор можно передать в строке GET.
Перезагрузка устройства.
Выключение устройства.
Получение уведомлений о разговорах через SSE (Server-Sent Events). Ответ на запрос по мере наступления событий будет дополняться. Каждое событие отделяется от другого пустой строкой. Информация о событии заключена в 3-х полях по одному на каждой строке: id - идентификатор события (порядковый номер), event - тип события, data - подробности, представленные в формате JSON. Заголовок Last-Event-ID в запросе может передать значение идентификатор последнего полученного события, это позволить получить пропущенные события (не более 100) в случае дисконнекта.
Коротко об SSE можно прочитать здесь. Обратите внимание, что если вы используете JavaScript для обработки событий, то необходимо подписаться на них используя метод addEventListener, а не onmessage.
Определены следующие типы событий и их параметры.
| Событие | Пояснение | |
| call_started | Начался вызов абонента. | |
|
Параметр |
Пояснение |
|
| cid | Внутренний идентификатор вызова | |
| callid | SIP-идентификатор | |
| caller_num | Номер вызывающей стороны | |
| called_num | Номер вызываемой стороны | |
| caller_name | Имя вызывающей стороны, если определено, в противном случае будет совпадать с caller_num | |
| called_name | Имя вызываемой стороны, если определено, в противном случае будет совпадать с called_num | |
| call_completed | Разговор завершен (повешена трубка). | |
|
Параметр |
Пояснение |
|
| cid | Внутренний идентификатор вызова | |
| call_processed | Вызов обработан. | |
|
Параметр |
Пояснение |
|
| cid | Внутренний идентификатор вызова | |
| status | Статус разговора | |
| error | Ошибка или предупреждение | |
| got_dtmf | Получен DTMF (только RFC 4733). | |
|
Параметр |
Пояснение |
|
| cid | Внутренний идентификатор вызова | |
| dir | Сторона: "caller" - вызывающий, "called" - вызываемый | |
| dtmf | Значение DTMF в виде соответствующего символа из списка 16 зарезервированных символов, в остальных случаях в виде “ev(num)” (например, “ev171”). | |
Каждый вызов имеет свой внутренний cid начинается событием “call_started” и заканчивается “call_processed”. В общем случае событие “call_processed” означает, что вызов обработан и доступен для команд /GetRecordsInfo и /GetRecordFile. До этого времени cid не будет считаться валидным.
Если на вызов не ответили, то событие call_completed как и call_answered не будет отправлено.
Пример:
id: 13826
event: call_started
data: {"called_name":"124","called_num":"124","caller_name":"alex","caller_num":"123", "callid":"6DK8_81ZPbnsY18OPwbvZA..","cid":"5374"}
id: 13827
event: call_answered
data: {"cid":"5374"}
id: 13828
event: got_dtmf
data: {"dir":"called","dtmf":"#","cid":"5374"}
id: 13829
event: call_completed
data: {"cid":"5374"}
id: 13830
event: call_processed
data: {"error":"ERROR_OK","cid":"5374","status":"STATUS_ANSWERED"}
id: 13831
event: call_started
data: {"called_name":"123","called_num":"123","caller_name":"lev","caller_num":"124","callid":"gwrsR6xKD6YIFVREtNuslg..","cid":"5375"}
id: 13832
event: call_processed
data: {"error":"ERROR_OK","cid":"5375","status":"STATUS_MISSED"}