api oficial · tech provider e roteamento
API oficial com mais de um parceiro: seu SaaS no número que já tem outra plataforma
Entre no número do cliente mesmo quando ele já usa outro CRM ou bot na API oficial com mais de um parceiro: a D-API mostra o papel do seu SaaS, recebe cópia das conversas e troca o dono quando autorizada.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Situação do número em uma chamada
GET /routing diz se há outros parceiros, se o roteamento está ativo e qual é o papel da D-API em cada entrada de conversa.
Cópia das conversas dos outros
Com a visão standby, as mensagens do outro parceiro chegam ao seu webhook marcadas com is_standby, sem disparar automações.
Troca de dono por API
take, pass e release em POST /thread-control. O seu SaaS assume, entrega ou solta uma conversa com um cliente específico.
Template sempre liberado
Na Meta, qualquer parceiro pode enviar template, dono ou não da conversa. Notificação do seu SaaS não depende do roteamento.
A API oficial com mais de um parceiro é o cenário em que o mesmo número da Cloud API está conectado a duas plataformas ao mesmo tempo, por exemplo o seu SaaS e o CRM que o cliente já usava. Ele aparece cedo na venda para contas maiores: o cliente quer o seu produto de agendamento, de cobrança ou de agente de IA, mas não vai desligar a ferramenta de atendimento que o time usa há anos. Na API oficial, cada plataforma entra na conta como um parceiro, e a D-API sabe dividir as conversas com os outros sem um atrapalhar o outro.
Como a Meta organiza vários parceiros
A D-API é Tech Provider da Meta, e entra na WABA do cliente como um app parceiro. Outras plataformas entram da mesma forma. Sem regra nenhuma, todos os parceiros recebem todas as mensagens e todos podem responder, o que vira dois robôs falando com o mesmo cliente. A Meta resolveu isso com o Conversation Routing: a empresa dona do número define quem atende cada tipo de conversa, e a Meta entrega a mensagem só para ele.
O vocabulário que o seu time precisa conhecer:
| Termo | O que significa para o seu SaaS |
|---|---|
| Dono | O parceiro que atende aquela conversa. Só ele recebe a mensagem como normal e envia texto livre na janela de 24 horas |
| Entrada | Por onde a conversa começou: atendimento, anúncio de clique para WhatsApp, resposta a template de marketing, resposta a template de utilidade ou ligação |
| Principal | O parceiro configurado para uma entrada. Vira dono quando a conversa começa por ela |
| Standby | O observador: recebe cópia das conversas dos outros, sem responder |
| Escalonamento | No máximo um por conta. Pode assumir qualquer conversa a qualquer momento |
| Conversa livre | Sem dono, depois de 24 horas sem mensagem do cliente ou quando o dono solta |
Um ponto que tranquiliza o cliente: a configuração é da empresa dona do número e só existe no Meta Business Suite. Nenhum parceiro, nem a D-API, configura o roteamento por API. O seu SaaS lê o resultado e age dentro do papel que recebeu.
Qual é o papel do seu SaaS no número
Antes de prometer qualquer automação, o seu painel precisa saber em que situação o número está. Uma chamada responde:
curl https://api.d-api.cloud/api/v1/connections/cloud-api/CONNECTION_ID/routing \
-H "Authorization: SUA_API_KEY"
{
"success": true,
"data": {
"situation": "routed",
"routingEnabled": true,
"roles": ["escalation"],
"isStandby": true,
"isEscalation": true,
"subscribedApps": [
{ "id": "1234567890", "name": "D-API", "isCurrentApp": true },
{ "id": "9876543210", "name": "Outro CRM", "isCurrentApp": false }
],
"otherAppsCount": 1
}
}
O campo situation resume tudo. exclusive significa que só a D-API está na conta. shared_without_routing indica outro parceiro sem roteamento: os dois recebem e os dois podem responder, e vale orientar o cliente a configurar. routed indica roteamento ativo, e aí roles lista as entradas em que a D-API é principal (customer_service, ctwa, marketing, utility, calls), com escalation quando ela pode assumir qualquer conversa.
A rota consulta a Meta na hora e a Meta limita a frequência. Use em telas de configuração ou depois de um erro, e não antes de cada envio.
Quando um segundo parceiro entra na conta, a Meta pode criar uma configuração de roteamento automaticamente. Se um número parou de receber mensagens ou começou a devolver o erro 131070 logo depois de uma nova conexão, essa é a primeira coisa a conferir.
Três arranjos comuns para SaaS
O roteamento vira um argumento comercial quando o seu time sabe propor a configuração certa para cada caso.
Seu SaaS como reserva
O cliente usa outra plataforma no dia a dia e quer a D-API pronta para assumir se ela falhar. No Meta Business Suite, o outro parceiro fica como principal de todas as entradas, e a D-API como escalonamento e standby. No dia a dia, a D-API recebe cópia de tudo pelo webhook e o histórico fica completo. Se a outra plataforma cair, a D-API assume a conversa com take, ou simplesmente enviando uma mensagem normal, e a Meta transfere a conversa na hora.
Nesse arranjo, qualquer mensagem de atendimento enviada pela D-API assume a conversa do outro parceiro, venha da API, do painel ou de um flow agendado. Se a sua integração não deve assumir conversas, envie só templates enquanto a outra plataforma estiver no ar.
Dividir por entrada
O seu SaaS dispara campanhas e notificações, e o outro parceiro faz o atendimento. As entradas de resposta a template de marketing e de utilidade ficam com a opção Rotear para quem enviou, e atendimento e anúncio ficam com o outro parceiro. Quem responde a um template do seu SaaS conversa com o seu SaaS, e quem escreve do nada vai para o atendimento do outro. É o arranjo natural para SaaS de cobrança, agendamento e e-commerce.
Bot e humano
Um parceiro faz o primeiro atendimento com bot, e o outro atende quando o cliente pede uma pessoa. O bot é principal de atendimento, e quem faz o atendimento humano é o escalonamento. Se o bot for o seu SaaS na D-API, a passagem é uma chamada:
curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/CONNECTION_ID/thread-control \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "action": "pass", "to": "5551999999999", "metadata": "Cliente pediu atendente" }'
O texto de metadata, com até 2.000 caracteres, chega ao parceiro que recebe a conversa.
Trocar o dono de uma conversa
A rota POST /api/v1/connections/cloud-api/{id}/thread-control age sempre sobre uma conversa, identificada pelo telefone do cliente em to:
action |
Quando a D-API pode usar | Efeito |
|---|---|---|
take |
Quando é o parceiro de escalonamento | Assume a conversa de quem for o dono |
pass |
Quando é a dona | Entrega a conversa; sem targetRole, vai para o escalonamento |
release |
Quando é a dona | Deixa a conversa livre para a próxima mensagem do cliente decidir |
O targetRole do pass aceita customer_service, ctwa, marketing, utility, escalation ou ai_agent. Os erros vêm com código estável para o seu código tratar: NOT_ESCALATION_PARTNER num take sem ser escalonamento, THREAD_CONTROL_NOT_ENABLED quando o número não tem roteamento ou a empresa não aceitou os termos da Meta, e META_GRAPH_ERROR com o metaCode original nas demais recusas. A lista de eventos que o seu backend recebe da D-API está em eventos de webhook do WhatsApp.
O que chega no seu webhook
No modo normalized, as cópias de conversas de outros parceiros chegam nos mesmos eventos de sempre, messages.received, message.delivered, message.read e message.failed, com um campo a mais: is_standby: true. Nas mensagens normais o campo não aparece. Uma mensagem que o outro parceiro enviou chega com fromMe: true e is_standby: true, e os flows, automações e agentes de IA da D-API não disparam nessas cópias.
Para o seu handler, a regra é simples: nunca responda um evento com is_standby: true. A conversa é de outro parceiro, e a resposta é recusada com 131070 ou, se a D-API for o escalonamento, toma a conversa dele.
A troca de dono envolvendo a D-API chega como conversation.control_changed, com type control_passed (a D-API passou a ser dona, is_owner: true) ou control_taken (deixou de ser, is_owner: false), além do papel anterior, do novo e, quando a Meta envia, um resumo da conversa. Com meta_passthrough, os mesmos sinais chegam nos campos standby e messaging_handovers do payload da Meta. O guia de webhooks da API de WhatsApp mostra como separar esses eventos no handler.
Quando o envio volta com 131070
Se a D-API tenta enviar texto livre ou mídia numa conversa que não é dela, sem ser o escalonamento, a Meta recusa e a rota de envio explica o motivo. O caminho é sempre um destes: enviar um template, que qualquer parceiro pode enviar e que não muda o dono; assumir com take, se a D-API for o escalonamento; ou pedir ao dono um pass. Uma conversa livre também recusa texto livre, e um template de marketing ou utilidade com “Rotear para quem enviou” traz a resposta do cliente para a D-API.
Por onde começar
Coloque o resultado do GET /routing na tela de configuração da conexão, com uma explicação curta de cada situation. Depois ensine o handler a ignorar is_standby e a reagir a conversation.control_changed. As rotas de detalhe da conexão estão em WhatsApp Cloud API, e o guia completo, com todos os casos, está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
A D-API é BSP ou Tech Provider?
A D-API é Tech Provider da Meta. O Embedded Signup roda no app Meta da D-API, e o número fica no Business Portfolio e na WABA do próprio cliente.
O meu SaaS paga pelas mensagens que o outro parceiro envia?
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.
Conectar a D-API num número que já usa outro parceiro muda algo para ele?
A D-API não registra de novo um número já ativo na API oficial com outro parceiro, para não trocar a verificação em duas etapas que ele configurou. A Meta, porém, pode criar um roteamento automático quando o segundo parceiro entra.
As cópias em standby vão para a integração com a Datacrazy?
Não. O formato da Datacrazy 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.
Quanto tempo uma conversa fica com o mesmo dono?
Até ser entregue, solta ou assumida, ou até passar 24 horas sem mensagem do cliente. Depois disso ela fica livre, e a próxima mensagem do cliente define o dono pela entrada.