Первый запрос к API за 5 минут

Первый запрос к API — это проверка, что ключ работает. Вы отправите запрос в Chatterfy и получите в ответ свою компанию. Дальше по шагам вы найдёте id компании, бота и чата — они нужны почти для всех

Обновлено 2 ноября 2026 г.4 мин

Первый запрос к API — это проверка, что ключ работает. Вы отправите запрос в Chatterfy и получите в ответ свою компанию.

Дальше по шагам вы найдёте id компании, бота и чата — они нужны почти для всех остальных запросов. Программировать не нужно: команды можно скопировать как есть.

Что понадобится

API-ключ. Как его получить — в статье Как получить API-ключ.

Сервисный аккаунт добавлен в Space с ботом.

Одна из программ: Терминал (есть на macOS), PowerShell (есть на Windows) или Postman (бесплатный, для любой системы).

Шаг 1. Проверьте API-ключ

Проверьте API-ключ запросом POST /companies/v1/search с пустым телом {} — он вернёт вашу компанию. Выполните его в Терминале на macOS и Linux, в PowerShell на Windows или в Postman. Вместо ВАШ_КЛЮЧ вставьте свой ключ целиком.

Откройте Терминал, вставьте команду и нажмите Enter.

curl -X POST 'https://api.chatterfy.ai/public-api/companies/v1/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{}'

Откройте PowerShell через меню «Пуск», вставьте команду и нажмите Enter.

$headers = @{ "ApiKey" = "ВАШ_КЛЮЧ" }
Invoke-RestMethod -Method Post `
  -Uri "https://api.chatterfy.ai/public-api/companies/v1/search" `
  -Headers $headers -ContentType "application/json" -Body "{}" |
  ConvertTo-Json -Depth 10

В Postman нажмите New и выберите HTTP.

Слева от строки адреса выберите метод POST. В строку адреса вставьте https://api.chatterfy.ai/public-api/companies/v1/search.

На вкладке Headers добавьте строку: в Key — ApiKey, в Value — ваш ключ.

На вкладке Body выберите raw и формат JSON, впишите {}.

Нажмите Send.

Если всё в порядке, придёт ответ с вашей компанией (часть полей скрыта):

{
  "data": [
    {
      "id": "3f2a9c10-7b4e-4d21-a8f5-61c0e9b2d7a4",
      "name": "My Company",
      "access": {
        "company.read": "all"
      }
    }
  ],
  "pagination": {
    "has_more": false
  }
}

Скопируйте значение id — это id компании. Оно понадобится на следующем шаге.

Пришла ошибка 401?

missing_api_key — не передан заголовок ApiKey. invalid_api_key — ключ скопирован не полностью, с лишним пробелом или уже заменён на новый. Остальные ошибки разобраны в статье Ошибки и лимиты API.

Шаг 2. Найдите id бота

Список ботов компании отдаёт POST /bots/v1/search с company_id в теле. Вместо ID_КОМПАНИИ вставьте id компании из шага 1. Команды для Терминала и PowerShell — на вкладках, в Postman поменяйте адрес и тело.

curl -X POST 'https://api.chatterfy.ai/public-api/bots/v1/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"company_id": "ID_КОМПАНИИ"}'

$headers = @{ "ApiKey" = "ВАШ_КЛЮЧ" }
$body = @{ company_id = "ID_КОМПАНИИ" } | ConvertTo-Json
Invoke-RestMethod -Method Post `
  -Uri "https://api.chatterfy.ai/public-api/bots/v1/search" `
  -Headers $headers -ContentType "application/json" -Body $body |
  ConvertTo-Json -Depth 10

Поменяйте адрес на https://api.chatterfy.ai/public-api/bots/v1/search, а в Body впишите {"company_id": "ID_КОМПАНИИ"}. Нажмите Send.

В ответе — боты, к которым у сервисного аккаунта есть доступ. Найдите нужного по полю name и скопируйте его id — это id бота.

{
  "data": [
    {
      "id": "0b7c2e64-5d1f-4a8e-9c3b-2f6d8e1a4b90",
      "name": "Sales bot",
      "space_id": "5a8d3f71-2e9b-4c06-b1f4-8e7a2c9d0b35",
      "status": "active"
    }
  ],
  "pagination": {
    "has_more": false
  }
}

Пустой список data значит, что сервисный аккаунт не добавлен ни в один Space с ботами. Добавьте его по инструкции Как получить API-ключ.

Шаг 3. Найдите чаты бота

Чаты бота отдаёт POST /chats/v1/search с bot_id в теле. Вместо ID_БОТА вставьте id бота из шага 2. Параметр limit — сколько чатов вернуть.

curl -X POST 'https://api.chatterfy.ai/public-api/chats/v1/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"bot_id": "ID_БОТА", "limit": 5}'

$headers = @{ "ApiKey" = "ВАШ_КЛЮЧ" }
$body = @{ bot_id = "ID_БОТА"; limit = 5 } | ConvertTo-Json
Invoke-RestMethod -Method Post `
  -Uri "https://api.chatterfy.ai/public-api/chats/v1/search" `
  -Headers $headers -ContentType "application/json" -Body $body |
  ConvertTo-Json -Depth 10

Адрес — https://api.chatterfy.ai/public-api/chats/v1/search, в Body — {"bot_id": "ID_БОТА", "limit": 5}.

Придут пять чатов с самой свежей перепиской. У каждого есть id — это id чата, имя клиента в name, статус в status и последнее сообщение в last_message (часть полей скрыта):

{
  "data": [
    {
      "id": "9d4e1b27-3c8a-4f6e-b2d1-7a5c0e8f3b62",
      "bot_id": "0b7c2e64-5d1f-4a8e-9c3b-2f6d8e1a4b90",
      "name": "Анна",
      "username": "anna_k",
      "status": "manual",
      "tags": [],
      "last_message": {
        "content": "Здравствуйте! Сколько стоит доставка?",
        "sender_type": "incoming"
      },
      "created_at": "2026-10-28T09:15:42Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "..."
  }
}

has_more: true значит, что чатов больше, чем пришло. Как получить следующие страницы — в статье Как получить чаты и сообщения через API.

Шаг 4. Прочитайте переписку чата

Сообщения чата отдаёт POST /messages/v1/search с chat_id в теле. Вместо ID_ЧАТА вставьте id чата из шага 3. order: desc — сначала новые сообщения.

curl -X POST 'https://api.chatterfy.ai/public-api/messages/v1/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"chat_id": "ID_ЧАТА", "limit": 10, "order": "desc"}'

$headers = @{ "ApiKey" = "ВАШ_КЛЮЧ" }
$body = @{ chat_id = "ID_ЧАТА"; limit = 10; order = "desc" } | ConvertTo-Json
Invoke-RestMethod -Method Post `
  -Uri "https://api.chatterfy.ai/public-api/messages/v1/search" `
  -Headers $headers -ContentType "application/json" -Body $body |
  ConvertTo-Json -Depth 10

Адрес — https://api.chatterfy.ai/public-api/messages/v1/search, в Body — {"chat_id": "ID_ЧАТА", "limit": 10, "order": "desc"}.

Придут 10 последних сообщений чата. В content — текст, в sender_type — кто написал: incoming — клиент, outcoming — ваша сторона.

Сохраните id

Запишите id компании, бота и чата в заметку. Они не меняются, а в следующих статьях вы будете подставлять их в запросы.

Как читать ответ API

Что вы видите	Что это значит
Данные без поля `error`	Запрос выполнен
`data` и `pagination`	Это список. Записи лежат в `data`, сведения о следующей странице — в `pagination`
`error` с полями `code`, `message`, `request_id`	Ошибка. `code` — короткое название, `message` — объяснение, `request_id` — номер запроса для поддержки
Заголовок `X-RateLimit-Remaining`	Сколько запросов ещё можно сделать в текущую минуту