Номер WhatsApp подключается к Gratio связанным устройством — как WhatsApp Web. Подходит и обычный WhatsApp, и WhatsApp Business. Телефон остаётся главным устройством.
Подключение
В кабинете: карточка канала WhatsApp → «Привязать номер».
По QR-коду. На телефоне: WhatsApp → «Связанные устройства» → «Привязка устройства», наведите камеру на код в кабинете.
Кодом по номеру. Введите номер — Gratio покажет код из 8 знаков. На телефоне: «Связанные устройства» → «Привязка устройства» → «Связать по номеру телефона» и введите код.
Чтобы канал работал
- Подключайте рабочий номер: Gratio видит все личные чаты номера.
- Открывайте WhatsApp на телефоне хотя бы раз в 14 дней — иначе WhatsApp отвяжет связанные устройства.
- В «Связанных устройствах» Gratio видно как «Google Chrome (Linux)» — не отвязывайте его.
- Номеру меньше 10 дней в WhatsApp — отметьте это в карточке канала («Изменить»): первое время Gratio будет писать первым осторожнее.
- Пока номер подключён к Gratio, WhatsApp не присылает пуши на телефон сотрудника — о новых сообщениях сообщает ваше приложение или Gratio.
Адреса
| Что | chatId |
|---|---|
| Личный чат | "79991234567@c.us" |
| Группа | "120363012345678901@g.us" |
| Скрытый номер | "67341362663633@lid" — у собеседника имя пользователя WhatsApp, номер не сообщается |
Так — во всех ответах и уведомлениях: chatId, sender, senderId, participant, from, owner. На входе суффикс можно не писать. Номер 79991234567@c.us проверяется: нет WhatsApp — 400 no_account.
idMessage — "3EB0…". С clientMessageId id сообщения выводится из ключа, повтор не создаёт второе.
Правила качества
WhatsApp блокирует номера, которые ведут себя как рассылка. Gratio держит правила для любого приложения на канале. Отказ с паузой — 429 и Retry-After, без паузы — 400; причина — в code.
| Правило | code |
|---|---|
| Первое сообщение — в новый чат или собеседнику, молчавшему 30 дней: не больше 200 в сутки и не чаще одного в минуту. Новому номеру — 10 дней не больше 20 в сутки | first_message_limit, first_message_gap |
| Одинаковый текст первого сообщения — не больше 10 в час | same_text_limit |
| Без ответа собеседника: до 3 сообщений за 2 минуты, одно напоминание через сутки, дальше — стоп до ответа | no_reply_limit, follow_up_too_early |
| На номер без WhatsApp не пишем | no_account |
| WhatsApp ограничил номеру новые чаты — первые сообщения на паузе сутки | restricted |
| Группы: создавать — не чаще раза в 5 минут, с одним участником; добавлять — только тех, кому номер писал, не больше одного в минуту | group_tempo, member_not_engaged |
| Исходящий звонок — не чаще раза в 20 секунд | call_tempo |
Ответы в текущих диалогах (собеседник писал за последние 30 дней) лимитами первых сообщений не ограничены. Рабочие часы и паузы рассылки — на стороне приложения.
Методы в WhatsApp
| Методы | Как работают |
|---|---|
sendMessage, sendFileByUpload, sendFileByUrl |
текст до 65 536 символов. OGG/Opus — голосовое с длительностью; MP3, M4A, AAC, AMR — аудио (без подписи); JPEG, PNG — фото; видео; WAV, WebP, GIF и прочее — документ. До 100 МБ |
sendLocation, sendContact, sendPoll, forwardMessages |
контакт — vCard с кнопкой «Написать»; опрос — 2–12 вариантов; пересылка — сообщений, которые канал видел с момента привязки |
editMessage |
своё сообщение, 15 минут |
deleteMessage |
у всех — своё за 48 часов, админ группы — и чужое; onlySenderDelete — «удалить у себя» на всех устройствах номера |
sendReaction, getAllowedReactions |
любая эмодзи; список — быстрые реакции приложения |
sendTyping, readChat |
«прочитано» видно и на телефоне сотрудника |
archiveChat, pinChat, pinMessage и отмена |
см. archiveChat и unarchiveChat |
getChatHistory, getMessage |
с момента привязки номера |
getContactInfo, getAvatar |
«О себе» — в description; фото — не чаще раза в 6 часов на собеседника |
checkAccount |
ответ хранится 30 дней, не больше 60 проверок в час |
Группы и deleteGroup |
из прав — только allowParticipantsAddMembers и allowParticipantsChangeAvatar; аватар — JPEG |
| Звонки | события — всегда; звук — если call_audio: true |
| Кнопки, истории | 501 |
Удалить группу у всех WhatsApp не умеет. deleteGroup делает как приложение: номер-админ убирает всех участников и выходит, группа пропадает из чатов на всех устройствах номера. У убранных участников она остаётся с пометкой «вас удалили».
Уведомления в WhatsApp
- Статусы исходящих:
sent→delivered→read. «Доставлено» — сообщение получил телефон собеседника; прослушанное голосовое —read. - Входящие: текст, ссылки, цитаты, фото, видео и «кружки», голосовые (OGG/Opus), документы, стикеры, геопозиция (трансляция — первой точкой), контакт (из нескольких — первый), опрос; голос в опросе —
quotedMessageна опрос с выбранными вариантами; ответы кнопками бизнес-аккаунтов, события календаря и приглашения в группы — текстом; правки, удаления, реакции. - Звонки:
offer,missed,declined,hangUp. Если ответили на телефоне,durationSeconds: 0— конец разговора связанное устройство не видит. Видеозвонок —isVideo: true.
Звонки со звуком
Если в getCapabilities у номера call_audio: true, сервер Gratio может ответить на звонок, позвонить и передать звук — как в MAX (Звонки: как это работает). Ответил Gratio — телефон сотрудника перестаёт звонить; ответили на телефоне — звонок уходит с канала. Видеозвонки не ведём.
Проверить подключение
После привязки номера проверьте канал из своего приложения:
curl "$GRATIO_URL/waInstance$GRATIO_ID/getStateInstance/$GRATIO_TOKEN"
Ответ {"stateInstance": "authorized"} — канал работает. Что умеет канал — getCapabilities.
Если канал отключился
notAuthorized — номер отвязан с телефона, связанные устройства сброшены или WhatsApp ограничил номер (подробность — в кабинете). Привяжите номер снова; автоматической перепривязки нет.
Что дальше
- Почта — особенности следующего канала.
- Напоминания и рассылки без блокировок — как писать первым и не потерять номер.