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

Документация сервиса Webim :: API для разработчиков

Доступ к API

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

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

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

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

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

Все данные возвращаются в кодировке 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" : "Подкатегория",
    "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",
              "message" : "{"guid": "81357dacd9254cd6bc8bde5df047b288", "content_type": "text/plain", "filename": "visitor_ext_api.txt"}",
              "operator_id" : 123
            },
            { "created_at" : "2012-04-04T09:14:57Z",
              "kind" : "file_visitor",
              "message" : "{"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" : "Пока нет, спасибо"
            }
    ],
    "operator_id"123,
       "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",
            "external_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 вида

{
    "created_at" : "2012-04-04T09:14:57Z",
        "id" : 453,
    "category" : "Категория",
    "subcategory" : "Подкатегория",
    "operator": {
        "id": 123,
        "email": "support@webim.ru",
        "name": "Василий"
    },
        "messages" : [
            { "created_at" : "2012-04-04T09:14:57Z",
              "kind" : "for_operator",
              " : "Посетитель открыл окно диалога со страницы ..."
            },
            { "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",
              "message" : "{"guid": "81357dacd9254cd6bc8bde5df047b288", "content_type": "text/plain", "filename": "visitor_ext_api.txt"}",
              "operator_id" : 123
            },
            { "created_at" : "2012-04-04T09:14:57Z",
              "kind" : "file_visitor",
              "message" : "{"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" : "Пока нет, спасибо"
            }
          ],
        "visitor" : { 
             "email" : "support@webim.ru",
            "external_id" : "asdf123",
            "icq" : "123123123",
            "login" : "somelogin",
            "name" : "asdf123",
            "phone" : "+7 (812) 385-53-37",
            "profile_url" : "https://vk.com/id000",
            "site" : "https://webim.ru"
          },
        "visit_session" : {
            "ip" "192.168.1.123",
         },
        "start_page" : {
            "url" "https://webim.ru/help/api",
         }

 

      }

 

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

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

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