Visão geral dos números
Cada número de WhatsApp da sua conta envia e recebe mensagens como um dispositivo conectado ao WhatsApp daquele telefone, do mesmo jeito que o WhatsApp Web. O telefone continua funcionando, e o Turbo Notify aparece em Dispositivos conectados com o nome da sua organização (no WhatsApp Business para Android, com o nome que a pessoa digitou ao vincular).
Número principal e números extras
| Número principal | Números extras | |
|---|---|---|
| Quantos | Um por conta | Quantos o plano permitir |
| Alias | Sempre main | Você escolhe no cadastro |
| Cadastro e pareamento | Pelo dashboard, com QR code ou código | Cadastro pelo dashboard ou pela API. Pareamento pelo dashboard (QR code ou código) ou pela API (código ou QR code) |
| Cobrança | Incluída no plano | Por número, veja Cobrança |
Todas as rotas de mensagens, contatos e grupos ficam debaixo do número:
/v1/numbers/{ref}/....
Todo número também tem um id (como num_0a1b2c3d4e5f60718293a4b5c6d7e8f9),
gerado pelo Turbo Notify, que nunca muda, nem se o alias for renomeado. Em
qualquer rota, o id vale no lugar do alias ({ref} aceita os dois). Alias não pode começar com num_.
Ciclo de vida de um número extra
| Etapa | O que você faz | Status resultante | Página |
|---|---|---|---|
| Cadastrar | POST /v1/numbers | pending | Inclusão |
| Parear | No dashboard, Vincular número. Pela API, POST /v1/numbers/{ref}/pair. Em ambos, com QR code ou código | pairing, depois connected ou failed | Pelo dashboard e pela API |
| Acompanhar | GET /v1/numbers/{ref} ou webhooks number.* | o status atual | Status |
| Desconectar e reconectar | POST /v1/numbers/{ref}/disconnect e .../connect | disconnected, connecting, connected | Conexão |
| Remover | DELETE /v1/numbers/{ref} | removido na hora, ou com remoção agendada (scheduled_deletion_at) para o fim do período já pago, com o status de sempre até lá | Remoção |
Um número conectado pode cair: a conexão com o WhatsApp pode cair, o Turbo Notify pode transferir a conexão internamente (manutenção, balanceamento de carga, recuperação de uma falha interna) ou alguém pode remover a conexão em Dispositivos conectados no celular.
Quando o Turbo Notify consegue trazer o número de volta sozinho, o status fica
reconnecting enquanto isso acontece. Se o número volta dentro da janela de
reconexão automática (cerca de um minuto), nenhum webhook é enviado: para você,
o número não caiu. Se não volta a tempo, você recebe number.disconnected, com
at igual ao momento em que o número ficou offline, e o Turbo Notify continua
tentando reconectar.
Quando a queda precisa de você, o aviso chega na hora. Se a conexão foi
removida no celular, você recebe number.revoked e o número precisa ser
pareado de novo. O campo reason de number.disconnected e number.revoked
diz o que aconteceu, veja
Motivos.
Acompanhar mudanças
Duas formas, que podem ser combinadas:
- Webhooks
number.*avisam assim que o número conecta, desconecta, falha, é revogado ou tem a remoção agendada, cancelada ou concluída, veja Webhook. Todo eventonumber.*traz oiddo número emdata.id, e todo evento de um número traz onumber_idno envelope, para você encaminhar o evento ao cliente certo sem consultar nada. - Consulta
GET /v1/numbers/{ref}devolve o status atual e, durante o pareamento, o blocopairingcom o código a ser digitado ou a imagem do QR code. Use-a para mostrá-los, porque não são enviados por webhook. Veja Status.
Se você revende números
Quando os números da sua conta pertencem aos seus clientes, cadastre cada
número com um alias por cliente e guarde o id que a resposta devolve: ele
aparece nas consultas e nos webhooks e não muda se o alias mudar. O
guia de revenda mostra o fluxo completo.
É o seu cliente quem usa o código ou lê o QR code no celular dele. A página de Pareamento pela API descreve a tela que permite a ele concluir sozinho: novo código ou QR code a qualquer momento, mensagem certa para cada motivo de falha e o limite de tentativas que protege o número dele.