WhatsApp Coexistence API — o guia completo

Odoo Community, on-premise. O Odoo Online (SaaS) não aceita módulos de terceiros. A instância precisa estar acessível pela internet por HTTPS, porque a Meta entrega as mensagens recebidas a um webhook no seu próprio domínio. Não é preciso nada do Enterprise: nem o app nativo de WhatsApp nem assinatura do Enterprise. Também roda sobre o Enterprise, mas foi feito para o Community.

Uma conexão WABA API não precisa de Tech Provider: basta o seu próprio app de desenvolvedor da Meta, e nada passa pela RC Studio.

Mantenha o número no celular. Coloque o Odoo por cima.

O caminho normal para a Cloud API do WhatsApp pede que você abra mão do número: uma vez migrado, ele deixa de funcionar no app WhatsApp Business do celular. Coexistence é a resposta oficial da Meta, e este módulo a traz para o Odoo Community. Você escaneia um QR code e, a partir desse momento, o mesmo número funciona nos dois lugares: sua equipe continua respondendo pelo celular e o Odoo vê tudo.

O que você recebe

• Coexistence, ou uma conexão WABA API. Conecte o número do seu app WhatsApp Business por QR code, ou uma conexão WABA API com o seu próprio app da Meta. Vários números em uma base de dados, cada um com seus operadores e suas empresas.
• Uma caixa de entrada feita para responder. Filtros de busca, não lidas, minhas e fechadas, seletor por número, atualização ao vivo, ticks de entrega, mídia, respostas citadas, reações, atribuição, e as mensagens que sua equipe envia pelo celular espelhadas na mesma conversa.
• Documentos a partir de qualquer registro. Uma ação Enviar por WhatsApp em contatos, cotações, faturas, entregas, leads, tarefas, eventos, compromissos, pedidos de compra e de PDV. O modelo é preenchido com o registro e o relatório PDF viaja como cabeçalho do documento.
• Modelos sincronizados com a Meta. Cabeçalho, corpo, rodapé e botões como a Meta os define. Cada placeholder é mapeado a um campo do registro, a um valor fixo, a um valor pedido no envio ou ao link do portal. Uma biblioteca de exemplos para os apps que você tem instalados.
• Envios automáticos. Uma ação de servidor Enviar modelo de WhatsApp que você dispara de qualquer regra de automação.
• Perfis, descadastro, novas tentativas. Os operadores só veem os números a que estão atribuídos. Um cliente que responde STOP entra na lista de bloqueio. Os envios com falha são tentados de novo, e cada mensagem mantém seu status e código de erro da Meta. Nada é apagado nunca.

Um passeio em cinco telas

Vários números em uma caixa de entrada, o ícone que os distingue, o filtro por número e um modelo enviado a partir de uma cotação.

Requisitos

Duas formas de ter permissão para usar o Coexistence

O WhatsApp Coexistence é ativado pelo Embedded Signup da Meta, que só funciona com um app registrado na Meta como Tech Provider e aprovado para o recurso WhatsApp Business App Onboarding. Um app de desenvolvedor comum não consegue. Há duas formas de cumprir esse requisito:

Com uma licença da RC Studio. Você compra uma chave de licença, cola no Odoo e conecta escaneando um QR code. Nada para registrar na Meta, sem revisão de app, sem liberação de domínios. A licença é cobrada separadamente deste módulo e não está incluída na compra.

Com o seu próprio app de Tech Provider, ou o de um terceiro. Este módulo funciona com qualquer um deles. Você informa o App ID, o App Secret e o Login Configuration ID que o seu provedor lhe dá, e a conexão roda pelo app da Meta dele em vez do da RC Studio. Essas credenciais são emitidas por esse provedor, não pela RC Studio. A RC Studio não pode obtê-las por você e não se responsabiliza se o seu provedor não as entregar, revogá-las, cobrar à parte por elas ou não ter sido aprovado pela Meta para o recurso WhatsApp Business App Onboarding. Confirme com o seu provedor que você receberá um App ID, um App Secret e uma Login Configuration de coexistence antes de comprar este módulo.

Instalar o módulo

• Garanta que os pacotes Python phonenumbers e requests estejam disponíveis para o Odoo. Os dois fazem parte do requirements.txt do próprio Odoo, então uma instalação padrão já os tem; o Odoo se recusa a instalar o módulo se faltarem (um módulo do Odoo não pode rodar pip por você). Se precisar, instale-os no ambiente em que o Odoo roda e reinicie o Odoo.
• Descompacte o módulo na sua pasta de addons e reinicie o serviço do Odoo.
• Configurações → Apps → Atualizar lista de apps, busque «WhatsApp» e instale WhatsApp Coexistence API.
• Dê aos seus usuários o direito de acesso WhatsApp / Operador ou Gerente.

Modo A · Coexistence com licença da RC Studio (recomendado)

Toda a configuração é: colar a chave, clicar em Conectar, escanear o QR. Nada para registrar na Meta, sem revisão de app e sem domínio para liberar, porque o diálogo do Facebook roda na própria página da RC Studio.

As três telas que você realmente vê, no modo licença

A Meta permite uma única sincronização de contatos e uma única de histórico por conexão. Se falharem, a única forma de repeti-las é desconectar o número e conectá-lo de novo com um QR code novo.

Modo B · Coexistence com o seu próprio app de Tech Provider

Funciona com o seu próprio app ou com o de qualquer outro provedor. Nos dois casos o app precisa estar aprovado pela Meta para o recurso WhatsApp Business App Onboarding, e o App ID, o App Secret e o Login Configuration ID são entregues a você por esse provedor. A RC Studio não pode obtê-los e não se responsabiliza se o provedor não os entregar.

• Escolha Coexistence e Seu próprio app de Tech Provider da Meta.
• Preencha App ID, App Secret e Login Configuration ID do seu app.
• Adicione o seu domínio do Odoo ao app da Meta, em Domínios do app e Domínios permitidos para o SDK de JavaScript. Esta etapa não tem API e precisa ser feita à mão para cada domínio.
• Clique em Conectar por Coexistence e siga com o QR.

No modo B não há janela da RC Studio: o diálogo do Facebook abre direto da sua própria página do Odoo, sobre o seu próprio app.

Modo C · Conexão WABA API

Sem Tech Provider. No seu app de desenvolvedor da Meta com o produto WhatsApp, copie o App ID, o App Secret, o WhatsApp Business Account ID, o Phone Number ID e um Access Token permanente (um token de usuário do sistema com as permissões do WhatsApp) no número, escolha Conexão WABA API (Cloud API) e clique em Testar conexão.

Webhook

Cada número tem sua própria Callback URL e seu Verify Token na aba Webhook. No modo coexistence, o Odoo os registra na Meta como parte da conexão do número. Com uma conexão WABA API, ou você clica em Inscrever webhook para que o Odoo os registre na conta do WhatsApp Business, ou cola à mão no app da Meta em WhatsApp → Configuração → Webhooks e se inscreve nos campos messages e message_template_status_update. As entregas são verificadas contra a assinatura da Meta (seu App Secret) ou, no modo licença, contra a URL secreta que só a Meta e o seu Odoo conhecem.

Modelos

Clique em Sincronizar modelos em um número conectado para importar os modelos aprovados na Meta, ou em Carregar modelos de exemplo para obter rascunhos para os apps que você tem instalados (cotação enviada, pedido confirmado, fatura disponível, entrega a caminho, inscrição em evento, lembrete de compromisso, recibo, pedido de compra, acompanhamentos de lead e de tarefa). Revise um rascunho, mapeie seus placeholders na aba Placeholders e clique em Enviar para a Meta; o Odoo fica sabendo do resultado da revisão pelo webhook.

Perfis

A caixa de entrada

WhatsApp → Caixa de entrada. Conversas à esquerda, atividade mais recente primeiro, com busca, os filtros Todas / Não lidas / Minhas / Fechadas e, quando há mais de um número, um seletor. A conversa à direita: responda com texto, emoji e anexos, cite uma mensagem e veja os ticks de entrega.

Sem nada digitado, o botão Enviar vira um microfone: aperte para gravar uma nota de voz; o cliente a recebe como mensagem de voz, com o ícone do microfone e a sua foto de perfil, reproduzida direto do balão e não como arquivo para baixar. A única coisa que nenhum remetente por API consegue adicionar é a forma de onda, que só o telefone que grava calcula. Chrome, Edge e Firefox não precisam de nada instalado; no Safari o servidor precisa ter ffmpeg. As notas de voz que o cliente envia tocam na conversa.

As mensagens novas chegam ao vivo; o ícone do WhatsApp na barra superior mostra quantas conversas estão esperando. Atribuir a mim e Fechar mantêm a lista limpa; o contato e os documentos a partir dos quais se escreveu ao cliente estão a um clique.

Uma conversa por cliente e número

Tudo o que um cliente escreve e tudo o que você envia para ele, pela caixa de entrada, por uma cotação ou por uma automação, cai na mesma conversa daquele número comercial. O contato é identificado pelo número de telefone; se o cliente escreve para dois dos seus números, são duas conversas de propósito, distinguidas pelo ícone do número. No modo coexistence, as respostas que sua equipe envia pelo celular aparecem na conversa marcadas como «pelo celular».

Vários números, uma caixa de entrada

Dê a cada número comercial um ícone no seu formulário. O ícone aparece como selo em cada conversa daquele número, então uma conversa de vendas e uma de suporte com o mesmo cliente se distinguem num relance. O seletor no topo da lista mostra todos os números ou só um, e os operadores só veem os números em que estão listados.

Enviar um documento

Em um contato, uma cotação, uma fatura, uma entrega, um lead, uma tarefa, uma inscrição em evento, um compromisso, um pedido de compra ou um recibo, abra o menu Ação e escolha Enviar por WhatsApp; o mesmo atalho fica ao lado de cada campo de telefone. Escolha o número e o modelo, preencha o que o modelo pedir, confira a pré-visualização e envie. O relatório PDF do modelo vai como documento, e fica uma nota no chatter do registro com link para a conversa. Em uma visão de lista, selecione vários registros e a mesma ação envia para todos.

Envios automáticos

Em Configurações → Técnico → Regras de automação, adicione uma ação do tipo Enviar modelo de WhatsApp e escolha o modelo. Cada registro que atender à regra recebe sua mensagem, preenchida com o registro, sem ninguém clicar.

A janela de 24 horas e o descadastro

Vinte e quatro horas depois da última mensagem do cliente, o WhatsApp só permite modelos aprovados. O editor avisa e oferece Enviar um modelo, que reabre a conversa. Se um cliente responder STOP, UNSUBSCRIBE ou BAJA (a lista você muda nas Configurações), o número entra na lista de bloqueio e nada mais é enviado para ele até ser removido.

Estados e novas tentativas

WhatsApp → Registro de mensagens guarda cada mensagem com o seu estado: na fila, enviada, entregue, lida ou com falha, com o código de erro da Meta quando há. As falhas temporárias são tentadas de novo por um cron a cada cinco minutos; as definitivas podem ser reenviadas pela lista. As mensagens nunca são apagadas: o registro e as conversas são o seu histórico.

Perguntas frequentes

Preciso ser Tech Provider da Meta? Só para coexistence. O Embedded Signup da Meta para o app WhatsApp Business funciona por um app de Tech Provider aprovado para WhatsApp Business App Onboarding. Ou você usa o app da RC Studio com uma chave de licença, ou se registra como Tech Provider, ou usa outro provedor que lhe entregue o App ID, o App Secret e a Login Configuration. Uma conexão WABA API não precisa de nada disso: basta o seu próprio app de desenvolvedor da Meta.

Funciona no Odoo Online (SaaS) ou no Odoo.sh? O Odoo Online não aceita módulos de terceiros, então não. Este módulo é feito para Odoo Community on-premise. Ele depende só de módulos do Community, então também instala em um projeto do Odoo.sh; o suporte ao Odoo.sh, porém, não faz parte do que testamos.

O celular continua funcionando depois de conectar? Sim, é isso que coexistence significa. O número continua ativo no app WhatsApp Business; o Odoo recebe tudo pela Cloud API e também pode enviar. As mensagens enviadas pelo celular são espelhadas no Odoo.

Onde as conversas ficam? O Discuss participa? Nos modelos próprios de conversa e mensagem do módulo, mostrados na sua própria caixa de entrada. O Discuss não é usado para as conversas de WhatsApp.

Meus dados passam pela RC Studio? Não. Nos três modos as mensagens viajam diretamente entre a Meta e o seu Odoo. Com uma licença da RC Studio, o nosso serviço participa apenas na conexão de cada número: troca a autorização da Meta pelo token de acesso, entrega-o ao seu Odoo e registra na Meta o endereço do seu Odoo como destino das entregas. A partir daí a Meta entrega cada mensagem diretamente à sua instância, e o envio sai do seu Odoo para a Meta com o seu próprio token. A RC Studio não recebe nem armazena conteúdo de mensagens; guarda apenas uma cópia criptografada do token e os dados de conexão do número até você desconectá-lo.

Quanto a Meta cobra pelas mensagens? A Meta cobra por mensagem entregue. As mensagens de modelo têm uma tarifa que depende da categoria (marketing, utilidade, autenticação) e do país do cliente. A partir de 1º de outubro de 2026 a Meta passa a cobrar também as respostas livres que você envia dentro da janela de 24 horas (as que sua equipe digita na caixa de entrada), na mesma tarifa das mensagens de utilidade e autenticação naquele país; até lá são gratuitas. Receber mensagens continua gratuito. As tarifas exatas estão na página de preços da Meta. A RC Studio não cobra por mensagem.

Posso enviar um PDF? Uma localização? Uma nota de áudio? Pela caixa de entrada, dentro da janela de 24 horas: texto, imagens, vídeos, áudio, documentos e respostas citadas. A partir de um registro: um modelo cujo cabeçalho de documento seja o relatório PDF do registro, ou um arquivo fixo. Localizações, figurinhas, reações e cartões de contato são recebidos e exibidos; localizações enviadas só são possíveis como cabeçalho de modelo.

Vários números, várias empresas? Sim. Cada número comercial tem seus próprios operadores e empresas permitidas, seus próprios modelos e suas próprias conversas. Os operadores só veem os números em que estão listados.

Quais versões do Odoo são suportadas e em que idiomas está a interface? Odoo Community 17.0, 18.0, 19.0 e 20.0; cada versão é comprada separadamente na loja do Odoo. A interface vem em inglês, espanhol, português, italiano, francês, alemão e árabe.

O suporte está incluído? Sim, para qualquer pessoa que compre o módulo. Bugs são corrigidos sem custo; recursos novos e a configuração do lado da Meta são orçados à parte.

Suporte

O suporte está incluído para qualquer pessoa que compre o módulo. A instalação, a configuração do lado da Meta e a licença de Tech Provider da RC Studio podem ser contratadas separadamente. Use a página de suporte deste módulo no Odoo Apps para tudo relacionado à sua compra: chega direto a nós e mantém o histórico vinculado à sua licença.

Trânsito de dados: mensagens e mídias viajam diretamente entre a sua instância do Odoo e a Cloud API da Meta, em qualquer modo de conexão. Com licença da RC Studio, o serviço de Tech Provider da RC Studio participa apenas na conexão do número: emite o token de acesso da Meta e registra o endereço do seu Odoo como destino das entregas. A RC Studio não recebe nem armazena conteúdo de mensagens. Política de privacidade.

WhatsApp é uma marca da Meta Platforms, Inc. A RC Studio não é afiliada, endossada nem patrocinada pela Meta. Este módulo é publicado sob a Odoo Proprietary License v1.0 (OPL-1).