Webim Stored Data API 2.0

Базовый URL

Базовый URL — это домен Вашего аккаунта, он зависит от Вашей сетевой конфигурации. Он имеет вид:

https://{hostname}/api/v2/{path}

Где {hostname} — имя хоста, на котором размещается сервер Webim, вида {account}.webim.ru для облачных клиентов и chat.mycompany.com для hosted, {path} — команда API.

На базовый URL отправляются запросы для доступа к Webim Stored Data API 2.0.

Пример готового запроса к Webim Stored Data API 2.0:

https://company.webim.ru/api/v2/operators

Данный запрос должен вернуть список всех операторов.

Для доступа к Webim Stored Data API необходимо пройти авторизацию.

Авторизация, доступ к API

Чтобы получить доступ к Webim Stored Data API Вам необходимо обратиться в техническую поддержку сервиса Webim - support@webim.ru.

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

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

curl -u adm@domain.com:password {base_url}/api/v2/{request}

Где base_url — базовый URL для вашей сетевой конфигурации, request — Ваш запрос к API.

Таким образом, после "curl -u" идёт e-mail пользователя, двоеточие, его пароль, а затем URL запроса.

• Работа API осуществляется только по протоколу HTTPS.
• Все данные возвращаются в кодировке UTF-8.
• Формат времени ISO 8601 и UTC в качестве часового пояса (временной зоны).
• Формат временных интервалов: секунды.

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

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

Если введён неверный пароль или пользователя не существует, возвращается HTTP-код 401.
Если оператор не является администратором или сделано слишком много попыток авторизации, возвращается HTTP-код 403.

Прочие ошибки приходят в формате JSON следующего содержания (с HTTP-кодом 200, если не указано иное):

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

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

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

Path: /operators
Тип запроса: GET
Query-string параметры: не нужны

Запрос возвращает массив всех операторов, привязанных к данному аккаунту Webim.

Описание полей объекта в ответе на запрос:

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

[  
  {
    "status": "online",
    "roles": [
      "admin"
    ],
    "created_at": "2019-04-08T14:10:32Z",
    "email": "mariakolesnikova@webim.ru",
    "full_name": "Мария",
    "id": 192162
  },
  {
    "status": "offline",
    "roles": [
      "operator"
    ],
    "created_at": "2019-07-10T13:17:49Z",
    "email": "ivan_kuznecov@webim.ru",
    "full_name": "Иван К.",
    "id": 193903
  }
]

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

Path: /departments
Тип запроса: GET
Query-string параметры: не нужны

Запрос возвращает массив отделов, привязанных к данному аккаунту Webim.

Описание полей объекта в ответе на запрос:

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

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

Выдача диалогов за период

Path: /chats
Тип запроса: GET
Query-string параметры: since — см. ниже (под примером)

Возвращает массив диалогов за определённый период времени.

Описание полей объекта в ответе на запрос:

Описание полей объекта messages* в ответе за запрос:

*Если тип сообщения keyboard или keyboard_response, то актуально следующее описание полей объекта в ответе на запрос:

{  
   "chats": [  
      {  
         "id": 453,
         "created_at": "2012-04-04T09:14:57Z",
         "category": "Категория",
         "subcategory": "Подкатегория",
         "operator_id": 123,
         "operator_comment": null,
         "rates": [
           {
             "rate": 3,
             "operator_id": 209920,
             "created_at": "2020-05-13T23:57:01Z"
           }
         ],
         "messages": [  
            {  
               "created_at": "2012-04-04T09:14:57Z",
               "kind": "for_operator",
               "message": "Посетитель открыл окно диалога со страницы"
               "id": "24113c657f254698a3e660c64c4ed6b5"
            },
            {  
               "created_at": "2012-04-04T09:14:57Z",
               "kind": "info",
               "message": "Пожалуйста, подождите немного." 
               "id": "f5eee59b508e47f999d8a373d0362c95"
            },
            {  
               "created_at": "2012-04-04T09:14:57Z",
               "kind": "events",
               "message": "Оператор Администратор включился в разговор"
               "id": "324090d75f904a3eb04e54b2fc44094b"
            },
            {  
               "created_at": "2012-04-04T09:14:57Z",
               "kind": "operator_busy",
               "message": "Приносим извинения, оператор отлучился"
               "id": "b1f9c575fc4d4b45b2480a490443a802"
            },
            {  
               "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": [  
            {  
               "state": "queue",
               "operator_id": null,
               "at": "2014-06-10T17:06:22Z",
               "department_id": null
            },
            {  
               "state": "queue",
               "operator_id": 3,
               "at": "2014-06-10T17:06:22Z",
               "department_id": null
            },
            {  
               "state": "chatting",
               "operator_id": 3,
               "at": "2014-06-10T17:06:28Z",
               "department_id": null
            },
            {  
               "state": "queue",
               "operator_id": null,
               "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": "2018-04-04T09:15:57Z"
      },
      {  
         "id": 455,
         "created_at": "2012-04-04T09:16:57Z"
      }
      ...
   ],
   "more_chats_available": false,
   "last_ts": 1429054006896762
}

Выдача диалогов по ID

Path: /chat
Тип запроса: GET
Query-string параметры: id — id диалога

Возвращает объект chat по его уникальному идентификатору.

Пример запроса:

https://company.webim.ru/api/v2/chat?id=1465

где chat?id={chat_id} вид команды API, а {chat_id} (в примере 1465) — уникальный идентификатор чата, информацию о котором необходимо получить.

Описание полей объекта в ответе на запрос:

Описание полей объекта messages* в ответе на запрос:

*Если тип сообщения keyboard или keyboard_responce, то используется следующее описание полей объекта в ответе на запрос:

Описание полей объекта state_history в ответе на запрос:

Описание полей объекта visit_session в ответе на запрос:

Описание полей объекта rates в ответе на запрос:

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

{ 
   "chat":{ 
      "operator_id":181502,
      "start_page":{ 
         "url":"https://webim.ru"
      },
      "subcategory":null,
      "visitor":{ 
         "fields":{ 

         },
         "id":"2c4a44b8948e4985951cb6df99279cdc"
      },
      "id":1465,
      "category":null,
         "operator_comment": null,
         "rates": [
           {
             "rate": 3,
             "operator_id": 209920,
             "created_at": "2020-05-13T23:57:01Z"
           }
         ],
      "visit_session":{ 
         "ip":"31.193.122.170",
         "landing_page":{ 
            "url":"https://company.webim.ru/sample-page.php?redirected=1"
         }
      },
      "created_at":"2019-07-19T14:39:08Z",
      "messages":[ 
         { 
            "created_at":"2019-07-19T14:39:08Z",
            "message":"Пожалуйста, подождите немного, к Вам присоединится оператор...",
            "kind":"info",
            "id":"24113c657f254698a3e660c64c4ed6b5"
         },
         { 
            "created_at":"2019-07-19T14:39:11Z",
            "message":"Привет!",
            "kind":"visitor",
            "id":"f5eee59b508e47f999d8a373d0362c95"
         },
         { 
            "created_at":"2019-07-19T14:39:13Z",
            "message":"Оператор Георгий Б включился в разговор",
            "kind":"info",
            "id":"324090d75f904a3eb04e54b2fc44094b"
         },
         { 
            "created_at":"2019-07-19T14:39:15Z",
            "operator_id":181502,
            "message":"Привет и пока!",
            "kind":"operator",
            "id":"b1f9c575fc4d4b45b2480a490443a802"
         },
         { 
            "created_at":"2019-07-19T14:39:20Z",
            "message":"Оператор закрыл диалог",
            "kind":"info",
            "id":"2970ed561d6a40c1b788001289096acb"
         }
      ],
      "state_history":[ 
         { 
            "state":"queue",
            "operator_id":null,
            "at":"2019-07-19T14:39:08Z",
            "department_id":5
         },
         { 
            "state":"queue",
            "operator_id":181502,
            "at":"2019-07-19T14:39:08Z",
            "department_id":5
         },
         { 
            "state":"chatting",
            "operator_id":181502,
            "at":"2019-07-19T14:39:13Z",
            "department_id":5
         },
         { 
            "state":"closed",
            "operator_id":181502,
            "at":"2019-07-19T14:39:20Z",
            "department_id":5
         }
      ]
   }
}

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

Path: /partner/tariffs
Тип запроса: GET
Query-string параметры: не нужны

Запрос возвращает массив тарифов сервиса Webim.

Описание полей объекта в ответе на запрос:

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

{
  "tariffs": [
    {
      "partner_prices": {
        "per_operator_price": 232.0,
        "base_price": 392.0
      },
      "name": "Начальный",
      "discounts": {},
      "public_prices": {
        "per_operator_price": 290,
        "base_price": 490
      },
      "key": "start",
      "description": "Что Вы получаете:n+ базовый функционал обслуживания посетителей;n+ хранение истории в течение одного месяца;n+ показ до 20 посетителей сайта.nnЧего Вы не получаете:n- работа с отделами;n- показ до 50 посетителей сайта;n- настройка цветов диалога;n- статистика работы операторов;n- хранение истории сообщений без ограничений по времени."
    },
    {
      "partner_prices": {
        "per_operator_price": 632.0,
        "base_price": 1112.0
      },
      "name": "Бизнес",
      "discounts": {},
      "public_prices": {
        "per_operator_price": 790,
        "base_price": 1390
      },
      "key": "bus",
      "description": "Что Вы получаете:n+ базовый функционал обслуживания посетителей;n+ показ до 50 посетителей сайта;n+ работа с отделами;n+ настройка цветов диалога;n+ статистика работы операторов;n+ хранение истории сообщений без ограничений по времени."
    },
    {
      "partner_prices": {
        "per_operator_price": 1992.0,
        "base_price": 1992.0
      },
      "name": "Корпоративный",
      "discounts": {},
      "public_prices": {
        "per_operator_price": 2490,
        "base_price": 2490
      },
      "key": "corp",
      "description": "Что Вы получаете:n+ базовый функционал обслуживания посетителей;n+ показ до 50 посетителей сайта;n+ работа с отделами;n+ настройка цветов диалога;n+ расширенная статистика работы операторов;n+ хранение истории сообщений без ограничений по времени.n+ расширенная информация о посетителе."
    }
  ]
}