Skip to main content
Você pode enviar a chave de duas formas (escolha a que seu framework preferir): Opção A (Padrão Recomendado): 
Authorization: Bearer sk_live_sua_chave_aqui
Opção B (Header Customizado): 
x-api-key: sk_live_sua_chave_aqui
A API Key está sempre vinculada a um único Workspace. Todas as operações (criar instâncias, enviar mensagens) ocorrem dentro desse contexto. Você não consegue acessar dados de outro workspace com a mesma chave.

​
Tabela de Escopos (Permissões)

Ao criar uma API Key, você define o que ela pode fazer. Se você deixar a lista de escopos vazia, a chave terá acesso ADMIN (todas as operações permitidas). Para segurança, recomendamos restringir.

​
Escopos por instâncias

  • whatsapp:instances:list Ver instâncias e obter detalhes (QR Code).
  • whatsapp:instances:create Criar novas conexões/instâncias.
  • whatsapp:instances:disconnect Desconectar uma sessão ativa.
  • whatsapp:instances:delete Remover uma instância (apenas se desconectada).

​
Escopos por mensagens

  • whatsapp:send Enviar mensagens (texto, mídia, arquivos).
  • whatsapp:read Listar e consultar histórico de mensagens enviadas (GET /v1/whatsapp/messages), status por ID (GET /v1/whatsapp/messages/{messageId}), listar mensagens recebidas/inbound (GET /v1/whatsapp/messages/inbound) e obter um inbound por ID (GET /v1/whatsapp/messages/inbound/{id}).
  • whatsapp:update Editar o conteúdo de uma mensagem enviada.
  • whatsapp:cancel Cancelar uma mensagem agendada ou na fila.
  • whatsapp:delete Apagar a mensagem para todos (Revoke).

​
Escopos por grupos (experimental)

  • whatsapp:groups Enviar mensagens para grupos (por JID), listar grupos, adicionar/remover participantes, enviar/revogar link de convite e buscar código de convite. Requer que o workspace tenha “Recursos de grupos (experimental)” ativado em Settings. A documentação da API de grupos é um OpenAPI exclusivo, oculto por padrão.

​
Escopos por contatos

  • contacts:read Listar contatos e obter contato por ID.
  • contacts:create Criar contato (phone ou email único por workspace).
  • contacts:update Atualizar contato.
  • contacts:delete Excluir contato.
Os contatos do workspace podem ser usados no envio de mensagens WhatsApp com payload.contactId (tipo contact). Veja a documentação da API de Contatos.

​
Escopos por tags

  • tags:read Listar tags e obter tag por ID.
  • tags:create Criar tag (nome único por workspace).
  • tags:update Atualizar nome da tag.
  • tags:delete Excluir tag (desvincula de todos os contatos).
As tags (segmentos) são vinculadas aos contatos via tagIds na criação/atualização de contato; use tagId na listagem de contatos para filtrar por tag.

​
Escopos por templates (gestão na API v1)

  • templates:read Listar, buscar (search) e obter template por ID (GET /v1/templates, GET /v1/templates/{id}).
  • templates:create Criar template (POST /v1/templates).
  • templates:update Editar template (PATCH /v1/templates/{id}).
  • templates:delete Excluir template (DELETE /v1/templates/{id}).
O envio multicanal por template usa POST /v1/templates/send e exige os escopos de canal (whatsapp:send, sms:send, email:send), não estes quatro. Veja a documentação Template API e a página Variáveis do contato, campos personalizados e CRUD.

​
Restrição por Instância

Além dos escopos (O QUE fazer), você pode limitar ONDE fazer. Se a sua API Key tiver o campo instanceIds preenchido, ela só poderá interagir com aquelas instâncias específicas.
  • Tentar enviar mensagem por uma instância não listada = Erro 403.
  • Tentar listar instâncias = Retorna apenas as permitidas.
  • Mensagens recebidas (inbound): GET /v1/whatsapp/messages/inbound só inclui registros das instâncias permitidas; filtrar por instanceId na query exige que essa instância esteja na lista (403 se não estiver).
De forma análoga, as rotas de E-mail e Push permitem restringir a chave por domínios (domainIds) e por apps de push (pushAppIds). Quando essas listas estão vazias, a chave acessa todos os recursos do tipo; quando preenchidas, apenas os listados (envio de e-mail só dos domínios permitidos, envio de push só para dispositivos dos apps permitidos).

​
Respostas de Erro de Autenticação

Se algo der errado com sua chave, a API retorna códigos HTTP claros para facilitar o debug:
Verifique se o header está correto e se a chave não foi apagada no painel.
Verifique se a chave tem o Escopo necessário para a rota. Para envio, verifique também se não excedeu créditos do plano ou saldo (Pague pelo uso); quem está em plano e acaba os créditos do mês usa o saldo automaticamente (code: PLAN_LIMIT_CREDITS quando insuficiente). Agendamento pode não estar permitido no plano (PLAN_LIMIT_SCHEDULING).