Пакет @squadus/botsdk содержит HTTP-клиент для осуществления запросов к серверу MySquadus. Используется для разработки ботов, работающих с мессенджером MySquadus.

• Требования
• Установка
• Использование
• Обработка ошибок
• API
• Примеры

Пакет @squadus/botsdk поддерживается Node v14 и выше. Рекомендуется использовать последнюю версию Node.

Для установки @squadus/botsdk выполните команду:

$ npm install @squadus/botsdk

Пакет @squadus/botsdk экспортирует класс MySquadusClient. Для использования нужно создать экземпляр класса, передав в конструктор адрес сервера, токен и разрешенный путь до папки с файлами, которые разрешено прикреплять к сообщениям, а затем вызвать connect.

import { MySquadusClient } from '@squadus/botsdk';

// Создание клиента
const mySquadusClient = new MySquadusClient({
    token: 'a89cDxjI1l',
    server: 'https://im.example.ru/',
    allowedAttachmentsPath: './',
});
await mySquadusClient.connect();

Токен для авторизации можно сгенерировать вручную в веб- или настольном клиенте MySquadus. Для этого необходимо:

1. Войти в учетную запись бота.
2. Перейти на странице «Настройки» в раздел «Токены личного доступа».
3. На открывшейся странице ввести название токена.
4. Установить флажок «Игнорировать двухфакторную аутентификацию».
5. Нажать «Добавить».

Каждый из методов MySquadusClient относится к одной из сущностей:

• room;
• message;
• subscription.

Например, метод sendMessageByRid используется для отправки сообщения. Чтобы его вызвать, необходимо обратиться к нему следующим образом: mySquadusClient.message.sendMessageByRid(), где

• mySquadusClient – инстанс класса MySquadusClient;
• message – сущность, которая содержит в себе методы для совершения операций над комнатами;
• sendMessageByRid – метод для отправки сообщений.

// При известном ID комнаты (канала, команды или прямого диалога с пользователем)
const roomId = '...';

(async () => {
    const result = await mySquadusClient.message.sendMessageByRid({
        msg: 'Hello world!',
        rid: roomId,
    });

    console.log('Message is sent successfully');
})();

Некоторые методы, такие как connect, getSettings, не относятся ни к одной из сущностей. Такие методы можно вызвать напрямую из инстанса класса MySquadusClient.

Так же возможно использовать имя метода в виде строки, чтобы:

• динамически определять вызываемый метод,
• вызывать методы, которые недоступны в используемой версии клиента.

Для этого можно воспользоваться конструкцией: mySquadusClient.restClient.post(im.create, [options]).

Приведенный выше метод может быть использован следующим образом:

(async () => {
    const response = await mySquadusClient.restClient.post('im.create', {
        username: 'new_user',
    });
})();

Ошибки могут возникать по нескольким причинам: пользователь не имеет прав вызывать метод или передан неверный аргумент. В таких случаях возвращенный промис будет отклонен с ошибкой. Необходимо обработать ошибку и использовать содержащуюся в ней информацию, чтобы решить, как приложение, использующее пакет @squadus/botsdk, будет функционировать дальше.

// Import ErrorCode from the package
import { MySquadusClient, ErrorCode } from '@squadus/botsdk';

const { TOKEN, SERVER } = process.env;

const mySquadusClient = new MySquadusClient({
    token: TOKEN || '',
    server: SERVER || '',
});

(async () => {
    try {
        await mySquadusClient.connect();
    } catch (error) {
        if (error === ErrorCode.AuthorizationError) {
            console.log('Authorization error');
        }
    }
})();

В таблице представлены описание методов, их аргументов и возвращаемых ими значений.

Примеры вынесены в отдельный репозиторий: squadus-nodejs-botsdk-examples

Репозиторий с примерами содержит проект с несколькими сценариями использования методов SDK.

Чтобы выполнить примеры, необходимо:

1. Клонировать репозиторий с примерами и установить зависимости: yarn.
2. Внести токен пользователя (бота), от чьего имени будут осуществляться действия, адрес сервера и имя собеседника в файл .env.

SERVER="https://******"
TOKEN="******"
PARTNER_NAME="yourPartnerName"

3. Запустите пример yarn create-direct. Если токен и адрес сервера указаны верно, а также пользователь, с которым создается диалог, существует, в консоль будет выведено сообщение Direct dialog with ${partner_name} was created successfully.

Примеры, которые помогут начать пользоваться @squadus/botsdk:

Будет произведена авторизация.

Будут получены значения настроек с сервера для Accounts_AllowRealNameChange и Accounts_AddGuestsToChats.

Будет создан диалог с собеседником, указанным в файле .env, если такой пользователь существует.

С собеседником, указанным в файле .env, если такой пользователь существует, будет создан диалог. Затем ему будет отправлено сообщение с текстом Hi.

С собеседником, указанным в файле .env, если такой пользователь существует, будет создан диалог. Затем ему будет отправлено изображение example.png из проекта с сообщением Image with logo. Если изображение будет заменено на файл с размером, превышающим допустимый, в консоли появится сообщение об ошибке: File is too large. Также файл должен находиться по пути, который соответствует параметру allowedAttachmentsPath, указанному при создании mySquadusClient.

Собеседник, указанный в файле .env, если такой пользователь существует, будет добавлен в указанный канал. Затем он будет удален из него.

Будет создан приватный канал с именем, указанным в константе PRIVATE_CHANNEL_NAME.

Будет создан открытый канал с именем, указанным в константе PUBLIC_CHANNEL_NAME.

Будет создан открытый канал c пользователем. Затем пользователю будет назначена роль «Модератор».

Будет создан канал, затем имя канала будет изменено.

Ботом будет выполнена подписка на все новые сообщения, а также отдельная подписка на новые личные сообщения от пользователя, имя которого указано в переменной окружения PARTNER_NAME. При получении ботом сообщения «Hi» от пользователя PARTNER_NAME, будет отправлен ответ «Hello». При получении ботом сообщения «Bye» из любого чата, будет отправлен ответ «Bye». Через 20 секунд произойдет отписка от сообщений «Hi», через 40 секунд произойдет отписка от сообщений «Bye».

Ботом будет выполнена подписка на все новые сообщения. После получения ботом сообщения «start», бот отправит ответное сообщение, на реакции которого произойдет подписка ботом. Если поставить реакцию с эмоджи 👏 на это сообщение любым пользователем, в тот же чат бот отправит сообщение, содержащее эмоджи 🌄, если будет реакция с 😀, то сообщение с эмоджи ⚽. После отправки ботом сообщения на реакцию, бот отпишется от реакций на это сообщение.

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

Будет отправлено сообщение, на основании идентификатора которого будет создана цепочка ответов.

Будет отправлено сообщение, на основании идентификатора которого будет создана цепочка ответов. Цепочка ответов будет отмечена как прочитанная пользователем, имя и токен которого указаны в переменных окружения PARTNER_NAME и PARTNER_TOKEN соответственно.

Будет выполнен запрос информации о пользователе по его email, который указан в переменной окружения PARTNER_EMAIL.

Бот создаст личный диалог с пользователем PARTNER_NAME, отправит родительское сообщение и создаст тред. Затем будет выполнена подписка на все новые сообщения через subscription.onMessage(). Если пользователь ответит в этом треде сообщением «Hi», бот получит сообщение из цепочки ответов и отправит «Test passed ✅» в тот же тред. Этот пример проверяет получение сообщений из тредов в уже существующей комнате.

Ботом будет выполнена подписка на все новые сообщения через subscription.onMessage(). После этого бот создаст новый приватный чат, добавит в него пользователя PARTNER_NAME и отправит туда инструкцию. Если пользователь ответит в этом новом чате сообщением «Hi», бот получит сообщение без ручной переподписки на rooms-changed и отправит ответ «Test case is passed ✅». Для чистой проверки удобно использовать пользователя, с которым у бота ещё нет активного чата.

Ботом будет выполнена подписка на все новые сообщения через subscription.onMessage(). После этого бот создаст новый личный диалог с пользователем PARTNER_NAME и отправит туда инструкцию. Если пользователь ответит в этом новом личном диалоге сообщением «Hi», бот получит сообщение без ручной переподписки на rooms-changed и отправит ответ «Test case is passed ✅». Для чистой проверки удобно использовать пользователя, с которым у бота ещё нет активного личного диалога.

Ботом будет выполнена подписка на все новые сообщения через subscription.onMessage(). После этого бот создаст новый личный диалог с пользователем PARTNER_NAME, отправит туда родительское сообщение и создаст новый тред. Если пользователь ответит в этом новом треде сообщением «Hi», бот получит сообщение без ручной переподписки и отправит ответ «Test case is passed ✅» в тот же тред.

Будет произведена авторизация на сервере через узказанный в окружении PROXY_URL.