checkAccount

Проверяет, есть ли у номера телефона аккаунт в мессенджере канала, и отдаёт его chatId. Нужен перед первым сообщением новому клиенту: есть WhatsApp — пишете в WhatsApp, нет — в MAX.

Параметры

Пример запроса

Есть ли у Марии аккаунт в MAX:

curl

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/checkAccount/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"phoneNumber": 79991234567}'

Python

import os
import requests

BASE = f"{os.environ['GRATIO_URL']}/waInstance{os.environ['GRATIO_ID']}"
TOKEN = os.environ["GRATIO_TOKEN"]

url = f"{BASE}/checkAccount/{TOKEN}"
payload = {"phoneNumber": 79991234567}
response = requests.post(url, json=payload, timeout=60)
print(response.status_code, response.json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/waInstance${GRATIO_ID}`;

const url = `${base}/checkAccount/${GRATIO_TOKEN}`;
const payload = { phoneNumber: 79991234567 };
const response = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
console.log(response.status, await response.json());

PHP

<?php
$base = getenv('GRATIO_URL') . '/waInstance' . getenv('GRATIO_ID');
$url = $base . '/checkAccount/' . getenv('GRATIO_TOKEN');
$payload = ['phoneNumber' => 79991234567];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);

Пример ответа

Ответ 200 OK:

{"exist": true, "chatId": "8695836", "fromCache": false}

Поля ответа

Ещё примеры

Аккаунта нет

{"exist": false, "chatId": "", "fromCache": false}

Ответ «нет аккаунта» тоже хранится в кэше час: повтор вернёт "fromCache": true.

WhatsApp

chatId — адрес чата WhatsApp. Если WhatsApp не сообщил номер (у собеседника имя пользователя), адрес кончается на @lid:

{"exist": true, "chatId": "79991234567@c.us", "fromCache": false}

Пределы

Мессенджеры строго ограничивают поиск по номеру: частые проверки похожи на перебор базы. Gratio держит темп сам и при превышении к мессенджеру не обращается.

• Сверх предела — 469 rate_limited с Retry-After. Повтор раньше срока получит тот же отказ.
• Отправка по номеру (chatId: "79991234567@c.us" в sendMessage) проверяет номер так же: с тем же кэшем и в тот же предел.
• force в WhatsApp сбрасывает только часовой кэш: ответ, сохранённый на 30 дней, вернётся без запроса к WhatsApp, а fromCache будет false.

Когда вызывать

• Один раз на номер. Сохраните chatId у себя и дальше пишите по нему — без проверки.
• Не проверяйте базу номеров списком: частые проверки мессенджеры считают подозрительными.
• Отправить сообщение можно и без отдельной проверки: sendMessage по номеру сам найдёт аккаунт. Нет аккаунта — 400 no_account.

Ошибки

Общие правила — в статье Ответы и ошибки.

Особенности каналов

• Telegram. Найти по номеру можно только того, кто разрешил это в настройках приватности. "exist": false в Telegram не всегда значит «аккаунта нет» — человек мог скрыть номер.
• MAX. Номер в ответе и в чате не виден: MAX отдаёт только id собеседника.
• WhatsApp. Перед первым сообщением Gratio проверяет номер сам: на номер без WhatsApp отправка — 400 no_account. Правила первых сообщений — в статье WhatsApp.

Что дальше

• sendMessage — написать по найденному chatId.
• Идентификаторы чатов и сообщений — номер вместо chatId.
• Темп и лимиты — пределы всех методов.