Números e QR
Criar um número de WhatsApp, parear pelo QR code e acompanhar a conexão.
Na API WAAPI SaaS, cada número de WhatsApp é uma instância. Depois de pareado com o celular, o número envia e recebe mensagens pela API.
Criar um número
Os números são criados na área do cliente, em Números > Criar número: a tela confere o limite do plano e já mostra o QR para parear. Nenhuma chave entregue ao cliente cria número pela API (POST /api/v1/instances responde 401 com a chave de um número e 403 CLIENT_KEY_SCOPE com uma chave de API).
Para achar o id de cada número, liste-os com uma chave de API com o escopo Números (GET /api/v1/instances) ou copie do endereço da página do número na área do cliente (.../app/<produto>/numbers/<id>: /app/qr/numbers/<id> na API própria e /app/cloud/numbers/<id> na API oficial).
Não tem um número? Você pode alugar um pronto, mantido por nós e entregue na sua conta pelo QR code: veja Alugar um número.
Ler o QR code
O QR também sai pela API, com a chave do número (a chave de API não abre o QR):
curl -H "Authorization: Bearer $API_KEY" \
"$API_URL/api/v1/instances/<id>/qr"| Resposta | O que fazer |
|---|---|
{"status": "ready", "qr_image": "data:image/png;base64,..."} | Mostre a imagem e escaneie em WhatsApp > Aparelhos conectados. |
{"status": "paired", ...} | O número já está pareado: não há QR. |
{"status": "generating", ...} | O QR ainda está sendo gerado: chame de novo em alguns segundos. |
O QR muda a cada poucos segundos enquanto ninguém escaneia. Peça um novo a cada 2 ou 3 segundos e mostre sempre o último. A imagem é uma credencial de pareamento: não a guarde nem a mande para outro lugar.
Acompanhar a conexão
curl -H "Authorization: Bearer $API_KEY" \
"$API_URL/api/v1/instances/<id>/status"O status abre com a chave do número ou com uma chave de API que tenha o número. As outras ações pedem a chave do número:
POST /api/v1/instances/<id>/reconnect: reconecta um número que caiu.POST /api/v1/instances/<id>/disconnect: desliga o aparelho. Para voltar, é preciso escanear o QR de novo.PUT /api/v1/instances/<id>/pause: pausa ou retoma os envios do número.DELETE /api/v1/instances/<id>: remove o número da conta. O aparelho é desconectado e o número deixa de contar no plano, mas as conversas, as mensagens e as notas ficam guardadas, só para leitura. A resposta é200com{"status": "removed", "removed_at": "..."}.
Depois da remoção, a chave do número deixa de valer (401). Com uma chave de API, as rotas /api/v1/instances/<id>/... do número removido respondem 410 com {"code": "INSTANCE_REMOVED"}, ou 403 com {"code": "CLIENT_KEY_SCOPE"} se a chave listava números. As mensagens que o número enviou no mês continuam contando no uso do plano.
Na área do cliente, em Números > Números removidos, ficam os números removidos que ainda têm histórico:
- Restaurar: o número volta com o mesmo id, desconectado (é preciso ler o QR de novo), com as conversas antigas ligadas a ele e com uma chave nova do número. Webhook, Chatwoot, clusters, aquecimentos e chaves de API não voltam: configure de novo. Conta no limite de números do plano. Conectar o mesmo telefone num número novo, em vez de restaurar, começa sem o histórico.
- Apagar histórico: apaga para sempre as conversas, as mensagens e as notas do número removido. Não dá para desfazer, e não baixa o uso do mês.
Na Caixa de entrada, as conversas de um número removido aparecem marcadas como só leitura.
Restaurar, apagar o histórico e listar os removidos usam a chave global da API (GET /api/v1/instances?removed=only, POST /api/v1/instances/<id>/restore, DELETE /api/v1/instances/<id>/history); nenhuma chave entregue ao cliente abre essas rotas.
Os campos de cada rota estão na Referência da API.