Канал
Канал — место для одного номера, аккаунта или ящика определённого типа: MAX, Telegram, WhatsApp или почта. У канала два состояния:
| Состояние | Что это | Что можно сделать в кабинете |
|---|---|---|
| Без номера | номера в канале нет | «Привязать номер» своего типа по QR-коду или коду |
| Привязан | в канале работает номер | «Проверить», «Отвязать номер» — канал снова без номера и остаётся в компании |
Тип канала фиксирован: в канал WhatsApp привязывается только WhatsApp. Сменить тип или освободить канал можно через поддержку Gratio.
Отвязка не ждёт телефона: сеанс в Gratio стирается сразу. Если телефон был не на связи, запись Gratio может остаться в «Устройствах» на телефоне — её удаляют вручную.
Ключ канала
Ключ — пара idInstance (номер канала в API) и apiTokenInstance (токен). Он открывает методы, уведомления и вебхук только этого канала.
- Выдаётся сам, как только в канал привязали номер.
- Виден в любой момент: «Ключ API» в карточке канала — адрес API,
idInstance, токен. Копировать можно по полю или «Скопировать всё». - «Перевыпустить» — новый токен; прежний перестаёт работать сразу, запросы с ним получают
401. - «Отозвать» — проекты на этом ключе сразу теряют доступ; номер продолжает работать в канале.
Выдать, перевыпустить и отозвать ключ может любой сотрудник компании в кабинете.
Один канал — один проект
У канала одна очередь уведомлений и один вебхук. Если два приложения читают одну очередь, они забирают уведомления друг у друга. Нужно отдать ленту второй системе — заведите ей подписку: она получает копию всех уведомлений канала по своему адресу и ничего не забирает у основного приложения. Подробно — subscriptions.
Смена номера
- Тот же номер снова привязали в канал — ключ, история и настройки прежние, проекты работают дальше.
- Другой номер — у канала новый
idInstanceи новый ключ. Прежний ключ перестаёт работать, вебхук и подписки не переносятся: новый номер не должен молча писать в проект прежнего. Журнал и файлы прежнего номера хранятся у компании, но по новому ключу их не видно.
После смены номера возьмите в кабинете новый ключ и заново задайте вебхук и подписки.
Сроки и оплата
Каналы оплачиваются помесячно, в кабинете в разделе «Оплата». У каждого канала свой срок.
| Состояние | Когда | Что с API |
|---|---|---|
| пробный, оплачен | до конца срока | всё работает |
| срок истёк | 3 дня после конца срока | всё работает, в кабинете — напоминание |
| пауза | ещё 14 дней | отправка от имени номера отвечает 402 payment_required; приём, уведомления, история и чтение работают |
| снят | после паузы | номер отвязан, ключ не работает; история и переписка сохраняются у компании |
На паузе закрыты методы, которые что-то отправляют или меняют от имени номера: сообщения и файлы, пересылка, правка, реакции, истории, вступление в чаты, создание групп и изменение их состава, названия и фото, звонки. Оплата во время паузы снимает её сразу. Снятый канал не продлевается — нужен новый.
{"message": "Канал на паузе: оплаченный срок истёк. Продлите канал в кабинете Gratio", "code": "payment_required"}
Безопасность ключа
- Держите токен на сервере. Не вставляйте его в код страницы, мобильного приложения или в публичный репозиторий.
- Токен в форме адреса Green (
/waInstance…/{method}/{token}) попадает в журналы прокси и серверов. Если это нежелательно, используйте форму с заголовкомAuthorization: Bearer— см. Адрес и авторизация. - Утёк токен — нажмите «Перевыпустить»: старый перестанет работать сразу.
Что дальше
- Адрес и авторизация — как передать ключ в запросе.
- Шаг 2. Первый запрос — проверить ключ на деле.