Escopos
Quatro escopos, resolvidos em tempo real a cada requisição. Quais endpoints exigem quais e por que marcar como lida é um envio.
Os escopos são por credencial — por API key ou por concessão OAuth2. São quatro.
| Escopo | Concede |
|---|---|
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 e o recebimento de qualquer entrega |
whatsapp.manage | POST /connections, POST /connections/{id}/pairing-code, POST /connections/{id}/restart, POST /connections/{id}/logout, DELETE /connections/{id} |
Marcar como lida é um envio, não uma leitura
POST /messages/read exige whatsapp.send. Parece uma operação de leitura, mas
ela transmite uma confirmação de leitura do seu número para o dispositivo do
cliente — ou seja, é de saída. A vantagem é que qualquer cliente que já pode
enviar também pode marcar como lida: sem escopo novo, sem novo consentimento.
A resolução é em tempo real
Os escopos e a lista de conexões acessíveis são resolvidos a cada requisição. Nada fica em cache no token e nada precisa ser atualizado. Duas consequências:
- Revogar uma chave ou reduzir seus escopos vale já na chamada seguinte.
- Uma conexão que você acabou de criar fica visível na chamada seguinte. Não há atraso de propagação e nada para reemitir.
Escopo insuficiente
Uma credencial sem o escopo que um endpoint exige recebe
403 insufficient_scope. Trate o código, não o status — 403 também é o que
uma recusa da lista de IPs permitidos retorna (ip_not_allowed), e os dois casos
pedem correções opostas: um significa editar os escopos da chave, o outro
significa adicionar um endereço. Veja Erros e idempotência.
Peça menos
O escopo que você não concede é o que não pode ser usado de forma indevida se a
chave vazar. Um job de relatórios somente leitura precisa de whatsapp.read e
nada mais; um serviço de notificações precisa de whatsapp.send; só um fluxo de
provisionamento precisa de whatsapp.manage, que pode excluir conexões.