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. 1. 1. Конечный потребитель API приложений программирует и использует на стороне внешнего приложения, поэтому начало исходящего звонка расценивается как "исходящее" независимо от того, кто дал команду "Позвонить" - внешнее приложение через API приложений или сам человек нажатием кнопки в ДП!!

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

   
   

2. В связи с тем, что такие виды взаимодействия, как 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 приложений предусмотрено, что массовые виды событий должны транслироваться внешнему приложению только в случае потребности со стороны последнего.

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

<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>

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

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

<File Name=”” SourceDir=”” DestinDir=”” Size=”” StartTime=”” Duration=””/>

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