Ir para o conteúdo

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 SaaS: 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:

bash
Authorization: Bearer <sua chave>

A API aceita quatro tipos de chave:

ChaveO que ela abreOnde 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úmeroTodas 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 clusterTodas 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.

Guarde cada chave como uma senha: quem tem a chave de um número pode enviar, ler e até excluir aquele número. Deixe-a no servidor, nunca no navegador nem no aplicativo do celular, e nunca a coloque numa URL.

Primeira chamada

Guarde o endereço e a chave em variáveis do terminal (os valores abaixo são de exemplo):

bash
export API_URL="https://api.exemplo.com.br"
export API_KEY="wck_sua-chave-aqui"

Confira se a API responde:

bash
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:

bash
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