Começar
Onde ficam o endereço e a chave da sua API e como fazer a primeira chamada.
Cada cliente tem a própria API WAAPI Max: um endereço só seu, com os seus números de WhatsApp, contatos, campanhas e fluxos. Tudo nesta documentação é uma chamada HTTP para esse endereço, com JSON na ida e na volta.
O endereço da API
Entre na área do cliente e abra API no menu. O endereço público da sua API aparece ali, com um botão para copiar. Nos exemplos ele aparece como $API_URL.
A chave de acesso
Toda chamada leva a chave no cabeçalho Authorization:
Authorization: Bearer <sua chave>A API aceita quatro tipos de chave:
| Chave | O que ela abre | Onde pegar |
|---|---|---|
Chave de API (wck_...) | Só o que você liberar ao criar: Números (listar os números e, em cada um, enviar e ler mensagens, contatos, chats, grupos, status e estatísticas; enviar e ler pelo cluster em que todos os números estão liberados), Marketing e Fluxos. Pode valer para todos os números ou só para alguns. Não cria nem apaga números, não lê o QR, não abre a caixa de entrada, o CRM nem a IA e não mexe em webhook, configuração de cluster, aquecimento ou conta. | Área do cliente: API > Chaves de API > Criar chave. A chave aparece uma vez só, ao criar. |
| Chave do número | Todas as rotas /api/v1/instances/<id>/... daquele número, inclusive QR, webhook e excluir o número (menos restaurar e apagar o histórico de um número removido, que são da chave global). Não abre GET /api/v1/instances nem outro número. | Área do cliente: Números > abrir o número > aba Acesso à API > Chave de acesso da API. |
| Chave do cluster | Todas as rotas /api/v1/clusters/<id>/... daquele cluster, inclusive excluir o cluster. | Área do cliente: Clusters > abrir o cluster > aba Configurações > Chave de acesso da API. |
| Chave da plataforma (global) | Todas as rotas da sua API. | Nunca é entregue ao cliente: ela opera a plataforma (limites, cobrança) e fica só com a equipe da plataforma. |
Para um sistema novo, prefira a chave de API: ela dá só o acesso que o sistema precisa e pode ser revogada sem mexer nas outras.
Chaves de API. Quem pode editar os números da conta (por padrão, o dono e os administradores) cria e revoga as chaves em API > Chaves de API. Cada escopo também pede a permissão de editar a área que ele libera: só quem edita o Marketing dá o escopo Marketing a uma chave. Uma conta tem até 20 chaves ativas. Revogar desliga a chave na hora.
Chave do número e do cluster. Quem pode editar os números (para a chave de um número) ou os clusters (para a de um cluster) vê e troca essas chaves; por padrão, o dono e os administradores. No cartão, Mostrar chave revela e copia a chave, e Gerar nova chave cria outra. A chave anterior deixa de valer na hora, então atualize os seus sistemas logo depois de gerar.
Para ligar um sistema seu a um fluxo sem chave nenhuma, use o webhook de entrada: o token do fluxo vai no caminho.
Primeira chamada
Guarde o endereço e a chave em variáveis do terminal (os valores abaixo são de exemplo):
export API_URL="https://api.exemplo.com.br"
export API_KEY="wck_sua-chave-aqui"Confira se a API responde:
curl -H "Authorization: Bearer $API_KEY" "$API_URL/api/v1/health"E liste os seus números com uma chave de API que tenha o escopo Números:
curl -H "Authorization: Bearer $API_KEY" "$API_URL/api/v1/instances"A resposta 200 traz só os números que a chave pode usar, cada um com o id que vai nas outras rotas. A chave de um número não abre essa lista: com ela, confira o número direto em GET /api/v1/instances/<id>/status.
Uma chave errada ou ausente responde 401. Uma chave de API sem o escopo da rota responde 403 com "code": "CLIENT_KEY_SCOPE". Um limite do plano responde 403 com um code estável: veja Limites do plano e erros.
Próximos passos
- Números e QR: parear um número com o celular e acompanhar a conexão.
- Envio de mensagens: texto, mídia e resposta citada.
- Webhooks: receber as mensagens no seu servidor.
- Referência da API: todas as rotas, com os campos e os exemplos.