Перейти к основному содержимому
Версия: v2

Введение

YuChat предоставляет API для интеграции с внешними системами и создания чат-ботов

📄 Актуальная спецификация Open API.

Совместимость с API v1

Для вызова методов Public API v2 из ботов, работающих на v1, дополнительных настроек не требуется.

Единственное исключение — метод getUpdates.

Чтобы использовать его из состава v2, необходимо предварительно переключить бота на получение обновлений в формате v2 с помощью метода setUpdateSettings, указав updateApiVersion = 2.

Создать бота​

  1. Добавьте Бота-помощника aibot@yuchat.ai в ваше Рабочее пространство — он необходим для создания и управления ботами

    • Настройки Рабочего пространства → Пригласить в команду → Пригласить по электронной почте → aibot@yuchat.ai

    • После успешного добавления помощника он должен появиться в разделе ИИ-агенты и боты после списка Каналов

      примечание

      Также после добавления бота-помощника в Рабочее пространство, вы можете взаимодействовать с ним через личные сообщения, используя команды. Напишите боту /help для отображения списка команд.

  2. Напишите Боту-помощнику личным сообщением команду /botcreate <название_бота>

  3. Результатом выполнения команды будет токен, который в дальнейшем необходимо использовать для API-запросов

    Например:

    Запрос:

    /botcreate TestBot

    Результат:

    Создан бот TestBot
    Токен: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJDbzVsR3ItZU51WnU0TjdUSEd2TGVHRGNWVk1oR1JXWlVLTmc0cFBxa2hBIn0.eyJleHAicJ1In0.Cncyq8zILO81Bv_wbNk5b5OuHLP76Vf94TRs2gUAq-Mvq3Qc4ZFNE_eMcpsvYr0q4DOAffpQ

  4. Сохраните токен

к сведению

Бот может отправлять сообщения и выполнять другие действия **только в тех каналах, в которых он является **Участником****

Добавить бота в Канал​

  1. Откройте Канал, в который бот должен отправлять сообщения
  2. Откройте Список участников канала
  3. Нажмите Добавить людей
  4. Найдите и выберите бота в списке
  5. Нажмите Пригласить

💡В боковой панели навигации вы найдёте список доступных API-методов, схемы запросов и ответов, а также примеры использования

к сведению

Базовый URL для API-запросов​

  • Для Cloud версии YuChat используйте базовый URL: https://yuchat.ai/

  • В случае On-Premises установки YuChat (развёрнутой в вашей корпоративной инфраструктуре), используйте соответствующий корпоративный адрес API, например: https://api-domain.company-domain.ru

    Убедитесь, что вы используете API-домен, а не адрес веб-клиента, иначе запросы не будут обработаны

Заголовок авторизации​

Каждый запрос к API должен содержать заголовок

Authorization: Bearer <ваш_токен>

🔑 Некоторые методы (например, отправка сообщений или файлов) требуют указания workspaceId и chatId в теле запроса

Как узнать workspaceId​

  • Откройте веб-версию YuChat и перейдите в нужное Рабочее пространство

  • Откройте Инструменты разработчика, нажав F12

  • Откройте вкладку Elements

  • Найдите HTML-элемент с атрибутом data-workspace-id, который соответствует Рабочему пространству, в котором находятся Каналы, в которые Бот будет отправлять сообщения или выполнять другие действия

    Например : <div data-workspace-id="RRvYqDwAvk"> ...

    к сведению

    Если у вас несколько Рабочих пространств, убедитесь, что вы выбрали элемент, связанный именно с нужным Рабочим пространством

  • Также workspaceId можно увидеть в консоли (вкладка Console) при переключении между Рабочими пространствами — отображается строка вида:
    go to workspaceId: <ID>

Как узнать chatId​

  • Посмотрите адресную строку браузера, когда открыт нужный Канал

    Пример: https://web.yuchat.ai/testws/channels/w:eXtXOs0sT2

    Здесь w:eXtXOs0sT2 — это chatId

Основные концепции​

Название идентификатораОписание
workspaceIdидентификатор рабочего пространства
chatIdидентификатор чатов: каналов, личных переписок, обсуждений (тредов), обсуждений в конференции
membershipIdидентификатор пользователя (аккаунта) в конкретном рабочем пространстве
accountIdидентификатор пользователя (аккаунта)
messageIdидентификатор сообщения

Подсказка: chatId всегда начинается с префикса, который указывает на тип чата: w: - чат канала, p: - личный чат, t: - чат обсуждения

Боты не привязаны к конкретному пользователю, создавшему его. Управление всеми ботами (создание, удаление, обновление токенов) доступно для всех администраторов. В случае утери или компрометации токена, его можно обновить при помощи команды /botnewtoken, при этом старый токен перестает действовать.

Все события, которые может получить бот, имеют ограниченный срок жизни, установленный в 10 минут по умолчанию. По истечении этого срока с момента генерации обновления, оно становится недоступным для получения через Public API.

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

  • Если в теле ошибки, полученной от сервера, содержится is not a correct id, проверьте, что все необходимые поля указаны в запросе, что имена полей указаны верно (chatId - верно, ChatId, chatid, chat_Id - неверно), и что идентификатор чата указан с префиксом :w, :t, :p, :c (w:BDK5NyCqIK - правильно, BDK5NyCqIK - неправильно).
Последнее обновление