enВойти в Senler

API SDK

Что это

@senlerio/api — типизированный клиент публичного API Senler AI. Он генерируется из OpenAPI-спецификации и предоставляет класс AiSenlerClient, модели ответов и отдельные группы методов, например client.projects, client.agents и client.apps.

SDK предназначен прежде всего для серверных интеграций. Он также работает в окружении с глобальным fetch, но произвольный внешний сайт не сможет обращаться к production API, если его origin не разрешён политикой CORS. Проектный API-ключ и Client Secret нельзя помещать в браузерный код.

Установка

Установите текущую опубликованную версию из GitHub с зафиксированным тегом:

npm install github:SenlerBot/Senler-io-sdk#v0.8.0

Пакет требует Node.js 18+ и содержит TypeScript-декларации. Фиксированный тег нужен, чтобы новая генерация SDK не изменила контракт во время следующей установки зависимостей.

Авторизация

В accessToken передаётся только значение токена, без префикса Bearer. SDK сам добавляет заголовок Authorization: Bearer <token> ко всем запросам.

Поддерживаются два источника токена:

  • проектный API-ключ формата senler_sk_... — для интеграции с одним проектом;
  • OAuth access token приложения — для доступа, который пользователь выдал через OAuth.

Доступные методы определяются областью и правами токена. Пользовательский OAuth-токен дополнительно ограничен актуальными правами пользователя в целевом проекте или developer-приложении.

Первый запрос

Пример для проектного API-ключа или проектного OAuth-токена:

import { AiSenlerClient } from "@senlerio/api";

const client = new AiSenlerClient({
  accessToken: process.env.SENLER_API_TOKEN!,
});

const currentProject = await client.projects.getMe();

const agents = await client.agents.agentsList({
  projectId: currentProject.project.id,
  limit: 20,
});

Внешней интеграции не нужен X-Session-Id: этот заголовок относится к сессии кабинета и не входит в параметры сгенерированных методов SDK.

Методы и типы

Группа клиента соответствует разделу API, а метод — операции из публичной OpenAPI-спецификации. Например:

  • client.projects — проекты;
  • client.agents — агенты;
  • client.dialogsMessaging — сообщения в диалогах;
  • client.apps — developer-приложения;
  • client.appDocumentation — документация developer-приложений.

Это примеры, а не полный каталог. Актуальные группы и сигнатуры доступны в TypeScript-подсказках установленной версии SDK, а назначение endpoint, обязательные параметры и права — в справочнике API.

Параметры метода передаются одним объектом в camelCase. SDK сам преобразует имена полей в формат JSON API и преобразует ответ в типизированную модель. Например, idempotencyKey отправляется как idempotency_key. Если обязательный параметр пропущен, TypeScript сообщает об этом при сборке, а runtime-проверка выбрасывает RequiredError.

Для чтения значений переменных лида используйте client.leadVariables.leadVariablesGetValues2. Поиск лидов использует курсорную пагинацию: для первой страницы не передавайте cursor. При отправке и редактировании сообщений указывайте формат текста, чтобы разметка не превратилась в буквальные символы.

Настройки developer-приложения обновляются отдельными методами: client.apps.updateGeneralSettings для названия, описания и сайта, client.apps.updateToolsSettings для инструментов агента и client.apps.updateEmbeddedPageSettings для встроенной страницы. Каждый метод принимает только поля своего раздела, поэтому изменение одной формы не перезаписывает соседние настройки.

В объектах доступных моделей SDK поле supportedServerBindingModes содержит режимы MCP, совместимые с моделью и её активными подключениями к провайдерам. В исходном JSON-ответе API оно называется supported_server_binding_modes. Используйте поле установленного SDK при выборе модели для агента, а не фиксированный список совместимости на стороне интеграции.

Настройка клиента

Конструктор поддерживает следующие параметры:

  • accessToken — обязательный API-ключ или OAuth access token;
  • baseUrl — адрес API, по умолчанию https://api.senler.io; переопределение обычно нужно только для разработки и тестов;
  • fetchApi — собственная реализация fetch, если её требует runtime или тест.

Для долгоживущей интеграции настройте обновление OAuth-токенов и обработку ошибок.

Декораторы и CLI для действий приложения описаны в SDK для NestJS.

Справочные материалы

Предыдущая
Подпись вебхуков
Далее
Формат сообщений