5.1.1. Трансляция событий

Реализуется передачей внешнему приложению XML-пакета с тегом <Event> и совокупностью атрибутов этого тега, детализирующих объект, место возникновения и направление взаимодействия, а также уточняющих момент возникновения и указание как реакции на команду:

  1. Момент возникновения события определяется значением обязательного атрибута Time.
  2. Ключ команды. Если событие должно идти как ответная реакция на команду API приложений (см. Передача команд), несущее результат выполнения (см. ниже), то обязательно присутствует атрибут ID="<ID команды>". Это позволит внешнему приложению точно понять, что данное событие есть ответ на конкретную команду
  3. Объект события означает "то, о чём событие", и определяется значением обязательного атрибута Object. Как правило, возможные объекты определяются возможными видами информационного взаимодействия.
  4. Место возникновения означает область данных, которой касается событие, и определяется значением необязательного атрибута Mode. Как правило, возможные области соответствуют видам типизированных списков в приложении. Если атрибут Mode не указан, это равноценно Mode="MyPersonalInfo".
  5. Направление взаимодействия с контактом ("от тебя как аккаунта", т.е. исходящее, или "для тебя", т.е. входящее) определяется значением необязательного атрибута Initiator.

    1. Initiator=”self” - означает, что действие и последовавшее событие инициировано аккаунтом, от лица которого работает API приложений в данный момент. (даже если исходящий звонок начался с другого устройства!!)Initiator=”incoming” - означает, что событие сигнализирует о действии других аккаунтов/системы.
      1. Конечный потребитель API приложений программирует и использует на стороне внешнего приложения, поэтому начало исходящего звонка расценивается как "исходящее" независимо от того, кто дал команду "Позвонить" - внешнее приложение через API приложений или сам человек нажатием кнопки в ДП!!

        Тег Initiator не указывается для событий изменения контакта и его статуса, т.е. для Object="PersonalInfo" и AgentOnlineStatus" (не имеет смысла, т.к. событие не о взаимодействии в чате).


  1. В связи с тем, что такие виды взаимодействия, как Call, RemoteAccessSession, FileTransfer, Treatment, ServiceRequest, по сути являются процессами (отрезками во времени), имеющими начало, окончание и какие-то стадии, то для уточнения в событии об этом объекте присутствует тег State:

    1. State=”Initialized” - процесс инициирован (начался дозвон, выбирается файл для передачи, обращение создано)
    2. State="Started" - процесс начат (разговор начался, экран УД начал транслироваться, файл стал закачиваться, обращение поступило в компанию)
    3. State="Finished" - процесс завершён (разговор завершен, сеанс УД закрылся, файл загружен, обращение закрыто)

    Итого, у тега Event может быть указано от 2 до 5 атрибутов со значениями.

В связи с тем, что такие виды взаимодействия, как Call, RemoteAccessSession, FileTransfer, Treatment, ServiceRequest, по сути являются процессами (отрезками во времени), имеющими начало, окончание и какие-то стадии, то для уточнения в событии об этом объекте присутствует тег State:

  1. State=”Initialized” - процесс инициирован (начался дозвон, выбирается файл для передачи, обращение создано)
  2. State="Started" - процесс начат (разговор начался, экран УД начал транслироваться, файл стал ��акачиваться, обращение поступило в компанию)
  3. State="Finished" - процесс завершён (разговор завершен, сеанс УД закрылся, файл загружен, обращение закрыто)

Итого, у тега Event может быть указано от 2 до 5 атрибутов со значениями.

Пример события о смене собственного онлайн-статуса:

Смена собственного онлайн-статуса
<Event Time="2019-01-31T12:34:30" Object="AgentOnlineStatus">
<Status>Online</Status>
</Event>

... а вот событие смены статуса пользователя линии поддержки:

Смена статуса пользователя ЛП
<Event Time="2019-01-31T12:34:30" Mode="ServicesClients" Object="AgentOnlineStatus">
	<ClientID>6dd05738-1464-11e3-93b5-7054d21ab6ff</ClientID>
	<UserID>227e9d68-01d8-4006-ad42-d034dcb67818</UserID>
	<CounterpartID>6dd05738-1464-11e3-93b5-7054d21ab6ff</CounterpartID>
	<Status>Away</Status>
</Event>

Пример события о входящем сообщении в ленте чата от коллеги:

Входящее сообщение от коллеги
<Event Time="2019-01-31T12:34:30" Mode="Colleagues" Object="Message" Initiator="Incoming">
	<MessageID>9e3ab298-074d-9f43-827a-323e20ed267f</MessageID>
	<ColleagueID>227e9d68-01d8-4006-ad42-d034dcb67818</ColleagueID>
	<AuthorID>227e9d68-01d8-4006-ad42-d034dcb67818</AuthorID>
	<MessageBody>Привет, дружищеее!!!</MessageBody><Sended></Sended>
</Event>

Пример события об окончании исходящего звонка в чате по линии поддержки, инициированного командой API приложений CallTo:

Событие об окончании исходящего звонка в чате по ЛП
<Event ID="d5d05738-1944-11e3-56b5-7054d21ab6ff" Time="2019-01-31T12:47:28" Mode="ServicesClients" Object="Call" Initiator="Incoming">
	<ClientID>6dd05738-1464-11e3-93b5-7054d21ab6ff</ClientID>
	<CounterpartID>6dd05738-1464-11e3-93b5-7054d21ab6ff</CounterpartID>
	<UserID>227e9d68-01d8-4006-ad42-d034dcb67818</UserID>
	<ServiceID>114c7433-4c28-11e7-80e5-0025904f970f</ServiceID>
	<CallID>cc7cafb6-2e3c-f5d2-502c-f19ee322e58c</CallID>
	<CallFrom>7215fb1e-89b9-4252-befa-45e20cf9bc5b</CallFrom>
	<CallTo>227e9d68-01d8-4006-ad42-d034dcb67818</CallTo>
	<State>Finished</State>
	<StartTime>2019-01-31T17:46:53</StartTime>
	<AcceptTime>2019-01-31T17:46:53</AcceptTime>
	<EndTime>2019-01-31T17:47:30</EndTime>
	<Duration>37</Duration>
	<BillSec>37</BillSec>
	<CallResult>Success</CallResult>
</Event>

Фильтрация событий

Если у текущего аккаунта списки контактов/групповых чатов большие, то возрастает поток событий от них, поступающих в ДП. Т.к. о производительности и функционале внешнего приложения заранее неизвестно (это знает только разработчик того приложения), то в API приложений предусмотрено, что массовые виды событий должны транслироваться внешнему приложению только в случае потребности со стороны последнего.

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

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

Подписка на события определенной категории
<Command [ID=”GUID”] Action=”EventSubscribe” Mode=”место” Object=”объект” [Initiator=”направление”]> </Command>

Если разработчик внешнего приложения нуждается в контроле исполнения команды, то он самостоятельно генерирует GUID и указывает его в качестве идентификатора конкретной команды (атрибут ID) - в таком случае от ДП поступит ответ

Результат исполнения команды на подписку
<CommandResult ID=”GUID, указанный разработчиком” Action=”EventSubscribe” Mode=”место” Object=”объект” [Initiator=”направление”]>
<Result></Result>
[<Error>Описание ошибки по-английски</Error>]
</CommandResult>

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

Отписка от получения событий
<Command [ID=”GUID”] Action=”EventUnSubscribe” Mode=”место” Object=”объект” [Initiator=”направление”]> </Command>

в ответ на команду придёт ответ, аналогичный вышеуказанному


Возможные объекты события

ObjectОписаниеУсловие

Свойства (теги)

Примечание
PersonalInfo




Персональные данные










<Name>

Имя

<SecondaryName>

Отчество

<Surname>

Фамилия

<Birthday>

Дата рождения

<Phone>

Номер телефона

<EMail>

Адрес электронной почты
AgentOnlineStatusОнлайн-статус аккаунта
<Status>
 Возможные значения тега Status
  • “Offline”
  • “Connecting”=Не в сети
  • “Online”=В сети
  • “Away”=Нет на месте
  • “Talking”=Разговариваю
  • “DoNotDisturb”=Не беспокоить
  • “RedirectToExternalPhone”=Переадресация на внешний телефон
  • “BusyForNewRequests”=Занят для новых обращений
Message



Сообщение в ленту чата








<MessageID>

UUID сообщения (не передаётся командой SendMessage)

<AuthorID>UUID автора сообщения
<MessageBody>Тело сообщения
<Sended>Время отправки сообщения
(Mode=”ServicesClients”)<SpecialistID>

UUID НСС

CallСеанс голосовой связи (звонок)
<CallID>UUID факта звонка

<CallFrom>UUID инициатора
<CallTo>UUID встречного абонента
(State>=”Started”)

<StartTime>

Момент начала дозвона
(State>=”CallAccepted”)

<AcceptTime>

Момент взятия трубки собеседником - начало отсчета длительности разговора
(State>=”Finished”)


<EndTime>

Момент завершения голосового сеанса
<CallResult>
 Возможные значения тега CallResult
  • “Success” = успешное завершение разговора
  • “NobodyToAnswer” = Не было свободных специалистов
  • ‘’RingingTimeout” = Превышено время дозвона
  • “RejectedByCallee” = вызываемый(принимающий) отбил вызов
  • “RejectedByCaller” = звонящий отбил вызов
  • “PBXunreachableForMe” = мне не удалось соединиться с АТС
  • “PBXunreachableForTarget” = собеседнику не удалось соединиться с АТС
  • “TargetHaveNoSoundDevices” = у собеседника отсутствуют звуковые устройства
  • “IHaveNoSoundDevices” = у меня отсутствуют звуковые устройства

<Duration>

Общая длительность голосового сеанса ~ (EndTime - StartTime)

<BillSec>

Длительность голосового общения ~ (EndTime - AcceptTime)
(State=”MP3RecordReady”)

<CallRecordLink>

URL-ссылка на файл записи голосового сеанса (формат .mp3)
(State=”SoundQualityAssessment)<Assessment>= 1..5
<Comments> комментарии к оценке (?XML)
RemoteAccessSession


Сеанс удаленного доступа




<SessionID>UUID сеанса УД
<AuthorID>UUID того, кто подключается
(State>=”Started”)<StartTime>Момент начала процесса подключения
<HostCompName>Название ПК в ОС, к которому подключаются
<AdminCompName>Название ПК в ОС, с которого подключаются
<HostIP>IP-адрес к кому подключаются
<AdminIP>IP-адрес того, кто админит
(State>=”Finished”)<EndTime>Момент завершения сеанса УД
<Duration>Длительность сеанса в секундах
<UploadedFiles>
Cписок файлов, скопированных с удаленного ПК
<File Name=”” SourceDir=”” DestinDir=”” Size=”” StartTime=”” Duration=””/>

FileTransfer

(пока не реализовано)

Файл, выложенный в ленту чата
<FileTransferID>UUID транслируемого файла (чтобы не запутаться)
<FileName>Имя файла с расширением
<FileSize>в байтах
(State>=”Finished”)<TransferDuration>в секундах с сервера/на сервер

Treatment

(Mode=”ServicesClients”)

Обращение по линии (поддержки)
<TreatmentID>UUID обращения


(State>=”Appointed)<AppointedSpecialistID>UUID специалиста, который был назначен на обращение


<WaitTime>время ожидания назначения спеца в сек


(State>=”Finished”)<TreatmentDuration>длительность обращения в секундах


(State>=”ServiceQualityAssessment)<Assessment>= 1..5 - оценка по 5-балльной шкале


(State>=”Comments)<Comments>Комментарии (XML?)
ServiceRequestТикет по ЛП (заявка/задача)


Возможные места возникновения события

ModeОписание

Свойства (теги)

Примечание
ServicesClients

Чат с пользователем линии поддержки

(соответствует вкладке "Клиенты")

<ClientID>UUID организации, в которой работает потребитель ЛП
<UserID>UUID пользователя ЛП
<ServiceID>UUID ЛП
Colleagues

Чат с коллегой 

(соответствует вкладке "Коллеги")

<ColleagueID>UUID коллеги
PersonalContacts

Чат с персональным ("Деловым") контактом

(соответствует вкладке "Коллеги")

<PersonalContactID>


<MeetingState>Состояние приглашения
SoftphoneСофтфон <CallTo>Номер встречного абонента
GroupChatsГрупповой чат (конференц-чат)

<GroupChatRoomID>




<MemberID>

От какого участника группового чата пришло событие