PostMessage API

Лицензия

API доступно только при наличии модуля «IQChannels – GUI. Agent_Widget»

Описание

PostMessage API позволяет встраивать интерфейс оператора в виде iFrame в другие системы, например в CRM или ДБО.

Все сообщения должны отправляться как JSON-объекты. Type сообщения определяет содержание.

Инициализация чата

Для инициализации чата в окне CRM необходимо добавить базовый код встраивания и при необходимости передать инициализационные параметры.

...
    <style>
        /* стили для изменения размера iframe */
        iframe {
            border: 0;
            width: 50%;
            float: right;
            height: 100%;
        }
    </style>
...
    <!-- Код iFrame для встраивания на страницу -->
    <iframe src="https://iqchannels.iqstore.ru/" width="100%" height="700" id="iQChannels"></iframe>
...
    <!-- скрипт для работы с чатом -->
    <script>
        // с данным режимом сразу будет открываться окно диалога с клиентом при переходе на страницу.
        window.onload = function () {
            initChat();
        }  
        function initChat(){
            var myIframe = document.getElementById("iQChannels");
            if (myIframe){
                myIframe.contentWindow.postMessage({
                    "Type": "initChat",
                    "InitChat": {
                        "HideTicketList": true, // Скрытие списка обращений в левой части окна чата
                        "HideClientCard": true, // Скрытие карточки клиента в правой части окна чата при открытом обращении
                        "HideNavigation": true  // Скрытие навигационного меню чата
                      }
                }, '*');
            }
        }
    </script>
...

Сообщения к iQChannels

Сообщения, которые можно отправлять фрейму с iQChannels.

Написать клиенту

Открывает в IQChannels модальное окно с поиском чата по имени клиента.

{
    "Type": "write_to_client",
    "WriteToClient": {
        "Search": "Строка для поиска клиента по имени, ИНН, ID в ДБО"
    }
}

Открыть чат с клиентом

Открывает в IQChannels последний диалог с клиентом по одному из указанных параметров:

• TicketId — идентификатор диалога, который необходимо открыть в IQChannels.
• CrmClientId — идентификатор клиента в CRM, по которому будет найден клиент и открыто его последнее обращение в IQChannels.
• ClientId — идентификатор клиента в iQChannels, по которому будет найден клиент и открыто его последнее обращение в IQChannels.

Если клиент или диалог не будет найден, iQChannels отобразит сообщение об ошибке. Пример сообщения об ошибке — «Клиент с идентификатором CrmClientId = 2' не найден».

{
    "Type": "open_iframe_ticket",
    "OpenTicket": {
        "ClientId": 1, // id клиента в iQChannels
        "CrmClientId": 2, // id клиента в CRM
        "TicketId": 3 // id тикета (обращения)
    }
}

Сообщения от iQChannels

Сообщения, которые отправляет фрейм с iQChannels в сторону родительской страницы.

Инбокс изменился

Отправляет в родительскую страницу событие с изменением счетчиков инбокса.

{
    "Type": "inbox_changed",
    "InboxChanged": {
        "TotalOpenThreads": 3,   // Количество открытых тредов в инбоксе.
        "TotalUnreadMessages": 7 // Количество непрочитанных сообщений во всех тредах.
    }
}

Открыть карточку клиента (при щелчке на ссылку)

Отправляет в родительскую страницу запрос на открытие карточки клиента по кнопке «Открыть в CRM» в разделе «Действия» текущего обращения.

Если в карточке клиента есть CRMURL, тогда в него дополнительно добавляются два параметра:

• iqchannels_client_id — идентификатор клиента в iQChannels.
• iqchannels_ticket_id — идентификатор обращения в iQChannels.

{
    "Type": "open_client",
    "OpenClient": {
        // URL клиента в CRM, который IQChannels получил от ДБО с дополнительными параметрами iqchannels_client_id и iqchannels_ticket_id.
        "URL": "http://crm/customers/?param=value&iqchannels_client_id=21&iqchannels_ticket_id=412",
        "TicketId": 412,
        "Client": {
            "Id": 21, // id клиента в IQChannels
            "Name": "Кинг Мартин",
            "CRMClientId": "00234",
            "Details": {
                "ClientId": 21,
                "CRMURL": "http://crm/client-id",
                "FirstName": "Мартин",
                "MiddleName": "Лютер",
                "LastName": "Кинг",
                "Sex": "мужской",
                "Birthday": "15.01.1929",
                "Cellphone": "+7 999 123-456",
                "Email": "king@example.com",
                "INN": "150622624993",
                "ExtRef": "XL-283-1238",
                "CardRef": "z8j23yzc1"
            }
        }
    }
}

Открыто обращение в чате

Отправляет в родительскую страницу информацию о том, что оператор открыл обращение.

Событие может быть использовано родительской страницей, например, для открытия карточки клиента при переходе оператора к тикету (обращению) клиента.

Если в карточке клиента есть CRMURL, тогда в него дополнительно добавляются два параметра:

• iqchannels_client_id — идентификатор клиента в iQChannels.
• iqchannels_ticket_id — идентификатор обращения в iQChannels.

{
    "Type": "open_client_from_ticket",
    "OpenClient": {
        // URL клиента в CRM, который IQChannels получил от ДБО с дополнительными параметрами iqchannels_client_id и iqchannels_ticket_id.
        "URL": "http://crm/customers/?param=value&iqchannels_client_id=21&iqchannels_ticket_id=412",
        "TicketId": 412,
        "Client": {
            "Id": 21, // id клиента в IQChannels
            "Name": "Кинг Мартин",
            "CRMClientId": "00234",
            "Details": {
                "ClientId": 21,
                "CRMURL": "http://crm/client-id",
                "FirstName": "Мартин",
                "MiddleName": "Лютер",
                "LastName": "Кинг",
                "Sex": "мужской",
                "Birthday": "15.01.1929",
                "Cellphone": "+7 999 123-456",
                "Email": "king@example.com",
                "INN": "150622624993",
                "ExtRef": "XL-283-1238",
                "CardRef": "z8j23yzc1"
            }
        }
    }
}

Закрыто обращение в чате

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

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

Если в карточке клиента есть CRMURL, тогда в него дополнительно добавляются два параметра:

• iqchannels_client_id — идентификатор клиента в iQChannels.
• iqchannels_ticket_id — идентификатор обращения в iQChannels.

{
    "Type": "close_client_from_ticket",
    "CloseClient": {
        // URL клиента в CRM, который IQChannels получил от ДБО с дополнительными параметрами iqchannels_client_id и iqchannels_ticket_id.
        "URL": "http://crm/customers/?param=value&iqchannels_client_id=21&iqchannels_ticket_id=412",
        "TicketId": 412, 
        "Reason": "ticket_closed", // причина закрытия - "закрыто обращение" или "ticket_assigned" - "Обращение переназначено"
        "Client": {
            "Id": 21, // id клиента в IQChannels
            "Name": "Кинг Мартин",
            "CRMClientId": "00234",
            "Details": {
                "ClientId": 21,
                "CRMURL": "http://crm/client-id",
                "FirstName": "Мартин",
                "MiddleName": "Лютер",
                "LastName": "Кинг",
                "Sex": "мужской",
                "Birthday": "15.01.1929",
                "Cellphone": "+7 999 123-456",
                "Email": "king@example.com",
                "INN": "150622624993",
                "ExtRef": "XL-283-1238",
                "CardRef": "z8j23yzc1"
            }
        }
    }
}

Пример встраивания чата iQChannels в CRM

...
    <style>
        /* стили для изменения размера iframe */
        iframe {
            border: 0;
            width: 50%;
            float: right;
            height: 100%;
        }
    </style>
...
    <!-- Код iFrame для встраивания на страницу -->
    <iframe src="https://iqchannels.iqstore.ru/" width="100%" height="700" id="iQChannels"></iframe>
...
    <!-- скрипт для работы с чатом -->
    <script>
        // с данным режимом сразу будет открываться окно диалога с клиентом при переходе на страницу.
        window.onload = function () {
            openChat(); // чтобы отображалось рабочее место в iqchannels замените openChat() на openDialog()
        }  
        function openChat () { // Если требуется открыть диалог с клиентом
            const clientId = 123;        // id клиента в iQChannels (можно опустить, если передается TicketId или CrmClientId)
            const ticketId = 456;        // id обращения в iQChannels (при наличии)
            const crmClientId = "00234"; // id клиента в CRM (если известен)
            const myIframe = document.getElementById('iQChannels');
            if (myIframe) {
                myIframe.contentWindow.postMessage({
                    'Type': 'open_iframe_ticket',
                    'OpenTicket': {
                        'ClientId': clientId,
                        'TicketId': ticketId,
                        'CrmClientId': crmClientId
                    }
                }, '*');
            }
        }
        function openDialog(){
            var myIframe = document.getElementById("iQChannels");
            if (myIframe){
                myIframe.contentWindow.postMessage({
                    "Type": "write_to_client",
                    "WriteToClient": {
                        "Search": "Строка для поиска клиента по имени, ИНН, ID в ДБО или CRM"
                    }
                }, '*');
            }
        }
    </script>
...   
    <button onclick="openDialog()">Открыть поиск</button>
...

Распространенные ошибки

При работе встраиваемого окна ошибки возвращаются в общем формате ответов iQChannels: поле Error содержит код (Code) и описание (Text). Возможные коды ошибок:

Код	Описание
not_found	Объект не найден
forbidden	Доступ запрещен
unauthorized	Ошибка авторизации
invalid	Ошибка валидации данных
unavailable	Сервис временно недоступен