Chatterfy API: What It Is and How to Get Started
Chatterfy API is a way to connect your own program, spreadsheet, CRM, or AI assistant to Chatterfy. Via the API, the program does the same things you do manually in the application: views chats, reads
Chatterfy API is a way to connect your own program, spreadsheet, CRM, or AI assistant to Chatterfy. Via the API, the program does the same things you do manually in the application: views chats, reads messages, replies to clients, adds tags, and retrieves analytics.
This article explains the API in simple terms: what you can do with it, what any request looks like, and in what order to read the other articles in this section. You don't need to program to make your first request.
API in simple terms
Imagine a service window at a café. You hand over an order note, the kitchen prepares it, and returns a tray. The API is a similar window in Chatterfy: your program sends a request ("show bot chats"), and Chatterfy returns a response with data.
API Glossary: key, service account, endpoint, JSON, id
Words that appear in the Chatterfy API articles. You don't need to memorize them — just return to this table when you come across something unfamiliar.
Word | Definition |
|---|---|
Request | A message from your program to Chatterfy: address, method, and data if needed. |
Response | What Chatterfy returns: data in JSON format and a response code. Code 200 means everything was successful. |
API key | A password for the program — a long string that starts with cfy_prod_. With this key, Chatterfy understands who is asking and what they are allowed to do. |
Service account | A separate "robot employee" in your company. The key belongs to it, not to you. It has its own role and access to the Space. |
Endpoint | The address of a specific action. For example, /chats/v1/search — to find chats. |
JSON | A text data format like {"name": "Анна"}. It is understood by both people and programs. |
id | A unique object number: company, bot, chat, message. Almost every request asks for some kind of id. |
What you can do via the API
Task | What it looks like | Instructions |
|---|---|---|
Read chats and correspondence | Bot chat list, search by name, full message history | |
Reply to clients | Send text, photo or document, reply to a message, schedule a message | |
Manage chats | Change status, assign a person in charge, add a tag, fill in a field | |
Find necessary chats | Unread, unanswered, with a tag, by period, by UTM tag | |
Export data | Retrieve all chats to a spreadsheet or your own database | |
Get notified about events immediately | Receive new messages without constant polling | |
View analytics | New and active chats, operator load and response speed, Tracker campaigns and leads |
What the API cannot do
Some actions are available only in the Chatterfy app. You cannot via API:
- invite people, change their roles and permissions;
- create bots, scenarios, and Tracker campaigns;
- manage payments and balance;
- upload files — a file is transmitted only via a link to it;
- receive notifications from Chatterfy to your address (webhooks). Instead, use real-time event subscriptions — New real-time messages via API — or regular requests.
How any API request is structured
Every API request has four parts: method, address (URL), headers, and body. Understand them once — from then on, all articles will follow the same structure.
POST
https://api.chatterfy.ai/public-api/chats/v1/search
Find bot chats
Part | Example | What is this |
|---|---|---|
Method | POST | Action type: GET — retrieve, POST — find or create, PATCH — modify, DELETE — delete. |
Address | https://api.chatterfy.ai/public-api/chats/v1/search | Common prefix https://api.chatterfy.ai/public-api and action path. v1 — version. |
Headers | ApiKey: cfy_prod_... and Content-Type: application/json | Key and data format. The key is passed specifically in the ApiKey header. |
Body | {"bot_id": "..."} | Request data in JSON. GET and DELETE requests have no body. |
Lists are requested using the POST method
Chats, bots, messages and Spaces are searched using the
POST method at an address ending in /search. Filters and the number of records are passed in the request body.How to start working with the API
Get an API key
Create a service account in the company and copy the key. Step-by-step instructions are in the article How to get an API key.Grant permissions
Add the service account to the Space with the necessary bots and select a role. Which role to select is described in the article API Key Permissions: Which Role to Assign.Make your first request
Check the key and find the company, bot, and chat IDs. Instructions — First API request in 5 minutes.Select a task
Connect AI if you don't want to write requests manually
Claude, ChatGPT, or Cursor can send API requests for you upon request. How to set this up — How to connect Chatterfy API to your AI.
Main rules for working with the API
- The address of any request starts with
https://api.chatterfy.ai/public-api.
- The key is passed in the
ApiKeyheader. TheAuthorizationheader will not work.
- One key — up to 120 requests per minute.
- The full key is shown only once. Store it like a password and do not send it to anyone.
- There is no test environment: the API works with real data. A message sent via the API will be received by a real client.
Frequently Asked Questions
Related
Was this article helpful?