Pular para o conteúdo principal
Um número da API Oficial (Cloud API) pode estar conectado a mais de uma plataforma ao mesmo tempo: a D-API e um CRM, um chatbot, outra API. Na Meta, cada plataforma é um parceiro (um app). Esta página explica como os dois convivem sem um atrapalhar o outro.
Resumo em três frases. Os dois parceiros podem estar no número ao mesmo tempo, mas cada conversa tem um único dono que responde. Quem decide quem é dono de quê é a empresa dona do número, no Meta Business Suite. A D-API mostra o papel dela, recebe cópia das conversas dos outros (standby) e, quando autorizada, assume uma conversa a qualquer momento.

Por que isso existe

Sem nenhuma regra, todo parceiro conectado recebe todas as mensagens e todos podem responder. Na prática isso vira bagunça: dois robôs respondendo o mesmo cliente, ou um parceiro respondendo uma conversa que o outro estava atendendo. A Meta resolveu isso com o Conversation Routing (roteamento de conversas): a empresa define qual parceiro atende cada tipo de conversa, e a Meta entrega a mensagem só para ele.
Quando um segundo parceiro entra na conta, a Meta pode criar uma configuração de roteamento automaticamente, a partir dos parceiros que já estavam lá. Se a D-API (ou o outro parceiro) parou de receber mensagens ou passou a receber o erro 131070 logo depois de uma nova conexão, é isso. Confira a configuração no Meta Business Suite e o papel da D-API.

Conceitos

O que cada parceiro pode fazer

Templates sempre podem ser enviados, por qualquer parceiro, sendo dono ou não. Enviar um template não muda o dono da conversa. O que pode mudar é a resposta do cliente: se ele tocar num botão do template, a conversa é roteada de novo pela entrada de marketing/utilidade.

1. Descubra a situação do número

Uma chamada mostra se há outros parceiros e qual é o papel da D-API:
SUA_CONEXAO é o id da conexão ou o id da sessão (cloud-…).
Resposta
string
O resumo. Um de três valores:
  • exclusive: só a D-API está na conta. Tudo funciona como sempre.
  • shared_without_routing: há outro parceiro e nenhum roteamento. Os dois recebem todas as mensagens e os dois podem responder. Configure o roteamento para evitar respostas duplicadas.
  • routed: o roteamento está ativo. O que a D-API faz depende de roles e isStandby.
string[]
Entradas em que a D-API é a principal: customer_service (atendimento), ctwa (anúncio de clique para WhatsApp), marketing, utility, calls (ligações). Contém escalation se a D-API é o parceiro de escalonamento. Vazio quando a D-API não é principal de nada.
boolean
true se a empresa deu à D-API a visão standby (cópia das conversas dos outros parceiros).
boolean
true se a D-API pode assumir qualquer conversa. Atalho para roles conter escalation.
object[]
Parceiros (apps) conectados à conta. isCurrentApp: true marca a D-API.
number
Quantos parceiros além da D-API.
Esta rota consulta a Meta na hora, e a Meta limita a frequência. Use em telas de configuração ou depois de um erro 131070. Não chame antes de cada envio.

2. Configure o roteamento no Meta Business Suite

A configuração é da empresa dona do número e só existe na interface da Meta. Nenhum parceiro (nem a D-API) consegue configurar por API.
1

Aceite os termos

Standby, escalonamento e troca de dono exigem que a empresa aceite os Termos de Serviço de Meta Business Agents e da Plataforma. Sem isso, só o roteamento básico funciona.
2

Abra o roteamento de conversas

No Meta Business Suite, abra as configurações da conta do WhatsApp e procure Roteamento de conversas (Conversation Routing). Dá para configurar a conta inteira ou um número específico (a configuração do número tem prioridade).
3

Escolha o principal de cada entrada

Para cada uma das cinco entradas, escolha o parceiro que atende. Em marketing e utilidade existe a opção “Rotear para quem enviou”: a resposta do cliente vai para o parceiro que enviou o template.
4

Escolha o parceiro de escalonamento (opcional)

No máximo um. Ele pode assumir qualquer conversa.
5

Dê a visão standby (opcional)

Vem desligada por padrão. Marque os parceiros que devem receber cópia das conversas que não são deles.
6

Salve e confira

Chame GET /routing e veja se o papel da D-API é o esperado.

3. Casos de uso

Cenário. O cliente usa outra plataforma no dia a dia e quer a D-API pronta para assumir se ela falhar, sem interferir no funcionamento dela.Configuração no Meta Business Suite:Resultado em GET /routing: situation: "routed", roles: ["escalation"], isStandby: true.No dia a dia:
  • O outro parceiro recebe e responde tudo, normalmente.
  • A D-API recebe cópia de tudo pelo webhook, com is_standby: true: mensagens do cliente e o que o outro parceiro enviou (fromMe: true). O histórico fica completo no painel.
  • Flows, automações e agentes de IA da D-API não disparam nessas cópias.
  • A D-API pode enviar templates quando quiser.
Quando a outra plataforma cair, a D-API assume a conversa de duas formas:
  • Explícita: chame take.
  • Implícita: envie uma mensagem normal pela D-API. A Meta transfere a conversa na hora, e o outro parceiro recebe o aviso de que perdeu a conversa.
Depois de assumir, as próximas mensagens daquele cliente chegam à D-API como mensagens normais (sem is_standby), e flows e automações voltam a funcionar nela.Para devolver a conversa ao outro parceiro, use pass com targetRole: "customer_service", ou release para deixar a próxima mensagem do cliente decidir pela configuração.
Como a D-API é o parceiro de escalonamento, qualquer mensagem de atendimento enviada por ela (pela API, pelo painel, por um flow agendado) assume a conversa do outro parceiro. Se a sua integração não deve assumir conversas, envie apenas templates enquanto a outra plataforma estiver no ar.

4. Trocar o dono de uma conversa

Uma rota, três ações. Sempre para uma conversa (um cliente).
string
obrigatório
take, pass ou release.
string
obrigatório
Telefone do cliente. Aceita qualquer formatação ou JID (5551999999999@s.whatsapp.net).
string
Só com pass. Para qual entrada entregar: customer_service, ctwa, marketing, utility, escalation ou ai_agent (Meta Business Agent, se ativo na conta). Sem ele, o pass vai para o parceiro de escalonamento.
string
Texto livre, até 2000 caracteres, entregue ao parceiro que recebe a conversa.

Assumir (take)

A D-API toma a conversa de quem for o dono. Só funciona se a D-API for o parceiro de escalonamento.
Resposta
O parceiro que perdeu a conversa é avisado pela Meta.

Entregar (pass)

A D-API, sendo a dona, entrega a conversa para outro parceiro.
O pass é recusado se a conversa estiver livre, se a D-API não for a dona, se a entrada escolhida não tiver principal ou se o destino já for o dono.

Soltar (release)

A D-API, sendo a dona, deixa a conversa livre. A próxima mensagem do cliente é roteada de novo pela configuração da empresa. Soltar uma conversa que já está livre não dá erro.
O release não gera webhook para ninguém: não há novo dono até o cliente escrever de novo.

Erros

Exemplo de erro

5. Webhooks

Cópias de conversas de outros parceiros: is_standby

As cópias chegam nos mesmos eventos de sempre, com um campo a mais: is_standby: true. Nas mensagens normais o campo não aparece.
Cliente escreveu numa conversa do outro parceiro
O outro parceiro enviou um template
Templates enviados pelo outro parceiro chegam com type: "template" e o texto [Template nome]: parâmetros em message. Mensagens interativas chegam com type: "interactive" e o texto do corpo.
Não responda mensagens com is_standby: true. A conversa é de outro parceiro: a resposta é recusada com 131070 ou, se a D-API for o escalonamento, toma a conversa do outro parceiro.

Troca de dono: conversation.control_changed

Disparado quando uma conversa muda de dono envolvendo a D-API:
  • type: "control_passed": outro parceiro entregou a conversa à D-API. A D-API agora é a dona (is_owner: true).
  • type: "control_taken": o parceiro de escalonamento tomou a conversa da D-API. A D-API deixou de ser dona (is_owner: false).
string
control_passed ou control_taken.
boolean
true: a D-API passou a ser a dona da conversa. false: deixou de ser.
string | null
Papel de quem era o dono (customer_service, ctwa, marketing, utility, escalation, ai_agent).
string | null
Papel de quem passou a ser o dono.
string | null
Texto enviado por quem fez a troca.
string | null
Resumo da conversa gerado pela Meta, quando ela envia (só em control_passed).

6. Envio numa conversa de outro parceiro: erro 131070

Se a D-API tentar enviar texto livre ou mídia numa conversa que não é dela (e não for o escalonamento), a Meta recusa. A rota de envio responde:
O que fazer:
  1. Precisa falar com o cliente agora? Envie um template.
  2. A D-API é o escalonamento? Assuma com take (ou o próprio envio já assume, sem erro).
  3. Senão, peça ao parceiro dono um pass para a D-API, ou mude a configuração no Meta Business Suite.
Conversa livre (sem dono) também recusa texto livre: a próxima mensagem do cliente é que define o dono. Para puxar uma conversa livre, envie um template de marketing ou utilidade: se a empresa configurou essa entrada como “Rotear para quem enviou”, a resposta do cliente traz a conversa para a D-API.

Perguntas frequentes

Não. O papel da D-API é o que a empresa configurou no Meta Business Suite, e pode ser diferente por número. A empresa pode mudar quando quiser: tornar a D-API principal de uma ou de todas as entradas, tirar o standby, ou remover o outro parceiro (aí o roteamento some e tudo volta ao normal). Use GET /routing para ver o papel atual.
Sim, no mesmo número e ao mesmo tempo, mas não na mesma conversa ao mesmo tempo: cada conversa tem um dono. As duas podem enviar templates livremente.
GET /routing: otherAppsCount maior que zero e a lista em subscribedApps.
Não. Cópias com is_standby: true vão para o histórico e para o webhook, mas não disparam flows, automações nem agentes de IA. Eles voltam a rodar quando a D-API vira dona da conversa.
Sim, quando a D-API tem a visão standby: as mensagens do cliente e as respostas do outro parceiro entram no histórico da conversa.
Não. Mensagens enviadas pelo outro parceiro não entram na cobrança da D-API. A cobrança da Meta por template é de quem enviou.
As cópias standby não são repassadas à Datacrazy: o formato dela não tem como marcar que a mensagem é só uma cópia, e a automação de lá responderia uma conversa que não é da D-API.
Até ser entregue, solta ou assumida, ou até 24h sem mensagem do cliente. Depois disso ela fica livre, e a próxima mensagem do cliente escolhe o dono de novo pela entrada.
A D-API não registra de novo um número que já está ativo na API Oficial com outro parceiro, para não trocar a verificação em duas etapas que ele configurou. Mas a Meta pode criar uma configuração de roteamento automática quando o segundo parceiro entra. Depois de conectar, confira a configuração no Meta Business Suite.