Passar para o conteúdo principal

Integração WhatsApp Coex

Como configurar e utilizar a Integração WhatsApp Coex, que conecta números de WhatsApp Business ao Ploomes usando o modelo de coexistência da Meta.

Escrito por Ploo

1) Sobre a Integração WhatsApp Coex

A Integração WhatsApp Coex conecta o Ploomes ao WhatsApp Business por meio do modelo de coexistência (Coexistence) da Meta. Esse modelo permite vincular um número de WhatsApp Business que já está em uso no aplicativo oficial (app do WhatsApp Business) à conta da Meta usada pela integração, sem exigir a migração para um número exclusivo de API.

Com a integração ativa, mensagens recebidas no WhatsApp passam a gerar automaticamente registros de interação no Ploomes, vinculados ao contato e ao usuário responsável pelo número. Também é possível gerar um resumo automático da conversa por IA e visualizar as mensagens em um leitor (viewer) dentro do próprio registro de interação, no formato semelhante ao do WhatsApp.

Essa funcionalidade é voltada a dois perfis:

  • Administradores, que configuram a integração e o webhook na Meta.

  • Usuários (vendedores), que recebem os registros de interação gerados a partir das mensagens do WhatsApp vinculadas ao seu número.

2) Pré-requisitos

  • Ter um Portfólio Empresarial (Business Portfolio) criado na Meta, com os dados da empresa preenchidos (endereço, site e e-mail).

  • Ter um app criado no Meta for Developers, do tipo Negócios, vinculado a esse portfólio e com o caso de uso WhatsApp habilitado.

  • Ter uma Conta do WhatsApp Business (WABA) conectada a esse app.

  • Ter um número de WhatsApp Business já verificado e em uso no aplicativo oficial (celular), com a versão 2.24.17 ou superior do app instalada, pois é esse número que será vinculado via coexistência (Coexistence) — a integração não substitui o app do WhatsApp Business no celular.

  • Ter em mãos o App ID, o App Secret e um token de acesso válido (de preferência um token permanente, gerado a partir de um usuário de sistema), obtidos na configuração do app na Meta.

  • Ter permissão de administrador na conta Ploomes para acessar a tela de configuração da integração.

  • Ter, no cadastro de Usuário, um campo de telefone (nativo ou personalizado, do tipo texto simples) preenchido e mapeável, que será usado para vincular as mensagens recebidas ao vendedor responsável.

3) Configurando a Integração WhatsApp Coex

A configuração acontece em duas frentes: primeiro na Meta, onde a conta e o webhook do WhatsApp são registrados, e depois no Ploomes, onde os parâmetros de negócio da integração são definidos. A URL de callback usada na Meta é gerada pelo próprio Ploomes — por isso, recomendamos abrir a tela de configuração da integração (seção 3.2) antes de ir até a Meta, para já ter a URL e o Verify Token em mãos.

Se sua empresa já possui um app na Meta com uma Conta do WhatsApp Business (WABA) configurada, você pode pular direto para a etapa 3.1.7. Se está começando do zero, siga as etapas na ordem apresentada.

3.1) Configurando o WhatsApp Business Platform na Meta

Esta etapa acontece inteiramente no Meta for Developers e no Meta Business Suite, fora do Ploomes, e é pré-requisito para que as mensagens do WhatsApp cheguem até a integração.

3.1.1) Criando o portfólio empresarial

  1. Acesse business.facebook.com com sua conta pessoal ou uma conta gerenciada da Meta.

  2. Se sua empresa ainda não tiver um Portfólio Empresarial (Business Portfolio), crie um informando o nome da empresa, seu nome e e-mail comercial.

  3. Complete os dados obrigatórios do portfólio: endereço, site e e-mail da empresa. Esses dados são exigidos mais adiante, na verificação da empresa.

3.1.2) Criando o app na Meta for Developers

  1. Acesse o Painel de Apps da Meta e clique em Criar app.

  2. Informe o nome do app e o e-mail de contato.

  3. Selecione o caso de uso Conectar-se com clientes através do WhatsApp (Connect with customers through WhatsApp) e clique em Avançar.

  4. Selecione o portfólio empresarial criado na etapa 3.1.1 (ou crie um novo, se ainda não tiver feito isso).

  5. Revise os requisitos de publicação exibidos (podem não haver pendências neste momento) e clique em Avançar.

  6. Confirme o nome do app, o caso de uso e o portfólio selecionado e clique em Criar app.

Ao concluir, você é direcionado para o painel Personalizar caso de uso > Conectar-se pelo WhatsApp > Quickstart, dentro do app recém-criado.

3.1.3) Conectando a Conta do WhatsApp Business (WABA)

  1. Na página Quickstart, clique em Começar a usar a API (Start using the API). Você será direcionado à página Configuração da API (API Setup).

  2. Nessa página, conecte o app a uma Conta do WhatsApp Business (WABA):

    • Para usar uma conta já existente, selecione-a na lista.

    • Para criar uma nova, clique em Criar uma conta do WhatsApp Business e siga as instruções para configurar o perfil comercial.

  3. Após conectar, o ID da Conta do WhatsApp Business (WABA ID) é exibido no painel. Guarde esse identificador.

Observação: se o portfólio empresarial acabou de ser criado, uma WABA pode já ter sido gerada automaticamente durante a criação do app. Verifique a conexão na seção Configuração da API antes de prosseguir.

Após realizar a configuração de API, é necessário acessar o menu Configurador de cadastro incorporado.

Então é preciso realizar as verificações - caso ainda estejam pendentes - para o cadastro da Empresa, análise do App e verificação de acesso e integridade da Empresa. Conforme o GIF abaixo, é preciso iniciar o cadastro incorporado escolhendo: configuração de login, versão do cadastro incorporado, versão das informações da sessão, e tipo de recurso (WhatsApp Business). E por fim, entrar com sua conta do Facebook para realizar a autorização do cadastro incorporado.
​

3.1.4) Vinculando um número já usado no WhatsApp Business (coexistência)

Esta etapa é o que caracteriza o modelo de coexistência: ela permite manter o aplicativo do WhatsApp Business funcionando normalmente no celular e, ao mesmo tempo, conectar esse mesmo número à API usada pela integração — sem perder o histórico de conversas.

  1. Nas configurações do Business da Meta em Contas, acesse o menu Contas do WhatsApp. Então vão ser listadas as contas de WhatsApp Business vinculadas ao portfólio empresarial.

  2. Neste menu, clique no botão Adicionar. Serão exibidas as opções de Criar uma nova conta WhatsApp Business ou Vincular uma conta do WhatsApp Business já existente.

  3. Se for criar uma nova conta WhatsApp Business, selecione a primeira opção e avance preenchendo os dados de identificação, número de telefone e verifique o número.

  4. Se for vincular uma conta WhatsApp Business já existente, selecione a outra opção destacada no print. Será aberta uma janela, então informe o número de telefone que já está em uso no app do WhatsApp Business.

  5. Um código de verificação será enviado para o número de telefone informado ao clicar em Continuar. O código expira em 30 segundos. Assim que receber o código no telefone, digite esse código na tela de vinculação da conta do WhatsApp Business no navegador.

  6. Após a validação do código, a conta do WhatsApp será listada como uma das contas vinculadas.

3.1.5) Criando o usuário de sistema e gerando o token de acesso permanente

O token gerado diretamente na tela de Configuração da API (botão Generate access token) é temporário e expira em poucas horas — serve apenas para o teste inicial de envio de mensagem.

Para uso contínuo, gere um token permanente a partir de um usuário de sistema:

  1. Acesse as Configurações do Negócio e clique em Usuários do sistema (System users), no menu lateral.

  2. Clique em Adicionar e crie um novo usuário de sistema, definindo um nome e o papel (Admin ou Funcionário).

  3. Selecione o usuário de sistema criado e clique em Atribuir ativos (Assign assets):

    • Selecione o app criado na etapa 3.1.2 e ative o controle total de Gerenciar app.

    • Selecione a Conta do WhatsApp Business conectada e ative o controle total de Gerenciar contas do WhatsApp Business.

    • Clique em Atribuir ativos para confirmar.

  4. Ainda na tela do usuário de sistema, clique em Gerar token (Generate token):

    • Selecione o app.

    • Defina a validade do token (recomenda-se a opção sem expiração, quando disponível).

    • Marque as permissões business_management, whatsapp_business_messaging e whatsapp_business_management.

    • Clique em Gerar token e copie o valor exibido imediatamente — ele não pode ser visualizado novamente depois.

Guarde esse token de acesso com segurança: é ele que autentica as chamadas feitas em nome do seu número de WhatsApp Business.

3.1.6) Obtendo o App ID e o App Secret

  1. No painel do app, acesse Configurações do app > Básico.

  2. Localize e copie o App ID e o Chave Secreta do Aplicativo (App Secret). Esses dados identificam o app perante a API da Meta.

3.1.7) Configurando o webhook e assinando os eventos de mensagens

  1. No painel do app, acesse o produto WhatsApp > Configuração.

  2. Na seção Webhook, clique em Editar.

  3. Preencha os dois campos solicitados pela Meta:

    • Callback URL: cole a URL de callback gerada pelo Ploomes (disponível na tela de configuração da integração, seção 3.2).

    • Verify Token: informe o mesmo token exibido na tela de configuração da integração no Ploomes.

    Clique em Verificar e salvar. A Meta faz uma chamada de verificação à URL informada; se o Ploomes responder corretamente, o webhook é validado do lado da Meta.

  4. Em Campos do webhook, localize o campo messages e clique em Assinar. Sem essa assinatura, nenhuma mensagem é enviada para o Ploomes.

Observação: a validação da URL de callback é feita inteiramente pela Meta. O Ploomes não exige nenhuma etapa adicional de validação interna — ele apenas exibe um indicador de status (veja seção 3.2) para facilitar o acompanhamento.

3.1.8) Quando a Análise do Aplicativo (App Review) é necessária

Se o app criado for usado apenas para o seu próprio número de WhatsApp Business (ou seja, sua empresa é dona da WABA conectada), o acesso padrão (Standard Access) já é suficiente — não é necessário passar pela Análise do Aplicativo (App Review).

A Análise do Aplicativo só é exigida quando o app precisa acessar WABAs de outras empresas (por exemplo, um parceiro que integra vários clientes com o mesmo app).

Nesse caso, é necessário solicitar Acesso Avançado (Advanced Access) para as permissões whatsapp_business_management e whatsapp_business_messaging, em Análise do Aplicativo > Permissões e recursos, incluindo descrição de uso e gravação de tela para cada permissão solicitada.

3.2) Configurando a integração no Ploomes

  1. Acesse a área de integrações plug and play do Ploomes e localize a entrada Integração WhatsApp Coex.

  2. Autorize a integração. Então será aberta uma janela para informar e preencher as informações do "App Id" e "App Secret" (conforme etapa 3.1.6) e o Token de API gerado para o usuário de sistema (conforme etapa 3.1.5).

  3. Ao ativar, o Ploomes gera automaticamente a URL de callback e o Verify Token (código alfanumérico ao final da URL - omitido no print exemplo abaixo) que devem ser usados na configuração da Meta (seção 3.1). Não é necessário gerar essa URL manualmente.

  4. Copie a URL de callback e o Verify Token exibidos na tela (há um botão de cópia rápida para cada campo) e utilize-os na configuração do webhook na Meta. A configuração é feita em Meus Apps > Casos de uso > WhatsApp > Configuração:

  5. Na tela de configuração do Ploomes, selecione o campo de telefone do objeto Usuário que será usado para vincular as mensagens recebidas ao responsável. Por padrão, o campo nativo de telefone do Usuário é sugerido, mas você pode selecionar um campo personalizado do tipo texto simples. Esse campo é obrigatório — o botão de salvar permanece bloqueado até que um campo válido seja selecionado.

  6. Revise o mapeamento de contato: ao criar um contato a partir de uma mensagem do WhatsApp, o nome do remetente é gravado no campo Nome e o número no campo Telefone do contato. Esse mapeamento é fixo e apenas exibido para conferência, não é editável.

  7. Defina o tempo de inatividade usado para agrupar mensagens em uma mesma conversa (e, consequentemente, em um mesmo registro de interação). O valor é definido em minutos ou horas, com mínimo de 30 minutos e máximo de 24 horas. O padrão sugerido é de 6 horas. Alterar esse valor depois de ativa a integração recalcula os agrupamentos de mensagens em andamento.

  8. Ative ou desative o resumo automático por IA. Quando ativo, é possível configurar um modelo (template) de resumo. Quando desativado, o registro de interação traz apenas a transcrição da conversa, sem resumo.

  9. Salve a configuração.

Observação: a URL de callback é única por conta — todos os administradores visualizam a mesma URL. Não existe uma ação isolada de "revogar" a URL; para gerar uma nova, é necessário desativar e reativar a integração.

4) Utilizando a Integração WhatsApp Coex

4.1) Recebimento de mensagens e criação de registros

Ao receber uma mensagem do WhatsApp de um número já configurado, a integração:

  1. Verifica se o número remetente está na lista de bloqueio (blocklist). Se estiver, a mensagem é descartada silenciosamente e nenhum registro é criado.

  2. Busca um contato correspondente ao número, aplicando a rotina de deduplicação do Ploomes. O resultado pode ser: vínculo com um contato já existente (por correspondência), criação de um novo contato, criação com pendência de revisão, ou bloqueio da criação, conforme a configuração de deduplicação da conta.

  3. Agrupa a mensagem em uma conversa em andamento (respeitando o tempo de inatividade configurado) ou inicia uma nova conversa, caso o agrupamento anterior já tenha sido encerrado.

  4. Gera ou atualiza o registro de interação vinculado ao contato e ao usuário responsável pelo número de telefone mapeado.

  5. Se o resumo automático por IA estiver ativo, gera o resumo da conversa na descrição do registro; caso contrário, grava a transcrição da conversa.

4.2) Visualizando as conversas

Dentro do registro de interação gerado, um leitor (viewer) exibe as mensagens da conversa em um formato semelhante ao do WhatsApp, junto com o resumo por IA (quando habilitado).

4.3) Vínculo com Negócios (Cards)

Quando o contato vinculado à conversa está associado a mais de um Negócio, a integração prioriza o vínculo do registro de interação ao Negócio em que o usuário responsável pelo número aparece como responsável; na ausência desse critério, prioriza o Negócio em que ele aparece como colaborador. Em caso de empate, prevalece o Negócio com a atualização mais recente.

5) Limitações

  • Sem suporte a grupos de WhatsApp: apenas conversas individuais são processadas pela integração.

  • Atribuição de responsável fixa na criação: o responsável pelo registro de interação é definido no momento da criação e não é recalculado depois, mesmo que o campo de telefone mapeado no Usuário seja alterado posteriormente.

  • Campo de telefone excluído: se o campo mapeado para vinculação for excluído do cadastro de Usuário, novos registros de interação deixam de ser criados até que um novo campo válido seja mapeado.

  • Usuário inativo: se o usuário responsável pelo número estiver inativo no Ploomes, nenhum registro de interação é criado para as mensagens recebidas.

  • Mídias com validade limitada: imagens, áudios e documentos recebidos são referenciados pela URL fornecida pela própria Meta, que expira após aproximadamente duas semanas. A integração não realiza cópia própria dos arquivos de mídia.

  • Limite de capacidade: a integração opera dentro do limite geral de capacidade da conta (atualmente 200.000 entidades, como contatos). Ao atingir o limite, é necessário liberar espaço (excluindo históricos antigos) ou contratar capacidade adicional.

  • Números fora do padrão internacional: números sem DDI/DDD no formato padrão podem não ser reconhecidos corretamente pela validação de telefone da integração.

  • Sem revogação isolada da URL de callback: para invalidar a URL atual, é necessário desativar e reativar a integração — não há um botão de revogação separado.

  • Limite de envio da Meta: números conectados por coexistência têm um limite de 20 mensagens por segundo definido pela própria Meta.

  • Histórico sincronizado limitado: a sincronização inicial de histórico do WhatsApp Business app cobre apenas os últimos 180 dias; conversas em grupo não são sincronizadas.

  • Inatividade do número na Meta: a Meta desconecta automaticamente a coexistência se o app do WhatsApp Business no celular (dispositivo principal) ficar cerca de 14 dias sem uso, ou se um dispositivo companion ficar cerca de 30 dias sem uso.

  • Recursos do app afetados pela coexistência: ao ativar a coexistência, alguns recursos do aplicativo do WhatsApp Business deixam de funcionar ou passam a ser somente leitura, como mensagens que somem, visualização única, localização em tempo real, chamadas de voz e vídeo, catálogo, pedidos, status e listas de transmissão.

6) F.A.Q.

Preciso criar uma nova URL de callback manualmente?

Não. A URL de callback e o Verify Token são gerados automaticamente pelo Ploomes assim que você ativa a integração. Basta copiá-los e colá-los na configuração do webhook na Meta.

Como sei se o webhook está funcionando?

A tela de configuração exibe o status Pendente de validação até que a primeira mensagem seja recebida com sucesso, e passa para Validado a partir daí.

A integração funciona com grupos de WhatsApp?

Não. Somente conversas individuais são suportadas.

O que acontece se eu excluir o campo de telefone usado no mapeamento?

A integração deixa de criar novos registros de interação até que um novo campo de telefone válido seja selecionado na tela de configuração.

Posso trocar o campo de telefone depois que a integração já está ativa?

Sim, mas o responsável de registros já criados não é recalculado — a troca vale apenas para novas mensagens recebidas a partir da alteração.

O resumo por IA é obrigatório?

Não. Você pode desativar o resumo por IA a qualquer momento; nesse caso, o registro de interação traz apenas a transcrição da conversa.

Por quanto tempo consigo acessar as mídias recebidas pelo WhatsApp?

As mídias usam a URL fornecida pela Meta, que expira em aproximadamente duas semanas. Após esse prazo, o conteúdo pode deixar de estar acessível.

Todos os administradores veem a mesma URL de callback?

Sim. A URL é única por conta, não por usuário.

Como faço para gerar uma nova URL de callback?

Desative e reative a integração. Uma nova URL será gerada automaticamente nesse processo.

Preciso passar pela Análise do Aplicativo (App Review) da Meta para usar a integração?

Não, se o app na Meta for usado apenas para o número da sua própria empresa. A Análise do Aplicativo só é exigida quando o app precisa acessar Contas do WhatsApp Business de outras empresas.

Posso conectar um número que já uso no aplicativo do WhatsApp Business no celular?

Sim. Esse é justamente o modelo de coexistência: o número continua funcionando no aplicativo do celular e passa a enviar as mensagens também para a integração, sem perder o histórico. É necessário manter o app do celular atualizado (versão 2.24.17 ou superior) e concluir a sincronização inicial em até 24 horas.

7) Glossário

  • Coexistência (Coexistence): modelo da Meta que permite vincular um número de WhatsApp Business já em uso no aplicativo oficial a uma conta de negócios, sem exigir migração para um número exclusivo de API.

  • Portfólio Empresarial (Business Portfolio): conta administrativa da Meta que reúne os ativos de uma empresa, como apps, contas de anúncio e Contas do WhatsApp Business.

  • App (Meta for Developers): aplicação registrada no painel de desenvolvedores da Meta, usada para autenticar chamadas de API e receber webhooks.

  • WABA (WhatsApp Business Account): Conta do WhatsApp Business — o ativo da Meta que agrupa números de telefone, modelos de mensagem e configurações de webhook de uma empresa.

  • App ID / App Secret: identificador e chave secreta do app na Meta, usados para autenticar integrações e trocar tokens.

  • Usuário de sistema (System User): usuário técnico criado nas Configurações do Negócio da Meta, usado para gerar tokens de acesso permanentes sem depender de login de uma pessoa.

  • Token de acesso: credencial usada para autenticar chamadas à API da Meta em nome de um app ou usuário de sistema. Pode ser temporário (poucas horas) ou permanente.

  • Análise do Aplicativo (App Review) / Acesso Avançado (Advanced Access): processo de revisão da Meta exigido quando um app precisa acessar Contas do WhatsApp Business de outras empresas, além da própria.

  • Cadastro Incorporado (Embedded Signup): fluxo da Meta usado para vincular contas, portfólios e números de WhatsApp Business a um app, incluindo o processo de coexistência.

  • Webhook: mecanismo pelo qual a Meta envia automaticamente as mensagens recebidas no WhatsApp para a URL de callback configurada.

  • URL de callback: endereço gerado pelo Ploomes que recebe as notificações de webhook enviadas pela Meta.

  • Verify Token: token usado pela Meta para validar a URL de callback informada na configuração do webhook.

  • Blocklist: lista de números bloqueados cujas mensagens são descartadas automaticamente, sem gerar registro.

  • Deduplicador: rotina do Ploomes que verifica se já existe um contato correspondente ao número remetente antes de criar um novo.

  • Registro de interação: registro criado no Ploomes a partir de uma conversa do WhatsApp, vinculado ao contato e ao usuário responsável.

  • Tempo de inatividade: intervalo configurado que determina quando uma nova mensagem inicia uma nova conversa (e um novo registro de interação) em vez de ser agrupada à conversa anterior.

  • Resumo por IA: resumo automático gerado a partir da conversa do WhatsApp, exibido na descrição do registro de interação.

  • Viewer: área do registro de interação que exibe as mensagens da conversa em formato semelhante ao do aplicativo WhatsApp.

Artigos relacionados
Respondeu à sua pergunta?