Ir para o conteúdo

Números e QR

Criar um número de WhatsApp, parear pelo QR code e acompanhar a conexão.

Na API WAAPI Max, 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):

bash
curl -H "Authorization: Bearer $API_KEY" \
  "$API_URL/api/v1/instances/<id>/qr"
RespostaO 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

bash
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 é 200 com {"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.