Chato
API

API authentication

Updated October 18, 20263 min read

Your software talks to the Chato API with an API key. It is separate from your browser session. The key starts with chato_sk_ and is sent with every request.

Two kinds of keys

Public API key Company API key
Where to create it CRM → ⋯ → CRM settings → API & webhooks → "New key" Account settings → Company → API key → "Generate key"
Who can create it admins and the owner the owner only
How many keys as many as you need, each with its own name one per company
Access the public API only (/api/v1/public/…), and only with the ticked permissions the whole REST API on behalf of the owner, plus the public API with all permissions
Limit 120 requests per minute per key 100 requests per minute from one IP address

For deals, contacts and tasks, use a public API key. It has limited permissions, a clear "via API" mark in the history and a stable response format. How to use it is described in Public deals API and CRM webhooks.

You need the company API key when your software works with chats and channels: the conversation list, sending messages on behalf of an operator.

Company API key

Open Account settings → Company. In the API key block, click Generate key. Chato shows the key only once, right after it is created. Copy it: you cannot view the key again. Regenerate key issues a new key, and the old one stops working at once. Revoke turns the key off without a replacement.

The same key is available in the amoCRM or Bitrix24 integration settings, on the "Additional" tab.

The company API key gives full access to the company on behalf of the owner. Treat it like a password: keep it in environment variables on your server, not in website code or in a public repository.

The key has no expiry date. It works until it is revoked or regenerated. You cannot create or revoke keys, or set up webhook URLs, with a key: such a request gets 403.

Base URL

https://chato.kz/api/v1

How to send the key

In the Authorization header:

GET https://chato.kz/api/v1/workspaces
Authorization: Bearer chato_sk_...

The public API also accepts the key in the X-Api-Key: chato_sk_... header.

A successful response is always in the data field:

{
  "data": [
    { "id": "cmulak1n90001295a8kf4ruhe", "name": "Baisal Delivery", "role": "OWNER", "timezone": "Asia/Almaty" }
  ]
}

Here id is the company id. You need it as :workspaceId in almost every request.

Core requests with the company key

List channels:

GET /workspaces/:workspaceId/channels

List conversations. Filters: status (OPEN, WAITING, IN_PROGRESS, CLOSED), assigned=me|none. Pagination via cursor and limit (30 by default):

GET /workspaces/:workspaceId/conversations?status=OPEN&limit=30

Start a conversation with a new number on a given channel. The response contains conversationId:

POST /workspaces/:workspaceId/conversations/start
Content-Type: application/json

{ "channelId": "clx...", "phone": "77011234567" }

Messages in a conversation:

GET /workspaces/:workspaceId/conversations/:conversationId/messages

Send a message:

POST /workspaces/:workspaceId/conversations/:conversationId/messages
Content-Type: application/json

{ "content": "Hello!" }

Errors and limits

  • 401 — no key, a wrong key or a revoked key.
  • 403 — the action is not available with an API key, or the key lacks the permission.
  • 429 — too many requests. For the company key the limit is shared: 100 requests per minute from one IP address. For a public API key every key has its own limit: 120 requests per minute. More on it in Public deals API and CRM webhooks.
Next Webhooks

Related articles