How to export all chats via API

Chat export is a way to retrieve all of a bot's chats at once: into a spreadsheet, your CRM, or a database. It reads a snapshot of the chats at the moment of initiation, so it doesn't skip or repeat a

Updated November 2, 20264 min
Chat export is a way to retrieve all of a bot's chats at once: into a spreadsheet, your CRM, or a database. It reads a snapshot of the chats at the moment of initiation, so it doesn't skip or repeat anything, no matter how many chats there are.
In this article, you will learn how to export all chats, a ready-to-use script for saving to CSV, and how to retrieve only subsequent changes.


Requirements

  1. An API key with the Space controller role or higher — exporting requires the chat.export permission. More details — API Key Permissions: Which Role to Assign.
  1. Bot ID — First API request in 5 minutes.


How chat export differs from search


Search `/chats/v1/search`
Export `/chats/v1/export`
How many chats can be scrolled
Up to 10,000
No limit
Duplicates and skips
Possible: the list changes while you are reading it
No: it reads a snapshot at the moment of the first request
How long does a cursor last
No limit
5 minutes after each page
Purpose
Displaying a list, finding a chat
Retrieving everything in bulk


Export all bot chats

All bot chats are exported using POST /chats/v1/export with the bot_id in the body — page by page, via cursor, without the 10,000 chat limit. No more than 5 minutes should pass between pages.

  1. Count chats

    This way you know how many chats to expect. The filter is the same as the one used in the export, or you can use no filter:
    Запросbash
    curl -X POST 'https://api.chatterfy.ai/public-api/chats/v1/stats' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"bot_id": "ID_БОТА"}'
    The total number is in the total field.

  2. Request the first page

    Запросbash
    curl -X POST 'https://api.chatterfy.ai/public-api/chats/v1/export' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"bot_id": "ID_БОТА", "limit": 100}'
    The response is structured the same way as for search: chats are in data, the next page is in pagination.

  3. Navigate through pages without pauses

    Repeat the same request, adding cursor to the body with the value next_cursor from the previous response.

  4. Stop at the last page

    When has_more: false is received, the export is finished.
The Cursor is valid for 5 minutes
If more than 5 minutes pass between pages, the API will return a cursor_expired error. In that case, restart the export, without a cursor.
The filter also works for exports — for example, only chats from October or only those with a tag. How to set it up is in the article Chat filters in the API.


Ready-to-use Python script: all chats in CSV

The script exports all bot chats to a chats.csv file, which can be opened in Excel and Google Sheets. All you need is Python 3 — there is nothing else to install.

  1. Save the script

    Copy the code into an export_chats.py file. In the BOT_ID line, replace ID_БОТА with your bot's ID.
    export_chats.pypython
    import csv
import json
import os
import time
import urllib.error
import urllib.request

API = "https://api.chatterfy.ai/public-api"
KEY = os.environ["CHATTERFY_API_KEY"]
BOT_ID = "ID_БОТА"


def call(path, body):
    request = urllib.request.Request(
        API + path,
        data=json.dumps(body).encode("utf-8"),
        method="POST",
        headers={"ApiKey": KEY, "Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(request, timeout=30) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        if error.code == 429:
            time.sleep(int(error.headers.get("Retry-After", "5")))
            return call(path, body)
        raise


body = {"bot_id": BOT_ID, "limit": 100}
total = 0

with open("chats.csv", "w", newline="", encoding="utf-8-sig") as file:
    writer = csv.writer(file)
    writer.writerow(["id", "name", "username", "status", "created_at", "last_message"])
    while True:
        page = call("/chats/v1/export", body)
        for chat in page["data"]:
            last_message = (chat.get("last_message") or {}).get("content", "")
            writer.writerow([chat["id"], chat.get("name", ""), chat.get("username", ""),
                             chat["status"], chat["created_at"], last_message])
        total += len(page["data"])
        print("Выгружено чатов:", total)
        if not page["pagination"]["has_more"]:
            break
        body["cursor"] = page["pagination"]["next_cursor"]

print("Готово: chats.csv")

  2. Pass the key and run

    Терминалbash
    export CHATTERFY_API_KEY='ВАШ_КЛЮЧ'
python3 export_chats.py

  3. Open the file

    The chats.csv file will appear in the same folder. It contains the chat ID, name, username, status, creation date, and the text of the last message.
The key is passed via the CHATTERFY_API_KEY environment variable, rather than being written to the file — this way, the script can be shown and shared without risk. If the API returns 429, the script will wait and continue automatically.


Retrieve only updated chats

After the first full export, you don't need to retrieve everything every time. Request only chats that have had new messages since the last time:

  1. Remember the start time

    Save the current time before each synchronization.

  2. Request modified chats

    Next time, send a search request with sort: asc and a filter by updated_at — the time of the last message. The lower bound is the time of the previous run with a buffer of a few minutes, the upper bound is the current time:
    Тело запроса /chats/v1/searchjson
    {
  "bot_id": "ID_БОТА",
  "limit": 100,
  "sort": "asc",
  "filter": {
    "field": "updated_at",
    "operator": "between",
    "value": ["2026-10-29T11:55:00Z", "2026-10-30T12:00:00Z"]
  }
}

  3. Update records by id

    If you already have the chat, replace it with the new version. This way, duplicates caused by the time buffer won't cause any issues.
Use between, not after: between includes the boundaries, so a chat with a message exactly at the moment of the boundary will not be lost.


FAQ



Related

How to get chats and messages via API
Chats and messages via the API are read in two requests: first the list of bot chats, then the messages of the specific chat. This is the same as opening the bot in the application and tapping on a co
Chat filters in the API
Chat filters are conditions used by the API to select chats: for example, 'unread', 'with the tag Paid', or 'came from Google'. The same filter works in search, counting, exporting, and event subscrip
API Errors and Limits
An API error is a response where Chatterfy explains why it didn't complete a request. All errors look the same, so you can figure them out using two fields: the response code and code . This article e
How to connect Chatterfy API to your AI
Connecting the API to your AI means giving Claude, Cursor, ChatGPT, or another assistant an instruction and a key so it can send requests to Chatterfy on your behalf. You write 'show me who hasn't bee

Was this article helpful?