'ccs' capability для WebSocket Token API

Содержание

Обзор
Запросы к серверу
Концепция интеграции с внешней системой и продуктовым слоем
Ссылки

Обзор

Предоставляет интерфейс для управления звонками (Подмножество CallManager REST-API).

Запросы, управляющие конкретным соединением, требуют указания параметра 'idconn'. Его можно обнаружить в событиях класса ccsevents о вызовах, либо в поле 'connectionid' событий класса callevents, либо в ответе на запрос чтения коллекции звонков. Запросы, управляющие конкретным плечом соединения, либо имеющие направление применения, требуют указания параметра 'idcall'. Это Call-Id конкретного плеча. Его можно обнаружить в событиях классов ccsevents и callevents, либо в ответе на запрос чтения коллекции звонков.

Запросы к серверу

Завершение звонка (bye)

Производится принудительный разрыв диалога с отправкой BYE обеим сторонам. Если диалог находится в состоянии Forking, то производит принудительное завершение диалога путем отправки CANCEL всем абонентам и неудачного ответа инициатору вызова.

Пример

[
  "bye",
  {
    "qid": 0.1234,
    "owner": "",
    "idcall": "",
    "idconn": "3694473f-0641-450c-2c15-c00000000002.1601282818792"
  }
]

Инициация нового звонка (new_invite)

Производит intercom-вызов устройства инициатора, указанного в поле owner, от имени CallManager с участием IVR-сценария. После снятия трубки производит перевод на указанный в поле number номер.

Если устройство инициатора не поддерживает или запрещает intercom-вызов, то первый служебный вызов производится вплоть до снятия инициатором трубки. Если устройство инициатора поддерживает и разрешает intercom-вызовы, то совершаемый вызов сразу же отвечается устройством.

В случае, когда во время выполнения команды устройство инициатора уже находится в каком-либо диалоге, то в зависимости от настроек устройства либо совершает второй вызов, либо прерывает текущий диалог, устанавливая его на удержание. При этом, если устройство поддерживает и разрешает вторжение через intercom-вызов, то текущий диалог ставится на удержание, а новый инициируемый диалог поступает и автоматически отвечается устройством. Иначе, если вторжение не поддерживается или запрещено, устройство принимает и отображает второй вызов, ожидающий снятия трубки инициатором.

Случай ограничения количества входящих вызовов для учетной записи. Если для учетной записи инициатора настроено ограничение одновременного количества вызовов, а в момент поступления инициируемого нового вызова отсутствуют свободные транки, то входящий intercom-вызов не может пройти и команда возвращает отказ "rejected".

Случай нескольких устройств. Если у инициатора зарегистрировано несколько устройств, поддерживающих и разрешающих intercom-вызовы, то вызов может быть отвечен автоматически на любом из них. В этом случае выбор конкретного устройства фактически носит случайный характер.

Пример

[
  "new_invite",
  {
    "qid": 0.1234,
    "owner": "sip:sip1@test.rootdomain.ru",
    "number": "12"
  }
]

Необязательные параметры:

owner - указатель на URI учетной записи инициатора вызова. Формат: 'sip:USERNAME@DOMAIN' или 'NUMBER'.
use_intercom - устанавливает режим интерком вызова инициатора. По умолчанию 'true'.
idseance - указатель сеанса. При необходимости совершения консультационного вызова, привязанного к уже существующему сеансу обслуживания. Если сеанс не указан, то вызов получает неуправляемую извне привязку к сеансу - это может быть пустой сеанс, новый сеанс, или наследуемый сеанс. Сеанс устанавливается в виде метки (binding) формата 'seance_DIR_ID' и наследуется при переводах.
idparentconn - указатель родительского вызова. При необходимости совершения консультационного вызова, привязанного к существующему вызову. Родительский вызов устанавливается в виде метки (binding) формата 'PARENT:acallid:CALLID' и не наследуется при переводах.

Альтернативный метод invite имеет значение по умолчанию для параметра 'use_intercom' = false.

Пример запроса

[
  "invite",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "number": "11",
    "use_intercom": false
  }
]

NOTE! Для корректной работы режима intercom в системе должен быть настроен featurecode с типом intercom и доступен маршрутами для звонка самому инициатору от его собственного имени.

Опционально может быть указан ключ idseance. Его значение попадет в binding-метку к текущему звонку. В дальнейшем она будет автоматически переноситься во все последующие диалоги текущего сеанса, создаваемые в результате переводов.

Позволяет задавать в номере символы ' и ,. Первый такой символ выделяет оставшуюся последовательность в качестве донабора DTMF после получения ответа, а каждый последующий такой символ обеспечивают паузу в 1 секунду в наборе DTMF.

Пример ответа

[
  "invite_result",
  {
    "qid":123,
    "result": "ok",
    "acallid": "4294572626@192.168.0.149",
    "dialogid": "rDlg-002-911Jnh",
    "ivrcallid": "rIV-006-Z7Bvucu1smS3jgRRuO8ZhcrHXm1",
    "last_response": "SIP/2.0 180 Ringing",
    "result": "ok"
  }
]

Параметры ответа:

dialogid - внутренний ID перенаправленного диалога. По нему можно достать idconn.
ivrcallid - это ID служебного CALL от IVR к Инициатору вызова.
acallid - это ID целевого звонка от Инициатора вызова к вызываемому номеру.

Инициация нового звонка из IVR (invite_byivr)

Производит вызов указанного в поле number от имени callerid и соединяет его со сценарием IVR, код которого указан в поле scriptcode. Если сценарий не указан, то запускается встроенный сценарий ext_api_management с передачей управления внешней системе. Поле key при этом передает значение в соответствующее свойство компонента "Внешнее Управление".

Поле use_intercom позволяет инициировать интерком-вызов абоненту.

Пример запроса

[
  "invite_byivr",
  {
    "qid": 0.1234,
    "number": "12",
    "use_intercom": false,
    "callerid": "1234567",
    "scriptcode": "script_abc"
  }
]

Необязательные параметры:

use_intercom - устанавливает режим интерком вызова. По умолчанию 'false'.
idseance - указатель сеанса. При необходимости совершения вызова, привязанного к уже существующему сеансу обслуживания. Если сеанс не указан, то вызов получает неуправляемую извне привязку к сеансу - это может быть пустой сеанс или новый сеанс. Сеанс устанавливается в виде метки (binding) формата 'seance_DIR_ID' и наследуется при переводах.
idparentconn - указатель родительского вызова. При необходимости совершения консультационного вызова, привязанного к существующему вызову. Родительский вызов устанавливается в виде метки (binding) формата 'PARENT:acallid:CALLID' и не наследуется при переводах.
scriptcode - указатель на код IVR сценария-обработчика вызова. Если не указан, то осуществляется обслуживание встроенным сценарием 'ext_api_management', осуществляющим передачу управления в API (компонент Внешнее управление]).
key - при использовании встроенного сценария 'ext_api_management' устанавливает передаваемый через него ключ в API событие 'ivrevents.api_start'.
callerid - номер абонента-инициатора, подставляемый сценарием IVR в отправляемый запрос INVITE, заголовок From, поле username.
callername - имя абонента-инициатора, подставляемое сценарием IVR в отправляемый запрос INVITE, заголовок From, поле displayname.
calltimeout - таймаут ожидания ответа в секундах.

Пример ответа

[
  "invite_byivr_result",
  {
    "qid": 123,
    "ivrcallid": "rIV-0GC-LBQTDymNxd2hdGyhBu1QNdjTIdz",
    "result": "answered",
    "sipcode": 200
  }
]

Параметры ответа: * ivrcallid - это ID служебного CALL от IVR к Инициатору вызова.

Перехват вызова (pickup)

Производит вызов устройства инициатора запроса с последующим переводом на номер перехвата звонка.

Пример

[
  "pickup",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "number": "11",
    "use_intercom": true
  }
]

Необязательные параметры:

NOTE! Если не указан "number", то будет произведена попытка группового перехвата.

NOTE! Для корректной работы перехвата в системе должен быть настроен featurecode с типом pickup и доступен маршрутами для звонка от имени инициатора на указанный номер (или в группу при групповом перехвате).

Перевод звонка на номер (refer)

Производит вызов с подменой плеча указанного диалога (idconn), после чего инициирует команду REFER с целью его перевода на указанный номер. Плечо диалога, определенное параметром idcall, является инициатором REFER. Подменяется и переводится оппозитное ему плечо. Диалог (idconn) и его плечо (idcall) должны существовать. Звонок должен быть активен, и не может находиться в состоянии вызова, или в состоянии ожидания ответа на отправленный запрос.

Значение idconn поступает в рамках событий класса ccsevents, либо может быть взято из событий класса callevents либо из поля connectionid, либо построено как конкатенация полей cid и its..

Пример запроса

[
  "refer",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
    "number": "11"
  }
]

Необязательные параметры:

Опционально может быть указан ключ idseance. Его значение попадет в binding-метку к вызову, инициирующему перехват запросом INVITE с заголовком Replaces. В дальнейшем она будет автоматически переноситься во все последующие диалоги текущего сеанса, создаваемые в результате переводов.

Пример ответа

[
  "refer_result",
  {
    "qid":123,
    "result": "ok",
    "dialogid": "rDlg-002-Ml5kfx",
    "ivrcallid": "rIV-006-R4AvhlGXOnYjEsTWbUPSiHQcI4N",
    "new_acallid": "4163136050@192.168.0.146",
    "new_dialogid": "rDlg-002-L45G2b",
    "new_last_response": "SIP/2.0 180 Ringing",
    "result": "ok"
  }
]

Параметры ответа:

dialogid - внутренний ID перенаправленного диалога. По нему можно достать idconn.
new_dialogid - внутренний ID вновь созданного диалога. По нему можно достать idconn.
ivrcallid - ID служебного колла, которым IVR взрезал диалог и отправил на refer.
new_acallid - ID целевого колла, которым абонент стал вызывать указанный номер.

Перевод звонка подменой (referreplaces)

Производит вызов с подменой плеча указанного диалога, после чего инициирует команду REFER с целью его перевода подменой на другой диалог. В результате соединяются абоненты двух разных диалогов, а их оппонентам отправляются запросы BYE. Диалог (idconn) и указанное плечо (idcall) должны существовать. Звонок должен быть активен, и не может находиться в состоянии вызова, или в состоянии ожидания ответа на отправленный запрос. В случае если второй вызов не существует, либо находится в неподходящем состоянии, результатом команды будет отбой обоих абонентов первого диалога.

Плечо диалога, определенное параметром idcall, является инициатором REFER. Подменяется и переводится оппозитное ему плечо диалога idconn. Точно также целевым плечом подмены второго диалога idconn2 является плечо, оппозитное указанному параметром idcall2.

Значения idconn и idconn2 поступают в рамках событий класса ccsevents, либо могут быть взяты из событий класса callevents либо из поля connectionid, либо построены как конкатенация полей cid и its.

Как правило, эта команда указывает обоими плечами одного и того же абонента - инициатора запроса - с целью соединить оппонентов из двух разговоров с его участием.

Пример

[
  "referreplaces",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
    "idcall2": "1094205346@192.168.0.149",
    "idconn2": "469e785a-0641-488c-eba4-780000000002.1601297166763"
  }
]

Переключение абонентского устройства в режим HOLD (hold)

Производит эмуляцию нажатия абонентом на кнопку HOLD (постановка его оппонента в текущем разговоре на удержание).

Диалог (idconn) и указанное плечо (idcall) должны существовать. Звонок долен быть активен, и не может находиться в состоянии вызова, или в состоянии ожидания ответа на отправленный запрос. Значение idconn поступает в рамках событий класса ccsevents, либо может быть взято из событий класса callevents либо из поля connectionid, либо построено как конкатенация полей cid и its..

NOTE! Требуется поддержка устройством расширения broadsoft.

NOTE! Применяется только в случае, если в заголовке Allowed-Events, полученном от устройства в ходе установки соединения, присутствует значение hold. Если заголовок Allow-Events отсутствует во всех запросах и ответах от устройства, то пробная отправка запроса NOTIFY в соответствии с протоколом broadsoft также производится.

Пример запроса

[
  "hold",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
  }
]

Пример ответа

[
  "referreplaces_result",
  {
    "qid": 123,
    "result": "ok",
    "ivrcallid": "rIV-006-BPLitgCyrFr6MtfwgJB5i7l0OhW",
    "masterdialogid": "rDlg-002-Et7v2Z",
    "new_acallid": "2799416178@192.168.0.146",
    "new_dialogid": "rDlg-002-TQIZyK",
    "new_last_response": "SIP/2.0 200 OK",
    "result": "ok",
    "slavedialogid": "rDlg-002-PEckZP"
  }
]

Параметры ответа:

masterdialogid - внутренний ID перенаправленного диалога. По нему можно достать idconn.
slavedialogid - внутренний ID принявшего диалога. По нему можно достать idconn.
new_dialogid - внутренний ID вновь созданного диалога. По нему можно достать idconn.
ivrcallid - ID служебного колла, которым IVR взрезал диалог и отправил на refer.
new_acallid - ID целевого колла, которым абонент диалога X подменил абонента в диалоге Y.

Переключение абонентского устройства в режим TALK (talk)

Применяется для автоматического снятия трубки на устройстве в целях ответа на поступивший вызов, а также в целях отмены режима HOLD и снятия абонента с удержания.

NOTE! Требуется поддержка устройством расширения broadsoft.

NOTE! Применяется только в случае, если в заголовке Allowed-Events, полученном от устройства в ходе установки соединения, присутствует значение talk. Если заголовок Allow-Events отсутствует во всех запросах и ответах от устройства, то пробная отправка запроса NOTIFY в соответствии с протоколом broadsoft также производится.

Пример

[
  "talk",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
  }
]

Получение списка текущих разговоров/диалогов (list_connections)

Возвращает список диалогов текущего домена. Применяется для периодической синхронизации данных. Предполагается, что внешняя система получает и данные на основе событий.

Пример запроса

[
  "list_connections",
  {
    "qid":"1234"
  }
]

Пример ответа

[
  "list_connections_result",
  {
    "qid":"1234",
    "data":[
      {
        "a_dn":"SIP4",
        "a_domain":"test.okteller.ru",
        "a_number":"14",
        "a_type":"user",
        "b_dn":"SIP2**",
        "b_domain":"test.okteller.ru",
        "b_number":"12",
        "b_type":"user",
        "dialed":"12",
        "direction":"user -> user",
        "id":"9cbe2eac-068e-e834-0292-7100000003ee.1678951104168",
        "idseance":"1wOVlMzgF96mOjJc5JmqWW7wxp2",
        "state":"connected"
      }
    ],
    "result":"ok"
  }
]

Получение информации об указанном диалоге (get_connection)

Возвращает краткую информацию о диалоге в текущем домене.

Пример запроса

[
  "get_connection",
  {
    "qid":"1234",
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
  }
]

Пример ответа

[
  "get_connection_result",
  {
    "qid":"1234",
    "acallid":"1_1683566754@192.168.0.229",
    "callids":["rB2-0GE-EULJka-01-1_1683566754@192.168.0.229","1_1683566754@192.168.0.229"],
    "dialogid":"rDlg-0GE-EULJka",
    "esgcallid":"",
    "esgdlg":"",
    "inviteid":"9cbe2eac-068e-e834-0292-7100000003ee",
    "legs":[
      {"callid":"1_1683566754@192.168.0.229","expirets":"undefined","localuri":"","remoteuri":"","side":"a"},
      {"callid":"rB2-0GE-EULJka-01-1_1683566754@192.168.0.229","expirets":40000,"localuri":"","remoteuri":"","side":"b"}
    ],
    "localuri":"",
    "opts":{},
    "remoteuri":"",
    "result":"ok",
    "site":"main_site",
    "startts":1678951104168,
    "status":"dialog",
    "uris":["","","",""]
  }
]

Получение списка текущих вызовов/плеч (list_calls)

Возвращает список вызовов/плеч текущем домене. Применяется для периодической синхронизации данных. Предполагается, что внешняя система получает и данные на основе событий.

Пример запроса

[
  "list_calls",
  {
    "qid":"1234"
  }
]

Пример ответа

[
  "list_calls_result",
  {
    "qid":"1234",
    "data":[
      {
        "dn":"SIP4",
        "id":"rB2-0GE-EULJka-01-1_1683566754@192.168.0.229",
        "idseance":"1wOVlMzgF96mOjJc5JmqWW7wxp2",
        "number":"14",
        "owner":"sip:sip2@test.okteller.ru",
        "side":"b",
        "state":"connected",
        "type":"user"
      },
      {
        "dn":"SIP2**",
        "id":"1_1683566754@192.168.0.229",
        "idseance":"1wOVlMzgF96mOjJc5JmqWW7wxp2",
        "number":"12",
        "owner":"sip:sip4@test.okteller.ru",
        "side":"a",
        "state":"connected",
        "type":"user"
      }
    ],
    "result":"ok"
  }
]

Преобразование звонка в конференцию (switch_to_conference)

Применяется для организации конфренеции, в том числе с целью подключения суфлера.

Пример

[
  "switch_to_conference",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
  }
]

Завершение конференции (stop_conference)

Завершает конференцию и отбивает всех участников, обнаруживая ее по идентификатору 'idconf'. Идентификатор можно достать в том числе по диалогу с конференцией методом get_conference

Пример

[
  "stop_conference",
  {
    "qid": 0.1234,
    "idconf": "rCF-0GB-QKZ1gz"
  }
]

Получение списка текущих конференций (list_conferences)

Пример

[
  "list_conferences",
  {
    "qid": 0.1234
  }
]

Получение информации о конференции (get_conference)

Возвращает информацию о конференции, обнаруживая ее по идентификатору (idconf), либо по диалогу, одним из абонентов которого является конференция.

Пример

[
  "get_conference",
  {
    "qid": 0.1234,
    "idconf": "rCF-0GB-QKZ1gz"
  }
]

или

[
  "get_conference",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
  }
]

Пример ответа

[
  "get_conference_result",
  {
    "qid": 0.1234,
    "result": "ok",
    "data": {
      "confid": "rCF-0GB-KbQYEI",
      "confnumber": "KbQYEI",
      "confroomnum": "9",
      "confuri": "<sip:conf-9@test.okteller.ru>",
      "site": "main_site",
      "startts": 1650533772987
    }
  }
]

Получение списка участников конференции (get_participants)

Возвращает список текущих участников активной конференции, обнаруживая ее по идентификатору (idconf). Идентификатор конференции можно достать в том числе по диалогу с конференцией методом get_conference.

По каждому участнику будет возвращет идентификатор ('participantid') и идентификатор звонка ('callid').

Пример запроса

[
  "get_participants",
  {
    "qid": 0.1234,
    "idconf": "rCF-0GB-QKZ1gz"
  }
]

Пример ответа

[
  "get_participants_result",
  {
    "qid": 0.1234,
    "result": "ok",
    "data": [
      {
        "participantid": "2919aaa2-0180-4b7a-d155-7cd30a921f58",
        "callid": "rB2-0GE-CCwUzc-01-913257614@192.168.0.149",
        "state": "active"
        "luri": "<sip:conf-9@test.okteller.ru>",
        "ltag": "rCF-0GB-IrzvfF",
        "ruri": "<sip:12@test.okteller.ru>",
        "rtag": "rB2-0GE-9UAM"
      },
      {
        "participantid": "e846809b-0180-4b7a-aebb-7cd30a921f58",
        "callid": "rB2-0GE-Wix6va-01-823279851@192.168.0.146",
        "state": "active"
        "luri": "<sip:conf-9@test.okteller.ru>",
        "ltag": "rCF-0GB-YGKQhJ",
        "ruri": "<sip:13@test.okteller.ru>",
        "rtag": "rB2-0GE-CIa0"
      }
    ]
  }
]

Получение информации об участнике конференции (get_participant)

Возвращает информацию об указанном участнике активной конференции, обнаруживая ее по идентификатору (idconf). Идентификатор конференции можно достать в том числе по диалогу с конференцией методом get_conference.

Пример запроса

[
  "get_participant",
  {
    "qid": 0.1234,
    "idconf": "rCF-0GB-QKZ1gz",
    "participantid": "dcdd6e3e-0180-4bdb-abe3-7cd30a921f58",
  }
]

Пример ответа

[
  "get_participant_result",
  {
    "qid": 0.1234,
    "result": "ok",
    "data": {
      "participantid": "e846809b-0180-4b7a-aebb-7cd30a921f58",
      "callid": "rB2-0GE-Wix6va-01-823279851@192.168.0.146",
      "state": "active",
      "luri": "sip:conf-9@test.okteller.ru",
      "ruri": "sip:13@test.okteller.ru",
      "ltag": "rCF-0GB-YGKQhJ",
      "rtag": "rB2-0GE-CIa0"
    }
  }
]

Получение топологии конференции (get_topology)

Возвращает текущую топологию конференции, обнаруживая ее по идентификатору (idconf). Идентификатор конференции можно достать в том числе по диалогу с конференцией методом get_conference.

По умолчанию конференция всегда имеет топологию "все всех слышат". Это правило в выдаче всегда расположено первым. Далее следуют все исключения: кто, кого и флаг выключения.

Пример запроса

[
  "get_topology",
  {
    "qid": 0.1234,
    "idconf": "rCF-0GB-QKZ1gz"
  }
]

Пример ответа

[
  "get_topology_result",
  {
    "qid": 0.1234,
    "result": "ok",
    "data": [
      {
        "enabled": true,
        "from": "*",
        "to": "*"
      },
      {
        "enabled": false,
        "from": "e846809b-0180-4b7a-aebb-7cd30a921f58",
        "to": "2919aaa2-0180-4b7a-d155-7cd30a921f58"
      }
    ]
  }
]

Изменение топологии конференции (set_topology)

Применяет модификатор к текущей топологии конференции, обнаруживая ее по идентификатору (idconf). Идентификатор конференции можно достать в том числе по диалогу с конференцией методом get_conference.

Пример запроса

[
  "set_topology",
  {
    "qid": 0.1234,
    "idconf": "rCF-0GB-QKZ1gz",
    "setup": [
      {
        "from": "e846809b-0180-4b7a-aebb-7cd30a921f58",
        "to": "*",
        "enabled": false
      },
      {
        "from": "e846809b-0180-4b7a-aebb-7cd30a921f58",
        "to": "2919aaa2-0180-4b7a-d155-7cd30a921f58",
        "enabled": true
      },
    ]
  }
]

Пример ответа

[
  "set_topology_result",
  {
    "qid": 0.1234,
    "result": "ok",
    "confid": "rCF-0GB-KbQYEI"
  }
]

Отправка DTMF-символа в одну из сторон диалога (send_dtmf)

Реализует отправку DTMF символов в указанное плечо указанного диалога. Поддерживается отправка отдельных символов и их последовательностей. Ответ на запрос поступает сразу, но в плече возникает очередь отправки отдельных символов. Та же очередь используется при поступлении нескольких запросов.

Позволяет задавать последовательность DTMF символов, включающую символы ' и ,. Каждый такой символ обеспечивают паузу в 1 секунду в наборе DTMF.

Отправка может быть произведена в формате SIP-INFO или RFC2833.

Диалог должен существовать.

По умолчанию отправка производится в сторону указанного плеча. Если значение параметра opposite = true, отправка производится в сторону, противоположную указанной.

Аналог REST-API метода SEND_DTMF /rest/v1/uc/calls/:id

Пример запроса

[
  "send_dtmf",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
    "opposite": true,
    "proto": "sipinfo",
    "dtmf": "2"
  }
]

Возможные значения параметра proto:

rfc2833 - значение по умолчанию. Отправка производится в RTP трафике.
sipinfo - отправка производится посредством SIP-сообщения INFO.
любое другое значение - rfc2833.

Пример ответа

[
  "send_dtmf_result",
  {
    "qid": 123,
    "result": "ok",
    "dialogid": "rDlg-002-911Jnh"
  }
]

Включение/выключение распознавания речи абонента (start_asr/stop_asr)

Производит поиск диалога, определяет плечо и отправляет команду на запуск процесса записи и потокового стенографирования. Топология разговора выстраивается таким образом, чтобы в запись попадала лишь речь целевого плеча диалога.

Диалог должен существовать и быть в состоянии разговора. По умолчанию производится стенографирование указанного плеча. Если значение параметра opposite = true, то выбор плеча инвертируется.

Параметр layer опциональный. Предоставляет возможность создавать разные слои в одном и том же диалоге. Такие слои пишутся и распознаются независимо друг от друга. Также дает возможность останавливать предыдущее и сразу же запускать новое распознавание, пока еще не перестали поступать события по предыдущему - для того, чтобы разводить события, например, при стенографировании заполнения данными различных полей карточки разговора. При указании того же самого значения, предыдущая сессия автоматически завершится, и вместо нее начнется новая.

Режим работает при установленной и настроенной подсистеме стенографирования речи (мастер-домен, settings.record_asr_options)

Аналог REST-API метода SETUP_ASR /rest/v1/uc/calls/:id

Пример запроса

[
  "start_asr",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
    "opposite": false,
    "layer": "abcdefg",
    "notify": true
  }
]

Параметр notify указывает на необходимость отправлять события. По умолчанию true - отправлять события по мере появления изменений в стенограмме. Если false - события частичного распознавания отправляться не будут. Результат в этом случае можно забрать в ответе при отключении распознавания с параметром result_text=true.

Для целей распознавания активируется запись указанного плеча, и с запаздыванием около 2 секунд производится отправка предварительных результатов. Отправка событий с предварительными результатами происходит в то же самое подключение.

В ответе возвращаются:

dialogid - идентификатор обнаруженного диалога,
layer - назначенный слой,
eid - сгенерированное UUID значение для привязки событий к разным близко расположенным сессиям.

Пример ответа

[
  "start_asr_result",
  {
    "qid": 123,
    "result": "ok",
    "dialogid": "rDlg-002-911Jnh",
    "layer":"abcdefg",
    "eid": "12341234-1234-1234-1234-123412341234"
  }
]

При выборе режима с уведомлением (notify=true), по мере появления результатов распознавания речи будет производиться отправка событий с результатами.

Пример события

[
  "asr_result",
  {
    "dialogid": "rDlg-002-911Jnh",
    "layer": "bbb",
    "eid": "12341234-1234-1234-1234-123412341234",
    "text": "раз два три\r\nчетыре пять шесть"
  }
]

Остановить потоковое распознавание следует с указанием того же самого layer, что указывался при запуске.

Пример запроса

[
  "stop_asr",
  {
    "qid": 1,
    "owner": "sip:sip3@test.okteller.ru",
    "idconn": "94f2ee21-0678-66bd-0715-9f00000003ee.1656420816464",
    "idcall": "2451417359@192.168.0.146",
    "layer":"bbb"
    "result_text": true
  }
]

Параметр result_text опциональный. По умолчанию true - будет ожидать завершения записи и распознавания, до 2-3 секунд, и только потом отправит ответ вместе с итоговым текстом. Если false - ответ моментальный, сразу после отключения записи. При этом в ответе параметр text будет отсутствовать. Добрать результаты после остановки можно с помощью событий, которые продолжат поступать еще некоторое время (около 2-3 секунд).

Пример ответа

[
  "stop_asr_result",
  {
    "qid": 1.234,
    "dialogid": "rDlg-0GE-SyxZRk",
    "layer":"bbb",
    "result": "ok",
    "text":"раз два три\r\nчетыре пять шесть"
  }
]

Включение/выключение записи во время разговора (start_record/stop_record)

Позволяет точечно включить запись разговора в указанном слое. Вне зависимости от того, включена ли запись разговора в соответствии с правилами, имеется ли параллельный процесс записи - указывая уникальное имя для слоя можно получить отдельную запись указанного интервала времени.

Пример запроса

[
  "start_record",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
    "layer": "abcdefg"
  }
]

Пример ответа

[
  "start_record_result",
  {
    "qid": 1.234,
    "dialogid": "rDlg-0GE-SyxZRk",
    "layer":"abcdefg",
    "result": "ok"
  }
]

Пример запроса

[
  "stop_record",
  {
    "qid": 0.1234,
    "owner": "sip:sip2@test.rootdomain.ru",
    "idcall": "4111998404@192.168.0.149",
    "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
    "layer": "bbb"
  }
]

Пример ответа

[
  "stop_record_result",
  {
    "qid": 1.234,
    "dialogid": "rDlg-0GE-SyxZRk",
    "layer":"bbb",
    "result": "ok"
  }
]

Управление метками диалога

Метки диалога - строковые значения, привязанные к конкретным разговорам/диалогам, устанавливаемые через API или сценариями. Метки доступны в любой момент жизненного цикла разговора вплоть до его завершения. Метки сохраняются при переводе звонка и передаются в новый переведенный разговор.

На метках основана привязка к сеансам обслуживания в КЦ, а также механизм post call survey.

Считывание всех меток (get_bindings)

Возвращает все установленные метки указанного диалога

Пример запроса

[
  "get_bindings",
  {
    "qid": 123,
    "owner":"sip:sip4@test.okteller.ru",
    "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
    "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229"
  }
]

Пример ответа

[
  "get_bindings_result",
  {
    "qid": 123,
    "result": "ok",
    "dialogid": "rDlg-002-911Jnh",
    "labels": ["seance_inner_5dBiGQrcFNFimwK3i7kuO9JrlfF","PCS:a:13","aaa"]
  }
]

Установка (замена) меток на указанные (set_bindings)

Заменяет текущее множество меток указанного диалога на новое множество. Допускается указывать одну метку в виде строки или список меток в виде массива строк в поле 'label'.

Пример запроса

[
  "set_bindings",
  {
    "qid": 123,
    "owner":"sip:sip4@test.okteller.ru",
    "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
    "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229",
    "label": ["aaa","bbb"]
  }
]

Пример ответа

[
  "set_bindings_result",
  {
    "qid": 123,
    "result": "ok",
    "dialogid": "rDlg-002-911Jnh"
  }
]

Добавление указанных меток (add_bindings)

Добавляет указанные метки к указанному диалогу. Допускается указывать одну метку в виде строки или список меток в виде массива строк в поле 'label'.

Пример запроса

[
  "add_bindings",
  {
    "qid": 123,
    "owner":"sip:sip4@test.okteller.ru",
    "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
    "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229",
    "label": ["aaa","bbb"]
  }
]

Пример ответа

[
  "add_bindings_result",
  {
    "qid": 123,
    "result": "ok",
    "dialogid": "rDlg-002-911Jnh"
  }
]

Удаление указанных меток (remove_bindings)

Удаляет указанные метки из указанного диалогу. Допускается указывать одну метку в виде строки или список меток в виде массива строк в поле 'label'.

Пример запроса

[
  "remove_bindings",
  {
    "qid": 123,
    "owner":"sip:sip4@test.okteller.ru",
    "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
    "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229",
    "label": ["aaa","bbb"]
  }
]

Пример ответа

[
  "remove_bindings_result",
  {
    "qid": 123,
    "result": "ok",
    "dialogid": "rDlg-002-911Jnh"
  }
]

Очистка всех меток (clean_bindings)

Очищает указанный диалог от меток.

Пример запроса

[
  "clean_bindings",
  {
    "qid": 123,
    "owner":"sip:sip4@test.okteller.ru",
    "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
    "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229"
  }
]

Пример ответа

[
  "clean_bindings_result",
  {
    "qid": 123,
    "result": "ok",
    "dialogid": "rDlg-002-911Jnh"
  }
]

Проверка наличия метки (contains_bindings)

Заменяет текущее множество меток указанного диалога на новое множество. Допускается указывать одну метку в виде строки.

Пример запроса

[
  "contains_bindings",
  {
    "qid": 123,
    "owner":"sip:sip4@test.okteller.ru",
    "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
    "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229",
    "label": "aaa"
  }
]

Пример ответа

[
  "contains_bindings_result",
  {
    "qid": 123,
    "result": "ok",
    "contains": true,
    "dialogid": "rDlg-002-911Jnh"
  }
]

Установка Post Call Survey (setup_post_call_survey)

Post Call Survey - функция перевода при отбое. Если один абонент диалога кладет трубку, а на другого назначена функция Post Call Survey, то вместо отбоя его плечо получает REFER на установленный номер. Как правило это номер сценария оценки уровня обслуживания.

Размещает метку диалога специального формата. На основании метки работает логика роли B2B, обслуживающей диалог.

Диалог должен существовать.

По умолчанию привязка осуществляется к указанному плечу. То есть функция перевода активируется в его отношении, если оппонент положил трубку. Если значение параметра opposite = true, привязка производится к противоположному плечу.

Дополнительная информация:

PCS устанавливается меткой звонка со специальным форматом.
Установка "to"="" стирает ранее установленный PCS.
Установка нового PCS методом setup_post_call_survey затирает все предыдущие.
PCS, как и все прочие метки, наследуются при переводах.
PCS автоматически удаляется при применении и далее не наследуется.
PCS не применяется, если вызов был переведен, и тогда метка наследуется дальше.
Формат устанавливаемой метки методом setup_post_call_survey для режима 'sticky=true' (по умолчанию): PCS:aor:ToNumber:AOR, где AOR - запись вида 'user@domain'. Такой PCS наследуется, и будет применен в одном из будущих диалогов только в отношении плеча, RemoteURI которого эквивалентен AOR в метке PCS. В свою очередь AOR определяется в момент установки метки PCS из RemoteURI одного из плеч на основании значения флага 'opposite' и указанного 'idcall'.
Формат устанавливаемой метки методом setup_post_call_survey для режима 'sticky=false': PCS:x:ToNumber:IdCall для opposite=true, PCS:y:ToNumber:IdCall для opposite=false. Такой PCS несмотря на наследование не применяется после переводов, поскольку указанный в PCS метке IdCall уникален и имеет отношение только к плечу конкретного диалога, завершившегося при переводе.
Формат PCS:a:ToNumber и PCS:b:ToNumber также поддерживаются, и после наследования при переводе не теряют действия. a и b - это указатели плеч (инициатор и вызываемый).

Пример запроса

[
  "setup_post_call_survey",
  {
    "qid": 123,
    "owner":"sip:sip4@test.okteller.ru",
    "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
    "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229",
    "opposite": true,
    "sticky": true,
    "to": "13"
  }
]

Пример ответа

[
  "setup_post_call_survey_result",
  {
    "qid": 123,
    "result": "ok",
    "dialogid": "rDlg-002-911Jnh"
  }
]

Концепция интеграции с внешней системой и продуктовым слоем

В совокупности с

событиями класса ccsevents,
событиями класса ivrevents,
компонентом ivr-сценария Внешнее управление через API,
websocket-интерфейсом модуля ivrapi позволяет производить интеграцию c внешней системой управления коллцентром.
К каждому домену может быть подключен свой экземпляр внешней системы управления X.
Операторами считаются sip-пользователи домена платформы Era, к которому подключен экземпляр X или различные системы, выполняющие функцию управления.
Все звонки поступают и обрабатываются в Era.
Внешняя с информируется обо всех звонках в соответствующем домене Era. X ведет их учет, предоставляет пользователям статистику, отслеживает занятость операторов.
X управляет звонками пользователей из клиентского приложения с помощью интерфейса Era CallManager.
В момент, когда звонки маршрутизируются в сценарий IVR, а там попадают в компонент "внешнее управление", Era информирует об этом X. Покидая этот компонент по любой причине Era также информирует X.
Во время нахождения в компоненте "внешнее управление" абонент обслуживается логикой сценариев X. Для Era все такие звонки равнозначны, а X удерживает их в своих очередях.
Во время обслуживания абонентов в X, сценарии X управляют медиа-содержанием с помощью команд, компонент "внешнее управление" Era исполняет эти команды, исполняя код компонентов: воспроизведение, запись, перевод и т.д.
Обмен файлами производится через HTTP интерфейс с проверкой хеша (предположительно X размещает и скачивает файлы с Era, но возможно и наоборот)
В случае отсутствия связи с X при входе сценария Era в компонент "внешнее управление", производится моментальный выход по неудачной ветке 1.
В случае потери связи с X во время работы компонента "внешнее управление", Era не предпринимает никаких действий в течение N пингов, а по их истечении производит выход по неудачной ветке 2.
В случае неудач по доступу к файлам взаимодействие не прекращается.
Звонки в Era могут собираться в виртуальные очереди, чтобы не перегружать X.
Звонки в Era могут маршрутизироваться и обслуживаться минуя X, в том числе с использованием call-waiting и очередей.
Любой запрос может завершиться удачным ответом, неудачным ответом, либо не получить ответ. Логика интеграции с обеих сторон учитывает эти варианты.

Внешней системе X также доступны API (HTTP REST и Websocket rest) модели данных, которой она может пользоваться как для собственных нужд, так и для целей более глубокой интеграции. В дополнении к ним полезна API Websocket subscr.

Технологические аспекты:

TCP соединение между X и Era. Era подсоединяется к Era.
Асинхронный дуплексный протокол на базе WebSocket.
Каждый из узлов может отправлять друг другу короткие сообщения в формате JSON, содержащие идентификатор, название и параметры.
Каждое сообщение является либо событием/асинхронной командой, либо запросом, либо ответом. Запрос и ответ имеют одинаковый идентификатор. Название в ответе незначимо.
X цепляется к одному из веб-серверов Era, при потере связи X автоматически переподсоединяется к тому же или любому другому веб-серверу Era.
Точка подключения к Era имеет HTTP путь, содержащий GUID, определяющийся в сущности integration_point в домене Era с разрешением на подписки.
В рамках дуплексного асинхронного протокола выделяются следующие группы команд:
- Настройка подключения (setup)
- Пинг-понг (ping)
- Подписка на события (subscr)
- Обмен информацией о звонках (сеансах, соединениях) (события callevents и/или ccsevents)
- Обмен информацией об операторах/sip-пользователях (rest)
- Управление звонками пользователей (ccs)
- Управления медиа режимами в IVR (ivrapi)
В рамках протокола обмена файлами выделяется группа:
- CRUD файлов с хешами (ivrapi, http /rest/v1/fs).

Ссылки

Управление звонками через REST-API
Компонент 'Операция' сценариев для управления звонками.