Москва +7 499 322 3754 Серебряническая набережная, 29
Санкт-Петербург +7 812 385 5337 Чкаловский проспект, 15
Попробовать демо-версию

Webim API для разработчиков

Доступ к API

Для подключения API к Вашей учетной записи онлайн-консультанта Webim обратитесь, пожалуйста, в поддержку.

Работа API осуществляется только по https

Для доступа используется email и пароль администратора (admin_password).

Осуществляется basic авторизация таким образом:

curl -u adminemail@somedomain.com:admin_password https://{subdomain}.webim.ru/api/v1/{subject}

Все данные возвращаются в кодировке UTF-8

Формат времени ISO8601 и UTC в качестве временной зоны.

Формат временных интервалов: секунды.
При работе через https убедитесь, что ваша библиотека поддерживает SNI

Обработка ошибок

При ошибках авторизации возвращается HTTP код 401.

Прочие ошибки приходят в следующем виде:

{"error":"код-ошибки"}

Возможные типы ошибок

Код ошибки Описание
no-tariff-option Аккаунт не имеет доступа к API
unknown-method Задан неверный тип запроса
unknown-mode Выбран неверный режим запроса (mode)
argument-missing Не хватает аргументов для запроса
unknown Неизвестная ошибка

 

Выдача списка операторов

Адрес запроса:

https://{subdomain}.webim.ru/api/v1/operators

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

[
    {
        created_at: "2013-01-16T09:15:12Z",
        roles: [
            "admin"
        ],
        id: 123,
        full_name: "Администратор",
        email: "a@webim.ru"
    },
    {
        created_at: "2013-05-16T09:15:12Z",
        roles: [
            "operator"
        ],
        id: 124,
        full_name: "Оператор 1",
        email: "o@webim.ru"
    }
]

 

Выдача списка отделов

Адрес запроса:

https://{subdomain}.webim.ru/api/v1/departments

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

[
    {
        "id": 1,
        "name": "Первый отдел",
        "order": 100
    },
    {
        "id": 2,
        "name": "Второй отдел",
        "order": 200
    }
]

 

Выдача истории чатов

Адрес запроса:

https://{subdomain}.webim.ru/api/v2/chats

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

{
    "chats": [
        {
            "id": 453,
            "created_at": "2012-04-04T09:14:57Z",
            "category": "Категория",
            "subcategory": "Подкатегория",
            "operator_id": 123,
            "messages": [
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "for_operator",
                    "message": "Посетитель открыл окно диалога со страницы ..."
                },
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "info",
                    "message": "Пожалуйста, подождите немного, к Вам присоединится оператор.."
                },
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "events",
                    "message": "Оператор Администратор включился в разговор"
                },
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "operator_busy",
                    "message": "Приносим извинения оператор отлучился, Вы могли бы сообщить Ваш телефон и как Вас зовут, мы обязательно с Вами свяжемся"
                },
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "file_operator",
                    "data": "{"guid": "81357dacd9254cd6bc8bde5df047b288", "content_type": "text/plain", "filename": "visitor_ext_api.txt"}",
                    "operator_id": 123
                },
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "file_visitor",
                    "data": "{"guid": "81357dacd9254cd6bc8bde5df047b288", "content_type": "text/plain", "filename": "visitor_ext_api.txt"}",
                    "operator_id": 123
                },
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "operator",
                    "message": "Здравствуйте! Чем я могу Вам помочь?",
                    "operator_id": 123
                },
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "contacts_request",
                    "message": "Введите, пожалуйста, Вашу контактную информацию.",
                    "operator_id": 123
                },
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "contacts",
                    "message": "{"name":"Евгений","phone":"111","email":"support@webim.ru"}"
                },
                {
                    "created_at": "2012-04-04T09:14:57Z",
                    "kind": "visitor",
                    "message": "Пока нет, спасибо"
                }
            ],
            "state_history": [
                {
                    "at": "2014-06-10T17:06:22Z",
                    "department_id": null
                },
                {
                    "at": "2014-06-10T17:06:28Z",
                    "department_id": 1
                },
                {
                    "at": "2014-06-10T20:07:04Z",
                    "department_id": 2
                }
            ],
            "visitor": {
                "fields": {
                    "email": "support@webim.ru",
                    "id": "asdf123",
                    "icq": "123123123",
                    "login": "somelogin",
                    "name": "asdf123",
                    "phone": "+7 (812) 385-53-37",
                    "profile_url": "https://vk.com/id000",
                    "site": "https://webim.ru"
                },
                "id": "4d123f6d7143490d966432ccb24403a4"
            },

            "visit_session": {
                "ip": "192.168.1.123",
                "landing_page": {
                    "url": "https://webim.ru"
                }
            },
            "start_page": {
                "url": "https://webim.ru/help/api"
            }
        },

        {
            "id": 454,
            "created_at": "2012-04-04T09:15:57Z",
            ...
        },

        {
            "id": 455,
            "created_at": "2012-04-04T09:16:57Z",
            ...
        }

    ],

    "more_chats_available": false,
    "last_ts": 1429054006896762
}

В запросе должен быть указан параметр since. В первом запросе передается since=0, в ответе на каждый запрос есть поле last_ts, и в каждом следующем запросе в качестве since должно передаваться значение last_ts из предыдущего.
Таким образом каждый следующий запрос получает в ответ только обновления по отношению к тому, что было получено на все предыдущие запросы.
Один и тот же диалог может быть получен несколько раз, если с момента, когда он был получен первый раз, в нем происходили какие-либо изменения.
В ответ на запрос истории возвращается за раз не более 100 диалогов. Если поле more_chats_available в ответе имеет значение true, это означает, что на сервере остались новые или изменившиеся диалоги, "не поместившиеся" в это ограничение, и следует сделать еще один запрос с новым значением since для их получения (и повторять это до тех пор, пока more_chats_available не примет значение false).

Поле visitor может быть null или содержать поля переданные посетителем и поля переданные согласно https://webim.ru/pro/identification/

Поле visit_session содержит ip посетителя и может содержать поле landing_page.

start_page и landing_page могут быть null.

Типы сообщений используемые в поле kind:

visitor
for_operator
info
operator
events
operator_busy
contacts_request
contacts
file_operator
file_visitor

 

Выдача статистики

Адрес запроса:

https://{subdomain}.webim.ru/api/v1/stats?date=2012-04-20&mode=usage

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

{
    "contacts": 10,
    "missed": 1,
    "chats": 7,
    "offlines": 2,
    "avg_waiting_time": 100
}

 

Адрес запроса:

https://{subdomain}.webim.ru/api/v1/stats?date=2012-04-20&mode=operators

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

[
    {
        "operator_id": 123,
        "online_time": 28800,
        "chating_time": 18000,
        "avg_chating_time": 150,
        "busy_messages": 5,
        "chats": 3
    },
    {
        "operator_id": 124,
        "online_time": 23800,
        "chating_time": 1000,
        "avg_chating_time": 150,
        "busy_messages": 1,
        "chats": 2
    }
]

 

Обработчики событий чата

При начале, завершении , или подключении оператора,  для каждого чата как онлайнового так и оффлайнового мы вызываем сторонние обработчики куда передаем информацию по чату. Настроить обработчики можно в Меню оператора, в разделе Общие настройки -> Интеграция (https://login.webim.ru/webim/operator/settings.php).

Например:

https://user:password@www.company.com/handler?webim_chat_start
https://user:password@www.company.com/handler?webim_chat_assign
https://user:password@www.company.com/handler?webim_chat_close

Передаваемые POST'ом в обработчик параметры chat и в нем JSON вида

{
    "id": 453,
    "created_at": "2012-04-04T09:14:57Z",
    "category": "Категория",
    "subcategory": "Подкатегория",
    "operator_id": 123,
    "messages": [
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "for_operator",
            "message": "Посетитель открыл окно диалога со страницы ..."
        },
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "info",
            "message": "Пожалуйста, подождите немного, к Вам присоединится оператор.."
        },
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "events",
            "message": "Оператор Администратор включился в разговор"
        },
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "operator_busy",
            "message": "Приносим извинения оператор отлучился, Вы могли бы сообщить Ваш телефон и как Вас зовут, мы обязательно с Вами свяжемся"
        },
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "file_operator",
            "data": "{"guid": "81357dacd9254cd6bc8bde5df047b288", "content_type": "text/plain", "filename": "visitor_ext_api.txt"}",
            "operator_id": 123
        },
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "file_visitor",
            "data": "{"guid": "81357dacd9254cd6bc8bde5df047b288", "content_type": "text/plain", "filename": "visitor_ext_api.txt"}",
            "operator_id": 123
        },
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "operator",
            "message": "Здравствуйте! Чем я могу Вам помочь?",
            "operator_id": 123
        },
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "contacts_request",
            "message": "Введите, пожалуйста, Вашу контактную информацию.",
            "operator_id": 123
        },
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "contacts",
            "message": "{"name":"Евгений","phone":"111","email":"support@webim.ru"}"
        },
        {
            "created_at": "2012-04-04T09:14:57Z",
            "kind": "visitor",
            "message": "Пока нет, спасибо"
        }
    ],
    "state_history": [
        {
            "at": "2014-06-10T17:06:22Z",
            "department_id": null
        },
        {
            "at": "2014-06-10T17:06:28Z",
            "department_id": 1
        },
        {
            "at": "2014-06-10T20:07:04Z",
            "department_id": 2
        }
    ],
    "visitor": {
        "fields": {
            "email": "support@webim.ru",
            "id": "asdf123",
            "icq": "123123123",
            "login": "somelogin",
            "name": "asdf123",
            "phone": "+7 (812) 385-53-37",
            "profile_url": "https://vk.com/id000",
            "site": "https://webim.ru"
        },
        "id": "4d123f6d7143490d966432ccb24403a4"
    },
    "visit_session": {
        "ip": "192.168.1.123",
        "landing_page": {
            "url": "https://webim.ru"
        }
    },
    "start_page": {
        "url": "https://webim.ru/help/api"
    }
}

 

Как сделать ссылку кнопкой для старта чата

Для того,чтобы сделать произвольную ссылку кнопкой для старта чата, необходимо этой ссылке добавить два класса - webim_button и webim_basic_button. Пример:

<a href='#' class='webim_button webim_basic_button'>Онлайн-консультант</a>

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

Рассмотрим на примере кода для аккаунта demo.

Необходимо убрать следующий фрагмент кода:

document.write('<a href="#" rel="webim"><img src="' + document.location.protocol + '//demo.webim.ru/webim/button.php" border="0"/></a>');

и получиться должно:

<!-- webim button generation date: 2013-09-18 version: 8.4.0 -->
<script type="text/javascript">
  webim = {
    accountName: "demo",
    domain: "demo.webim.ru"
  };
  (function () {
      var s = document.createElement("script");
      s.type = "text/javascript";
      s.src = document.location.protocol + "//demo.webim.ru/webim/js/button.js";
      document.getElementsByTagName("head")[0].appendChild(s);
  })();
</script>
<!-- /webim button -->

Вернуться к главной странице документации