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

Доступ к API

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

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

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

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

curl -u adm@domain.com:password https://{domain}.webim.ru/api/v1/{subj}

Все данные возвращаются в кодировке 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\":\"8cdb288\",\"content_type\":\"text\",\"filename\":\"v.txt\"}",
      "operator_id": 123
    },
    {
      "created_at": "2012-04-04T09:14:57Z",
      "kind":"file_visitor",
      "data":"{\"guid\":\"81f0488\",\"content_type\":\"text\",\"filename\":\"v.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\":\"1\",\"email\":\"v@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/features/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\":\"8d6df047b2\",\"content_type\":\"text\",\"filename\":\"v.txt\"}",
   "operator_id": 123
  },
  {
   "created_at": "2012-04-04T09:14:57Z",
   "kind": "file_visitor",
   "data": "{\"guid\":\"8135b288\",\"content_type\":\"text\",\"filename\":\"v.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\":\"02\",\"email\":\"p@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: 2017-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 -->

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