REST API

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

Общие сведения

Базовый URL

Все запросы к API Олчат выполняются через базовый URL вашего портала:

https://{ваш-домен}/api/v1/

Формат данных

• Запросы: JSON (Content-Type: application/json).
• Ответы: JSON.
• Кодировка: UTF-8.
• Именование полей: camelCase в запросах и ответах API.

Аутентификация

JWT-токен

Для доступа к API используется JWT-токен (JSON Web Token). Токен передаётся в заголовке Authorization:

Authorization: Bearer {ваш_jwt_токен}

Получение токена

Токен выдаётся при авторизации через приложение Олчат в Битрикс24. Для программного доступа:

1. Пользователь авторизуется в приложении Олчат через интерфейс Битрикс24.
2. Приложение получает токен, привязанный к порталу и пользователю.
3. Токен используется для последующих запросов к API.

Осторожно

Храните токены в безопасном месте. Не передавайте токены по незащищённым каналам и не храните их в открытом виде в коде.

Время жизни токена

Токены имеют ограниченный срок действия. При истечении срока токена необходимо выполнить повторную авторизацию. API вернёт ошибку 401 Unauthorized при использовании истёкшего токена.

Доступные методы

Линии и коннекторы

Метод	Путь	Описание
GET	/lines/	Получить список линий портала
GET	/lines/{id}/	Получить информацию о линии
GET	/connector/status/	Статус подключённых коннекторов

Контакты

Метод	Путь	Описание
GET	/contacts/	Список контактов
GET	/contacts/{id}/	Информация о контакте
GET	/contacts/detail/	Детальная информация о контакте

Чаты и диалоги

Метод	Путь	Описание
GET	/dialogs/	Список диалогов
GET	/groups/	Список групповых чатов

Аккаунт

Метод	Путь	Описание
GET	/account/info/	Информация об аккаунте
GET	/account/status/	Статус аккаунта

Примеры запросов

Получение списка линий

GET /api/v1/lines/ HTTP/1.1
Host: ваш-домен
Authorization: Bearer {токен}

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

{
  "lines": [
    {
      "id": 1,
      "lineNumber": 1,
      "lineName": "Основная линия",
      "connectorName": "olchat_telegram",
      "isActive": true
    }
  ]
}

Получение информации о контакте

GET /api/v1/contacts/detail/?phone=79001234567&connector=olchat_telegram HTTP/1.1
Host: ваш-домен
Authorization: Bearer {токен}

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

{
  "contact": {
    "chatId": "123456789",
    "firstName": "Иван",
    "lastName": "Петров",
    "username": "ivanpetrov",
    "phone": "79001234567",
    "isOnline": false,
    "lastSeen": "2026-03-20T10:30:00Z"
  }
}

Получение статуса коннектора

GET /api/v1/connector/status/?connector=olchat_telegram&lineNumber=1 HTTP/1.1
Host: ваш-домен
Authorization: Bearer {токен}

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

{
  "status": "authorized",
  "connectorName": "olchat_telegram",
  "lineNumber": 1,
  "accountName": "Олчат Support"
}

Коды ответов

Код	Описание
200	Запрос выполнен успешно
400	Некорректный запрос (неверные параметры)
401	Не авторизован (отсутствует или истёк токен)
403	Доступ запрещён (недостаточно прав)
404	Ресурс не найден
429	Превышен лимит запросов
500	Внутренняя ошибка сервера

Формат ошибки

При возникновении ошибки API возвращает JSON с описанием:

{
  "detail": "Описание ошибки"
}

Заметка

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

Ограничения

Лимиты запросов

Для защиты от перегрузки API применяются лимиты на количество запросов:

• Количество запросов ограничено по IP-адресу и токену.
• При превышении лимита API вернёт код 429 Too Many Requests.
• Рекомендуется выполнять не более 10 запросов в секунду.

Общие ограничения

• API доступен только для авторизованных пользователей портала.
• Доступ к данным ограничен порталом текущего пользователя.
• Массовые операции (batch) не поддерживаются через REST API — для автоматизации используйте роботов Битрикс24.

Совет

Для автоматизации типовых сценариев (отправка сообщений, обработка событий) рекомендуется использовать роботов и бизнес-процессы Битрикс24 вместо прямых вызовов API.

Взаимодействие с Битрикс24 API

Олчат использует REST API Битрикс24 для работы с открытыми линиями, CRM и ботами. Приложение работает с правами scope: app, imol, bot.

Основные методы Битрикс24, с которыми взаимодействует Олчат:

Область	Методы
Открытые линии	imconnector.send.messages, imconnector.chat.name.set
CRM	crm.deal.get, crm.contact.get, crm.lead.get
Боты	imbot.message.add, imbot.app.register
SMS	messageservice.sender.add, messageservice.sender.delete

Осторожно

Для вызова методов Битрикс24 через Олчат используются токены приложения. Не пытайтесь вызывать методы Битрикс24 напрямую от имени Олчат — это может привести к ошибкам авторизации.

Рекомендации

• Всегда проверяйте код ответа перед обработкой данных.
• Реализуйте обработку ошибок 401 с повторной авторизацией.
• Кешируйте редко изменяемые данные (список линий, статусы коннекторов) для снижения нагрузки.
• Используйте HTTPS для всех запросов.
• Не храните токены в клиентском коде или логах.