Все id — строки
chatId, idMessage, sender и другие id приходят и передаются строками. id сообщений MAX 64-битные ("117429033780458644") — в JavaScript и PHP числом они теряют точность. idInstance и timestamp — числа.
chatId по каналам
| Канал | Личный чат | Группа | Канал (сообщество) |
|---|---|---|---|
| MAX | id собеседника: "8695836" |
отрицательный id: "-80040066617372" |
отрицательный id |
| Telegram | id собеседника: "8617393401" |
"-4012345678" (обычная), "-1001234567890" (супергруппа) |
"-1001234567890" |
"79991234567@c.us"; скрытый номер — "67341362663633@lid" |
"120363012345678901@g.us" |
— | |
| Почта | адрес собеседника в нижнем регистре: "maria@client.ru" |
— | — |
В WhatsApp суффикс на входе можно не писать: "79991234567" — то же, что "79991234567@c.us". @lid означает, что WhatsApp не сообщил номер собеседника (у него имя пользователя WhatsApp).
Номер телефона вместо chatId
В методах, которые пишут собеседнику первым, можно передать номер вместо chatId: "79991234567@c.us" (11–12 цифр). Gratio найдёт аккаунт по номеру и запомнит ответ на час. Это sendMessage, sendFileByUpload, sendFileByUrl, sendLocation, sendContact, sendPoll, forwardMessages (поле chatId), sendTyping и makeCall.
Остальные методы — правка, удаление, реакции, история, группы — принимают только chatId: возьмите его из ответа checkAccount или из уведомления.
- Нет аккаунта на этом номере —
400,code: no_account. - В Telegram найти можно только тех, кто разрешил находить себя по номеру.
Проверить номер заранее, не отправляя сообщения, — checkAccount; номер не из 11–12 цифр там — 400 bad_phone.
idMessage
- Сообщение MAX — число строкой:
"117428955282341903". - Сообщение Telegram — номер сообщения в чате строкой:
"4815". - Сообщение WhatsApp —
"3EB0…". - Письмо — 20 шестнадцатеричных знаков от Message-ID:
"c62b698304229a98aad3", одно и то же во всех папках.
У уведомлений о правке, удалении и реакции idMessage — это id события, а не сообщения. Сообщение, к которому относится событие, — в поле stanzaId:
| Событие | idMessage |
|---|---|
| правка | {id}:edit:{версия} — две разные правки одного сообщения дают два разных id |
| удаление | {id}:delete |
| реакция | {id}:reaction:{автор}:{n} — n растёт при каждой смене или снятии реакции |
eventId — ключ события
Во входящих и в сообщениях с телефона, в правках, удалениях, реакциях, звонках, событиях групп и syncGap есть eventId — ключ события в Gratio: msg:{chat}:{id}, edit:{chat}:{id}:{версия}, react:{chat}:{id}:{автор}:{n}, callstate:{callId}:{state} и т. п.
У outgoingAPIMessageReceived, outgoingMessageStatus и stateInstanceChanged eventId нет. Для них ключ — idMessage, у статусов — пара idMessage + status.
Одно событие площадки — одно уведомление: повторы при переподключении и догоне после простоя Gratio отсеивает сам. Если ваше приложение может получить одно уведомление дважды (например, повтор вебхука после тайм-аута), храните обработанные eventId и пропускайте повторы.
Время
timestamp — секунды Unix (UTC). Время в настройках канала и в кабинете — по часовому поясу канала.
Что дальше
- Как проходят сообщения и уведомления — что происходит после запроса и откуда берутся id.