После подключения Gratio загружает историю всех чатов канала в фоне — до самого начала каждого чата. getSyncStatus показывает, как идёт загрузка: сколько чатов готово и сколько сообщений уже можно читать getChatHistory. Удобно, чтобы показать в вашей системе «Синхронизация · 37 из 128 чатов» и начать перенос переписки, когда история готова.
| Запрос | GET /v1/instances/{idInstance}/getSyncStatus |
| Ключ | заголовок Authorization: Bearer {apiTokenInstance} |
| Тело | нет |
| Каналы | MAX, Telegram, WhatsApp, почта, чат на сайте |
Пример запроса
Как идёт загрузка истории:
curl
curl "$GRATIO_URL/v1/instances/$GRATIO_ID/getSyncStatus" \
-H "Authorization: Bearer $GRATIO_TOKEN"
Python
import os
import requests
BASE = f"{os.environ['GRATIO_URL']}/v1/instances/{os.environ['GRATIO_ID']}"
HEADERS = {"Authorization": f"Bearer {os.environ['GRATIO_TOKEN']}"}
url = f"{BASE}/getSyncStatus"
response = requests.get(url, headers=HEADERS, timeout=60)
print(response.status_code, response.json())
Node.js
const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/v1/instances/${GRATIO_ID}`;
const auth = { Authorization: `Bearer ${GRATIO_TOKEN}` };
const url = `${base}/getSyncStatus`;
const response = await fetch(url, { headers: auth });
console.log(response.status, await response.json());
PHP
<?php
$base = getenv('GRATIO_URL') . '/v1/instances/' . getenv('GRATIO_ID');
$auth = 'Authorization: Bearer ' . getenv('GRATIO_TOKEN');
$url = $base . '/getSyncStatus';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [$auth],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 90,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);
Пример ответа
Ответ 200 OK — загрузка идёт, готово 37 чатов из 128:
{
"state": "syncing",
"chats": {"total": 128, "done": 37},
"messages": 41250,
"startedAt": 1792300000,
"finishedAt": null
}
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
state |
string | состояние загрузки — таблица ниже |
chats.total |
integer | сколько чатов загружается |
chats.done |
integer | сколько из них догружено до начала |
messages |
integer | сколько сообщений уже в истории канала |
startedAt |
integer или null | когда началась первая полная загрузка, секунды Unix |
finishedAt |
integer или null | когда она закончилась; пока идёт — null |
state |
Что значит |
|---|---|
waiting |
загрузка ещё не начиналась: канал не был на связи |
syncing |
идёт первая полная загрузка |
synced |
все чаты догружены до начала. Новые чаты потом догружаются сами, без смены состояния |
paused |
канал на паузе за неоплату — загрузка тоже на паузе |
unsupported |
канал не умеет загружать историю: getChatHistory отдаёт последние сообщения с площадки, до 200 |
Начало и конец первой полной загрузки приходят и уведомлением — syncStateChanged. Опрашивать getSyncStatus по таймеру не нужно.
Ошибки
| Код | code |
Когда | Что делать |
|---|---|---|---|
401 |
— | неверный idInstance или токен |
взять ключ в кабинете |
Общие правила — в статье Ответы и ошибки.
Особенности каналов
- Пока идёт загрузка, история уже читается: getChatHistory отдаёт то, что загружено, а глубже дочитывает с площадки прямо в ответ на запрос.
- Темп загрузки — тот же, что у живой работы: Gratio держит паузы и пределы площадки, чтобы история не стоила номеру блокировки. Большой канал может загружаться часами.
- WhatsApp. Старые сообщения догружает телефон номера — он должен быть в сети.
- Почта. Чат — переписка с одним адресом: письма из «Входящих», «Отправленных» и «Архива», у Gmail — из «Вся почта».
Что дальше
- getChatHistory — листать историю чата до начала.
- syncStateChanged — уведомление о начале и конце загрузки.
- getChats — список чатов канала.