First API request in 5 minutes

The first API request is a check that the key works. You will send a request to Chatterfy and receive your company in the response. Next, step-by-step, you will find the company, bot, and chat IDs — t

Updated November 2, 20264 min

The first API request is a check that the key works. You will send a request to Chatterfy and receive your company in the response.

Next, step-by-step, you will find the company, bot, and chat IDs — they are needed for almost all other requests. You don't need to program: the commands can be copied as is.

What you will need

API key. How to get it — in the article How to get an API key.

Service account added to the Space with the bot.

One of the following programs: Terminal (available on macOS), PowerShell (available on Windows), or Postman (free, for any system).

Step 1. Check your API key

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

Open Terminal, paste the command, and press Enter.

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

Open PowerShell from the Start menu, paste the command, and press 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

In Postman, click New and select HTTP.

To the left of the address bar, select the POST method. In the address bar, paste https://api.chatterfy.ai/public-api/companies/v1/search.

On the Headers tab, add a row: in Key — ApiKey, in Value — your key.

On the Body tab, select raw and the JSON format, enter {}.

Click Send.

If everything is in order, you will receive a response with your company (some fields are hidden):

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

Copy the id value — this is the company ID. You will need it in the next step.

Got a 401 error?

missing_api_key — the ApiKey header was not passed. invalid_api_key — the key was not copied completely, contains an extra space, or has already been replaced with a new one. Other errors are explained in the article API Errors and Limits.

Step 2. Find the bot 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.

The response contains the bots that the service account has access to. Find the one you need using the name field and copy its id — this is the bot id.

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

An empty data list means the service account is not added to any Space with bots. Add it following the instructions How to get an API key.

Step 3. Find bot chats

Чаты бота отдаёт 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}.

You will receive five chats with the most recent correspondence. Each has an id — this is the chat id, client name in name, status in status, and the last message in last_message (some fields are hidden):

{
  "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 means there are more chats than returned. How to get the next pages — in the article How to get chats and messages via API.

Step 4. Read chat correspondence

Сообщения чата отдаёт 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"}.

You will receive the 10 latest chat messages. content contains the text, sender_type shows who wrote: incoming — client, outcoming — your side.

Save the id

Save the company, bot, and chat IDs in a note. They do not change, and you will use them in requests in upcoming articles.

How to read an API response

What you see	What this means
Data without an `error` field	Request successful
`data` and `pagination`	This is a list. Entries are in `data`, information about the next page is in `pagination`
`error` with fields `code`, `message`, `request_id`	Error. `code` is a short name, `message` is an explanation, `request_id` is the request number for support
Header `X-RateLimit-Remaining`	How many requests can still be made in the current minute