Pular para o conteúdo

Conectar canais

Conectar o WhatsApp

Como ligar um número de WhatsApp em coexistência ou só pela API, pelo cadastro oficial da Meta.

O Messajo conecta números pelo cadastro oficial da Meta (Embedded Signup), em dois modos. A escolha é feita na hora de conectar e muda o que o número consegue fazer:

Coexistência (“Manter meu WhatsApp Business”) Só API (“Número novo, só pela API”)
App WhatsApp Business no celular Continua funcionando, com as mensagens enviadas pelo celular chegando à API (message.echo) O número fica dedicado à integração
Velocidade de envio Fixa em 20 msg/s 80 msg/s, ou 1.000 msg/s quando a Meta libera vazão alta
Histórico de 6 meses e contatos Sincronizados uma vez, dentro de 24 h Não há
Perfil, nome exibido e username Editados no app do celular Editados pelo painel ou pela API
Registro do número O número não é registrado de novo Registrado com um PIN aleatório de 6 dígitos, guardado cifrado
Parceiros ao mesmo tempo Só um Vários

Use a coexistência quando o atendimento continua no celular. Use o modo só API para volume ou para um número novo.

  • Um portfólio de negócios na Meta e acesso de admin a ele.
  • Um número de telefone para conectar.
  • Na coexistência: o número já ativo no app WhatsApp Business 2.24.17 ou mais novo.
  • No modo só API: um número que possa receber o código de verificação por SMS ou ligação e que não esteja em uso no app.
  • No painel, o papel de dono ou admin, com o 2FA ligado.
  1. Abra Conexões e clique em Conectar WhatsApp.
  2. Escolha o modo: Manter meu WhatsApp Business (coexistência) ou Número novo, só pela API. Na coexistência, o painel mostra a lista de limites antes de seguir. Clique em Continuar.
  3. Clique em Abrir o popup da Meta. O popup abre em outra janela: não feche a página do painel. Se o navegador bloquear, libere popups do endereço do painel e tente de novo.
  4. No popup, faça login no Facebook, escolha (ou crie) o portfólio e a conta de mensagens, e escolha o número.
  5. Na coexistência, confirme no app do celular lendo o QR code que a Meta mostra. No modo só API, confirme o número com o código por SMS ou ligação.
  6. Ao fechar o popup, o painel mostra Concluindo a conexão… e, em seguida, WhatsApp conectado. A conexão aparece como Ativa e sai o evento connection.created.

Na conclusão, o servidor troca o código do popup pelo token da conta (guardado cifrado), confere que a conta escolhida é mesmo a que o popup autorizou, inscreve o app nos webhooks da conta, registra o número (só API) e lê a saúde do número. Contas banidas ou sinalizadas pela Meta são recusadas antes de qualquer alteração na Meta, com o erro account_flagged.

Se um passo depois da inscrição falhar, a conexão fica Pendente e o painel mostra o motivo, por exemplo “O registro do número na Meta falhou.”. Na página da conexão:

  • Tentar registrar de novo refaz só o registro do número (só API). A Meta aceita até 10 registros por número em 72 h.
  • Concluir conexão refaz o que faltou, sem abrir o popup de novo.

Cada passo, do popup e do servidor, fica gravado na aba Histórico da conexão. Um cancelamento no popup aparece lá com a etapa em que a pessoa parou.

Agências podem conectar o número de um cliente sem que ele crie conta no Messajo. Em Links de conexão, clique em Criar link e configure (o botão Criar link de conexão, em Conexões, leva para lá):

Campo O que é
Rótulo Nome do link, só a sua equipe vê
Canal WhatsApp. Instagram e Messenger chegam na 0.2.0-alpha
Modo Coexistência, só API ou “escolhido por quem abrir”
Validade 1 hora, 24 horas, 3, 7, 14 ou 30 dias. Padrão: 7 dias
Reaproveitável Desligado, o link vale para um número só; ligado, para vários
Senha (opcional) De 8 a 128 caracteres, pedida antes de abrir o cadastro
Idioma da página Idioma da página e do e-mail: português, inglês ou espanhol
Reconectar uma conexão (opcional) Faz do link uma reconexão: herda o modo da conexão e vale uma vez só
Enviar por e-mail para (opcional) Manda o link por e-mail já na criação

A URL do link (https://<painel>/c/<token>) aparece uma única vez, na criação: o Messajo guarda só o hash do token. Copie e envie por onde quiser, ou mande pelo e-mail da plataforma. Enviar por e-mail gera um token novo, e a URL anterior deixa de valer. A senha nunca vai no e-mail: combine com o cliente por outro canal.

A página do convite não pede login. Ela mostra o nome e o logo da sua organização, deixa trocar o idioma, explica os modos e os limites da coexistência e abre o mesmo popup da Meta. Ao terminar, mostra “Conexão feita. Pode fechar esta página.” A conexão fica com a sua organização: o cliente não ganha acesso a nada.

  • Cinco senhas erradas seguidas bloqueiam o link por 15 minutos (link_locked).
  • Link de uso único já usado responde link_used; vencido, link_expired. Para tirar um link do ar antes do prazo, use Revogar.
  • O logo vem de Configurações → Organização.

Os links também podem ser criados pela API, em POST /v1/connection-links (permissão admin). Veja a referência da API.

A Meta impõe estas regras a todo número em coexistência:

  • velocidade fixa de 20 msg/s;
  • grupos não sincronizam;
  • listas de transmissão ficam só leitura;
  • mensagens temporárias e de visualização única são desligadas;
  • o app precisa ser aberto a cada ~14 dias;
  • exige WhatsApp Business 2.24.17 ou mais novo;
  • só um parceiro por vez.

Logo depois de conectar em coexistência, o Messajo pede à Meta os contatos do app e, em seguida, até 6 meses de conversas. A aba Sincronização da conexão mostra cada um:

Status O que quer dizer
Na fila Ainda não foi pedida, ou vai ser pedida de novo depois de uma falha
Pedida à Meta A Meta aceitou o pedido e está mandando os dados
Concluída Tudo chegou. O histórico mostra o progresso em % por fase
Recusada A pessoa recusou o compartilhamento do histórico no celular
Prazo de 24 h vencido A Meta só aceita o pedido até 24 h depois da conexão

Cada sincronização acontece uma vez só. Se o pedido falhar, o Messajo tenta de novo em 1 min, 5 min, 15 min, 1 h, 3 h e 6 h, sempre dentro das 24 h. Uma falha aqui nunca derruba a conexão. Os contatos chegam como evento contacts.sync e as conversas como history.batch, e as mensagens importadas aparecem nos logs com a origem history.

Na coexistência o número aceita um parceiro por vez. Para trazer um número que já está com outro provedor:

  1. Faça backup das conversas no app.
  2. No app, vá em Configurações > Conta > Plataforma Business > Desconectar.
  3. Conecte de novo pelo Messajo, como no passo a passo acima.

O parceiro antigo recebe o aviso PARTNER_REMOVED da Meta. Se aparecer um erro de linha de crédito do parceiro anterior, siga o guia da Meta para coexistência.

A aba Visão geral da conexão mostra a Saúde do número:

  • Qualidade: Alta, Média, Baixa ou Sem nota, como a Meta mede;
  • Faixa de envio: quantos contatos novos por 24 h o portfólio pode alcançar (veja Limites);
  • Velocidade: 20, 80 ou 1.000 msg/s, a vazão usada no envio;
  • Envio: Liberado, Limitado ou Bloqueado;
  • a restrição, quando a Meta restringe a conta, com o prazo.

O Messajo lê a saúde a cada 15 minutos. Atualizar saúde lê na hora. A aba Perfil edita o perfil do negócio, pede a troca do nome exibido e define o username (só no modo só API).

Cada mudança de status gera um evento connection.* nos seus destinos de eventos, com o motivo em reason, e um e-mail para donos e admins, no idioma de cada um.

Status Quando O que fazer
Precisa reconectar A Meta invalidou o token (erro 190), numa leitura de saúde ou num envio Reconectar
Restrita A Meta restringiu a conta por um prazo, ou bloqueou o envio por política Esperar o prazo e corrigir a causa no Gerenciador do WhatsApp. O envio continua liberado onde a Meta deixar
Desativada Violação de política ou banimento Recorrer na Meta. Se ela reativar, a conexão volta a Ativa sozinha
Desconectada O app foi removido da conta, a conta ou o número foi apagado, ou alguém desconectou pelo painel Conectar de novo

No erro 190, o e-mail para donos e admins traz um link de reconexão. Na página da conexão, Reconectar abre o popup de novo, e Gerar link de reconexão cria um link para mandar a quem administra o número. A reconexão precisa ser do mesmo número (reconnect_mismatch) e mantém o id da conexão, o histórico e os destinos.

Reconectar uma conexão Desconectada conta como conexão nova na cobrança; reconectar uma em Precisa reconectar não. Uma conta do WhatsApp Business (WABA) pertence a uma organização só: conectá-la em outra devolve waba_owned_by_other_org. Uma conexão Desconectada nunca volta a Ativa sozinha: só reconectando pelo painel.

Desconectar para de receber e enviar pelo número. No modo só API, dá para também cancelar o registro do número na Meta. Na coexistência, o painel mostra como remover o acesso no app do celular.