Números de telefone do WhatsApp
Uma mensagem do WhatsApp sai de um de dois tipos de número: um que Bird opera em seu nome, ou um que o seu próprio espaço de trabalho possui. Qual deles você tem determina o que pode enviar e se um envio identifica o remetente.
A página Numbers lista ambos. O campo from na resposta de envio e no log de mensagens identifica o número que uma determinada mensagem usou.
Números gerenciados por Bird
Os números próprios de Bird não precisam de configuração e trazem os templates pré-aprovados cujos slugs começam com bird_. Bird seleciona um pela categoria do template e pela sua região: templates de authentication usam um número dedicado de autenticação, templates de utility usam um número de notificação. Um envio com template gerenciado, portanto, não tem o campo from, e defini-lo é rejeitado.
Esses números usam a infraestrutura de envio gerenciada por Bird, então o remetente que o destinatário vê é o de Bird, não o seu, e conteúdo livre não pode sair por eles. Eles são marcados como Bird-managed na coluna WABA.
Seu próprio número
Conectar um número seu é o que libera o envio com a sua própria marca: seus próprios templates e conteúdo livre dentro de uma janela de atendimento ao cliente aberta. Todo envio feito por ele identifica o número em from.
Você o conecta pela página Numbers, no popup do Embedded Signup da Meta. Existem dois caminhos, e eles diferem em quem lê o código de verificação que a Meta envia para o número:
- Eu tenho meu próprio número. Você recebe o código da Meta por SMS ou chamada de voz e digita na janela do Embedded Signup. Escolha o caminho de migração compatível ou de coexistência de Business app elegível antes de alterar um registro existente, e defina um Phone registration PIN apenas se o número já tiver um em WhatsApp.
- Um número que seu espaço de trabalho possui em Bird. Selecione-o na lista Number. Bird recebe o código e conclui a verificação da Meta para você, então o número chega pré-verificado e você apenas o seleciona na janela do Embedded Signup.
Verificação em um número que Bird possui
Escolher um número mantido inicia a verificação antes de o popup do Embedded Signup abrir. Bird pede à Meta que envie uma mensagem de texto para o número e depois lê o código em seu nome.
Isso geralmente leva menos de um minuto. Você não precisa esperar no diálogo: Continue in background o fecha, e a linha na página Numbers acompanha o mesmo progresso.
Quando o código é lido, o número está verificado com a Meta e aguardando que você conclua no Embedded Signup. Finish setting up abre o popup da Meta, onde você seleciona o número e a conta empresarial à qual ele deve se associar.
O que o status de um número significa
Um número passa por vários estados antes de poder enviar, e a coluna Status indica em qual ele está:
| Status | O que significa |
|---|---|
| Preparing | Bird está concluindo a verificação da Meta para um número que seu espaço de trabalho possui. |
| Pre-verified | Bird concluiu a verificação da Meta. Finalize o número no Embedded Signup. |
| Pending | O Embedded Signup foi concluído e Bird está registrando o número na Meta. |
| Connected | O número pode enviar. |
| Failed | A configuração parou. A linha informa o motivo. |
Qualquer um dos caminhos pode falhar no meio, na verificação da Meta ou no popup. Como você recupera depende do motivo que a linha informa.
Se a linha mostra verification_code_not_received ou verification_rate_limited, abra o número e selecione Try again em vez de desconectá-lo. Por que a pré-verificação falha e quando tentar novamente explica quando o botão fica disponível e o que fazer se a nova tentativa também falhar.
Para qualquer outro motivo, desconecte o número pelas ações da linha e conecte-o novamente: a linha com falha mantém o número reservado, então uma segunda tentativa sem removê-lo é rejeitada.
Posso enviar WhatsApp sem comprar um número de telefone? apresenta a escolha.
O que um número conectado mostra
A página de um número mostra o que WhatsApp permite que ele faça no momento, além de uma seção Activity que cobre como ele tem enviado.
Quality rating, Messaging limit e Send rate são números de WhatsApp, não de Bird. O limite de mensagens é a quantidade de conversas iniciadas pela empresa que WhatsApp permite em 24 horas, e ele aumenta conforme o número envia bem. Quality rating mostra Not rated até que WhatsApp tenha histórico de entrega suficiente para avaliá-lo.
A aba Business profile contém o que os destinatários veem sobre você no WhatsApp: o nome de exibição, a descrição, o endereço e a foto de perfil.
A conta empresarial por trás de um número
Todo número conectado pertence a uma WhatsApp Business Account, e a coluna WABA leva até ela. Sua ficha reporta as avaliações da Meta sobre a empresa em si, não sobre o número.
Esses estados controlam o que a conta pode fazer. Business verification em particular controla os templates de autenticação: uma empresa não verificada não pode criar um. Marketing Messages API mostra Onboarded quando a Meta aceita a conta. Envios de marketing não dependem disso. O onboarding controla as otimizações de entrega da Meta e um header gif, que falha em WhatsApp em uma conta que não completou o onboarding. Um espaço de trabalho pode ter várias contas empresariais, cada uma com vários números. Leia os vereditos da conta que possui o remetente pretendido; uma conta conectada tem um espaço de trabalho e proprietário regional específicos.
Bird lê essas informações da Meta em uma programação, não continuamente, então Last read from WhatsApp indica a data dos vereditos acima.
Leia seus números pela API
Tudo o que o painel mostra acima pode ser lido pela API e pelos SDKs. As leituras exigem uma chave API com acesso de leitura a whatsapp_management.
GET /v1/whatsapp/numbers retorna seus remetentes como uma página com cursor. Cada um traz o estado que WhatsApp reporta para ele, então essa é a chamada que informa quais valores de from um envio pode usar.
GET /v1/whatsapp/numbers/{id} lê um número, com o mesmo quality rating, limite de mensagens e nível de throughput que a página de detalhes exibe. GET /v1/whatsapp/numbers/{id}/profile lê o perfil empresarial por trás da aba Business profile, incluindo description, address e websites.
GET /v1/whatsapp/numbers/{id}/events retorna como um número chegou ao estado atual, do mais recente ao mais antigo: quando foi adicionado, cada mudança de status e cada decisão de limite de mensagens, quality rating e nome de exibição. Cada evento traz type, summary e created_at. type é um enum aberto, então trate um valor que você não reconhece como um tipo de evento futuro, não como um erro.
GET /v1/whatsapp/business-accounts e GET /v1/whatsapp/business-accounts/{id} leem os estados da conta que esta página descreve acima: account_review_status, business_verification_status e marketing_messages_onboarding_status. Um número reporta sua conta no próprio campo waba, que contém o ID de conta da Meta em vez de um ID Bird.
Dois detalhes que vale a pena saber antes de construir sobre essas leituras. meta_synced_at indica a data dos campos reportados por WhatsApp, correspondendo a Last read from WhatsApp no painel, e está ausente em um número que Bird opera em seu nome. Um número em processo de cadastro pode ser lido: status reporta preparing e awaiting_signup, next diz o que fazer sobre esse estado, e finish_setup_url traz o link que finaliza, para que você possa acompanhar a configuração e entregar a última etapa a uma pessoa. O único campo retido é meta_preverified_id, o id próprio de WhatsApp para um número que estamos preparando, que permanece no painel.
Conectar, renomear e desconectar um número não fazem parte da API pública nem dos SDKs. Estão disponíveis no painel e na CLI (bird whatsapp numbers create|update|delete e bird whatsapp numbers profile update). Apenas uma etapa exige navegador: uma nova conexão termina na tela de consentimento da Meta, e por isso create entrega a você uma finish_setup_url em vez de completar por conta própria.
Mensagens de entrada
Mensagens de entrada chegam ao seu espaço de trabalho apenas nos seus próprios números. Bird as registra no log de WhatsApp, e a aba Inbound na página Metrics reporta o volume recebido por número. Cada uma também abre a janela de 24 horas que o conteúdo livre necessita. Números gerenciados por Bird não recebem mensagens para o seu espaço de trabalho.
Próximos passos
- Enviando mensagens do WhatsApp: a chamada de envio que esses números usam, e quando from é obrigatório
- Templates do WhatsApp: o catálogo gerenciado e seus próprios templates
- A janela de atendimento ao cliente do WhatsApp: quando conteúdo livre pode ser entregue
- Log do WhatsApp: veja por qual número uma mensagem foi enviada
- Conectar o WhatsApp ao Bird: da compra de um número a um canal ativo: um vídeo que percorre o mesmo caminho no painel
for await (const number of bird.whatsapp.numbers.list({ limit: 25 })) {
console.log(number.id, number.phone_number, number.status);
}for number in client.whatsapp.numbers.list(limit=25):
print(number.id, number.phone_number, number.status)for number, err := range client.Whatsapp.Numbers.List(ctx, bird.WhatsappNumbersListParams{Limit: 25}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(number.Id, number.PhoneNumber, number.Status)
}foreach ($bird->whatsapp->numbers->list() as $number) {
echo $number->getId(), ' ', $number->getPhoneNumber(), ' ', $number->getStatus(), PHP_EOL;
}curl -sS "https://us1.platform.bird.com/v1/whatsapp/numbers?limit=25" \
-H "Authorization: Bearer $BIRD_API_KEY"Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.