Conectar canais
Conectar o WhatsApp
Como ligar um número de WhatsApp em coexistência ou só pela API, pelo cadastro oficial da Meta.
Escolha o modo
Seção intitulada “Escolha o modo”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.
Requisitos
Seção intitulada “Requisitos”- 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.
Passo a passo no painel
Seção intitulada “Passo a passo no painel”- Abra Conexões e clique em Conectar WhatsApp.
- 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.
- 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.
- No popup, faça login no Facebook, escolha (ou crie) o portfólio e a conta de mensagens, e escolha o número.
- 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.
- 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.
Quando falta um passo
Seção intitulada “Quando falta um passo”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.
Convidar o cliente por link
Seção intitulada “Convidar o cliente por link”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.
Limites da coexistência
Seção intitulada “Limites da coexistência”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.
Sincronização da coexistência
Seção intitulada “Sincronização da coexistência”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.
Trocar de parceiro na coexistência
Seção intitulada “Trocar de parceiro na coexistência”Na coexistência o número aceita um parceiro por vez. Para trazer um número que já está com outro provedor:
- Faça backup das conversas no app.
- No app, vá em Configurações > Conta > Plataforma Business > Desconectar.
- 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.
Depois de conectar
Seção intitulada “Depois de conectar”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.
Quando a conexão cai
Seção intitulada “Quando a conexão cai”| 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.