Области доступа
Четыре области доступа, которые проверяются при каждом запросе. Какие эндпоинты что требуют и почему отметка о прочтении — это отправка.
Области доступа задаются для каждого учётного ключа — для API key или для OAuth2-разрешения. Их четыре.
| Область | Что даёт |
|---|---|
whatsapp.read | GET /connections, GET /connections/{id}, GET /account, GET /messages |
whatsapp.send | POST /messages, POST /messages/read |
whatsapp.events | GET /webhook, PUT /webhook, POST /webhook/rotate, а также сам приём доставок |
whatsapp.manage | POST /connections, POST /connections/{id}/pairing-code, POST /connections/{id}/restart, POST /connections/{id}/logout, DELETE /connections/{id} |
Отметка о прочтении — это отправка, а не чтение
Для POST /messages/read нужна область whatsapp.send. Операция похожа на чтение, но
она передаёт уведомление с вашего номера на устройство клиента — то есть
является исходящей. Плюс в том, что любой клиент, который уже может отправлять
сообщения, может и отмечать их прочитанными: новая область не нужна, повторное
согласие тоже.
Проверка выполняется на лету
Области доступа и список доступных соединений определяются при каждом запросе. В токене ничего не кэшируется, и ничего не нужно обновлять. Отсюда два следствия:
- Отзыв ключа или сужение его областей вступает в силу со следующего же вызова.
- Только что созданное соединение видно уже при следующем вызове. Задержки распространения нет, и ничего не нужно выпускать заново.
Недостаточно прав доступа
Если у учётного ключа нет области, которая нужна эндпоинту, он получает
403 insufficient_scope. Ориентируйтесь на код, а не на статус: 403
возвращается и при отказе из-за списка разрешённых IP-адресов (ip_not_allowed),
а исправлять эти случаи нужно по-разному: в одном случае меняют области ключа,
в другом — добавляют адрес.
См. Ошибки и идемпотентность.
Запрашивайте меньше
Область, которую вы не выдали, — это та, которой нельзя злоупотребить, если ключ
утечёт. Заданию для отчётов, которое только читает данные, нужна whatsapp.read и
ничего больше; сервису уведомлений — whatsapp.send; и только процессу
подключения нужна whatsapp.manage, с которой можно удалять соединения.
Лицензии и пробный период
7 дней бесплатного пробного периода для каждого номера, затем ежемесячная лицензия на номер. Что такое слот и что происходит, когда срок его действия истекает.
Ошибки и идемпотентность
Ориентируйтесь на код ошибки, а не на статус. И делайте безопасным каждый повторный запрос, который стоит денег.