Перейти к основному содержимому

Как пользоваться Swagger

Swagger — интерактивная документация API Salesbot. В ней можно посмотреть доступные методы, параметры запросов и сразу проверить их: из интерфейса Swagger в браузере или скопировав готовый curl / пример запроса в свой код, Postman и другие клиенты.

Где открыть​

ЧтоАдрес
Swagger UIhttps://app.salesbot.tech/docs
OpenAPI-схема (JSON)https://app.salesbot.tech/api/v1/openapi.json

Шаг 1. Получите API-ключ​

  1. Войдите в личный кабинет https://app.salesbot.tech.
  2. В меню слева откройте Мой профиль.
  3. Перейдите на вкладку API ключи.
  4. Нажмите Сгенерировать новый API ключ.
Вкладка «API ключи» и кнопка «Сгенерировать новый API ключ»
  1. Скопируйте значение из поля Ваш API ключ.
Отображение сгенерированного API ключа

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

warning

Если ключ скомпрометирован — нажмите Удалить API ключ и сгенерируйте новый.

Шаг 2. Авторизуйтесь в Swagger​

  1. Откройте https://app.salesbot.tech/docs.
  2. Нажмите кнопку Authorize (замок) вверху справа.
  3. В блоке APIKeyHeader вставьте API-ключ в поле напротив X-API-Key (header).
  4. Нажмите зелёную кнопку Authorize, затем Close.
Окно Available authorizations: ввод X-API-Key и кнопка Authorize

После этого Swagger будет добавлять заголовок X-API-Key ко всем запросам, которые вы запускаете из интерфейса.

Альтернатива: логин и пароль​

В том же окне Authorize можно войти через блок OAuth2PasswordBearer: укажите email и пароль аккаунта Salesbot и нажмите Authorize. Поля client_id и client_secret заполнять не нужно.

Окно Available authorizations: вход по username и password

Для интеграций и скриптов обычно удобнее API-ключ.

Шаг 3. Выполните запрос​

  1. Раскройте нужную группу методов (например, contacts или campaigns).
  2. Выберите метод, например GET /api/v1/campaigns/.
  3. Нажмите Try it out.
  4. При необходимости заполните параметры (фильтры, skip, limit и т.д.).
  5. Нажмите Execute.
  6. Ниже появится код ответа, тело ответа и пример curl.

Если видите 401 / 403 — проверьте, что авторизация активна (замок «закрыт») и ключ скопирован без лишних пробелов.

Какие разделы доступны в API​

Раздел в SwaggerPrefixЧто можно делать
campaigns/api/v1/campaignsСписок и карточка кампании, создание/обновление, постановка контактов в очередь звонков
contacts/api/v1/contactsСписок, получение, создание, обновление, удаление контактов; массовый импорт; постановка в очередь
calls/api/v1/callsСписок звонков и получение звонка по ID
analytics/api/v1/analyticsДетальная аналитика и тренды
contact-creation-integration/api/v1/contact-creation-integrationСоздание контакта по токену интеграции (отдельная схема авторизации)

Подробнее про приём контактов с сайта/CRM: Создание контактов через API.

Пример: список кампаний​

  1. Авторизуйтесь через X-API-Key.
  2. Откройте GET /api/v1/campaigns/.
  3. Нажмите Try it out → Execute.

Эквивалент через curl:

curl -X GET "https://app.salesbot.tech/api/v1/campaigns/" \
  -H "X-API-Key: ВАШ_API_КЛЮЧ"

Пример: создать контакт​

  1. Узнайте campaign_id (из списка кампаний или из интерфейса).
  2. Откройте POST /api/v1/contacts/.
  3. В теле запроса укажите минимум номер телефона и ID кампании.
  4. Execute.

Пример тела:

{
  "campaign_id": 123,
  "phone_number": "+79991234567",
  "contact_data": {
    "name": "Иван"
  }
}

Пример curl:

curl -X POST "https://app.salesbot.tech/api/v1/contacts/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ВАШ_API_КЛЮЧ" \
  -d "{\"campaign_id\": 123, \"phone_number\": \"+79991234567\", \"contact_data\": {\"name\": \"Иван\"}}"

Пример: список звонков по кампании​

curl -X GET "https://app.salesbot.tech/api/v1/calls/?campaign_id=123&limit=20" \
  -H "X-API-Key: ВАШ_API_КЛЮЧ"

В ответе будут статусы, длительность, record_url, external_session_id и другие поля звонка (набор зависит от конкретного звонка).

Как читать схему метода в Swagger​

Для каждого метода полезно смотреть:

  • Parameters — query/path-параметры (фильтры, пагинация).
  • Request body — структура JSON для POST/PUT; можно раскрыть модель и увидеть обязательные поля.
  • Responses — коды и примеры ответов (200, 401, 404, 422).
  • Schemas (внизу страницы) — полные модели данных: контакт, кампания, звонок и т.д.

Ошибка 422 обычно означает, что тело или параметры не соответствуют схеме — сверьте типы полей со схемой в Swagger.

Частые проблемы​

СимптомЧто проверить
401 UnauthorizedКлюч вставлен в X-API-Key, авторизация не сброшена, ключ не удалён в настройках
403 / «Not enough permissions»Объект принадлежит другому аккаунту; используйте ID своих кампаний/контактов
404Неверный ID или объект удалён
422 Validation ErrorОбязательные поля, типы данных, формат телефона/даты
Ключ «светится» в логах сайтаНе вызывайте API из браузера посетителя — проксируйте через свой сервер

Краткий чеклист​

  1. Создать API-ключ в Мой профиль → API ключи.
  2. Открыть https://app.salesbot.tech/docs.
  3. Authorize → вставить ключ в X-API-Key.
  4. Выбрать метод → Try it out → Execute.
  5. Для продакшен-интеграций скопировать готовый curl из ответа Swagger и встроить его в свой сервис.