api oficial · cloud api
WhatsApp Cloud API da Meta operada pela D-API no seu SaaS
Use a WhatsApp Cloud API da Meta sem escrever a camada de Graph API: a D-API valida o token, assina o webhook, guarda o token criptografado e entrega envio e eventos no mesmo contrato da não oficial.
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
Conexão por popup ou manual
Embedded Signup para o cliente que conecta pelo seu produto, ou cadastro manual com wabaId, phoneNumberId e accessToken para quem já tem a WABA pronta.
Token guardado e auditado
O access token da Meta fica criptografado com AES-256-GCM. A leitura pela API devolve o tipo e a validade, e cada leitura gera log de auditoria.
Webhook no formato que você quiser
normalized entrega o evento canônico da D-API. meta_passthrough repassa o corpo cru da Meta. Dá para trocar depois, por conexão.
Saúde da conta no seu painel
A rota de detalhe traz qualidade e tier de mensagens sincronizados da Meta, prontos para exibir ao cliente.
A WhatsApp Cloud API é a versão da API oficial do WhatsApp hospedada pela própria Meta, acessada pela Graph API. Ela é poderosa e também trabalhosa para um SaaS que quer oferecê-la a dezenas de clientes: troca de código por token, assinatura de webhook por WABA, registro do número, tradução de payload, guarda segura de token, leitura de qualidade da conta. A D-API faz essa camada e entrega a Cloud API ao seu produto como uma conexão igual às outras, com o mesmo envio e o mesmo webhook da API não oficial.
O que a D-API faz por cima da Cloud API
Para o seu time, o ganho é não escrever nem manter a integração com a Graph API para cada cliente. Ao provisionar uma conexão, a D-API valida o par número e token na Graph API, tenta assinar os webhooks do app na WABA e cria a conexão com a cobrança por conexão sincronizada. O token fica criptografado com AES-256-GCM no banco.
Depois disso, o número responde às mesmas rotas que o seu produto já usa. O id da conexão é o sessionId em POST /api/v1/messages/send/text e nas demais rotas de envio, e os eventos chegam no formato que você escolher. As rotas específicas da Cloud API, que ficam em /api/v1/connections/cloud-api/{id}, aceitam tanto o id da conexão quanto o id da sessão, no formato cloud-<uuid>.
Três jeitos de conectar um número
Para um SaaS que integra por API, são três caminhos, e cada um atende um perfil de cliente. No painel da D-API existe ainda a seleção de uma WABA existente, para quem conecta o primeiro número sem código.
Embedded Signup pelo seu produto
O cliente clica num botão do seu painel, passa pelo fluxo da Meta num popup hospedado pela D-API e a conexão volta pronta. É o caminho para a maioria dos clientes, explicado em Embedded Signup WhatsApp.
Coexistência com o app
Mesmo fluxo, com mode: "coexistence", para o cliente que quer manter o app WhatsApp Business no número. O histórico do app é importado na conexão.
Cadastro manual com credenciais da Meta
Para quem já gerou WABA, número e token no Meta Business Manager, por exemplo uma conta corporativa com time de TI próprio, existe a rota de cadastro manual:
curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/manual \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"wabaId": "102290129340398",
"phoneNumberId": "106540352242922",
"accessToken": "EAAG…",
"webhookMode": "normalized"
}'
A resposta traz data.session e data.webhookSubscribed. Quando webhookSubscribed vem false, a assinatura automática do webhook não aconteceu, e o seu painel deve mostrar ao usuário as instruções para assinar manualmente no painel da Meta. A rota exige assinatura ativa na sua conta D-API: sem ela, responde 402 com code: "TRIAL_REQUIRED".
As rotas de uma conexão Cloud API
Com a conexão criada, cinco rotas cobrem o que um painel de SaaS costuma precisar.
| Rota | Para que serve |
|---|---|
GET /api/v1/connections/cloud-api/{id} |
Detalhes: WABA, número exibido, nome verificado, webhook e saúde da conta |
PATCH /api/v1/connections/cloud-api/{id} |
Trocar webhookUrl, webhookMode ou rotacionar o accessToken |
GET /api/v1/connections/cloud-api/{id}/access-token |
Ler o token da Meta descriptografado, com tipo e validade |
GET /api/v1/connections/cloud-api/{id}/routing |
Ver outros parceiros no número e o papel da D-API |
POST /api/v1/connections/cloud-api/{id}/thread-control |
Assumir, passar ou soltar uma conversa |
Detalhe e saúde da conta
O GET da conexão devolve os dados de identificação e os indicadores de saúde sincronizados da Meta: qualidade e tier de mensagens. Para o cliente, o tier é o número que importa, porque define o limite diário de mensagens iniciadas pela empresa. Mostrar esse dado no seu painel evita a pergunta “por que minha campanha parou?”. A rota responde 404 quando a conexão não pertence à conta da API key.
Atualizar webhook e rotacionar token
O PATCH aceita webhookUrl (ou null para limpar), webhookMode e accessToken, e exige pelo menos um campo. Sem nenhum, responde 400. O token rotacionado é criptografado de novo na escrita.
curl -X PATCH https://api.d-api.cloud/api/v1/connections/cloud-api/CONNECTION_ID \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "webhookUrl": "https://seu-saas.com/hooks/dapi", "webhookMode": "meta_passthrough" }'
Access token da Meta
Quem precisa chamar a Graph API por fora da D-API lê o token pelo backend. A resposta traz o accessToken e uma classificação:
kind |
Significado |
|---|---|
permanent |
Não expira, como o token de System User |
long_lived |
Token de cerca de 60 dias |
short_lived |
Token de cerca de 1 hora |
unknown |
A Meta não respondeu à consulta de classificação; o token vem mesmo assim |
Além do kind, vêm label em português, expiresAt, expiresInDays, isValid, scopes, type, wabaId, phoneNumberId e businessId. Como o token envia mensagens e administra a WABA do cliente, chame a rota só do backend e nunca registre o valor em log. Do lado da D-API, cada leitura fica registrada com quem leu, sem o token.
Webhook normalizado ou cru
O formato dos eventos é escolhido por conexão. Com normalized, o padrão, a conexão Cloud API entrega o evento canônico da D-API, com event, sessionId e data, igual ao de uma conexão não oficial, e o mesmo handler serve as duas. Uma falha de entrega chega como message.failed com o error_code da Meta.
Com meta_passthrough, o corpo do webhook da Meta chega sem tradução, incluindo o statuses original com o wamid e os códigos de erro. É a escolha para quem já tem parser da Cloud API ou precisa de eventos que só existem no formato da Meta, como o message_template_status_update dos templates.
Nos dois modos, a ordem de entrega não é garantida e pode haver reentrega. Use o wamid, presente em todos os eventos da mensagem, como chave de idempotência. Cada tentativa espera resposta 2xx em até 30 segundos. O guia de webhooks da API de WhatsApp mostra um handler que responde rápido e processa em fila.
Roteamento e thread control
Um número da Cloud API pode estar conectado a mais de uma plataforma ao mesmo tempo, e a Meta usa o Conversation Routing para decidir quem responde cada conversa. A rota GET /routing mostra a situação: exclusive quando só a D-API está na conta, shared_without_routing quando há outro parceiro sem roteamento e routed quando o roteamento está ativo. Ela consulta a Meta na hora e a Meta limita a frequência, então use em telas de configuração ou depois de um erro, e não antes de cada envio.
A rota thread-control troca o dono de uma conversa com take, pass ou release. Os papéis, os casos de uso e os eventos estão em API oficial com mais de um parceiro.
Limites que valem na Cloud API
A D-API não impõe limite próprio de envio nas conexões oficiais. Vale o da Meta: cerca de 80 mensagens por segundo por número, ou 20 em coexistência, além do limite diário definido pelo tier. Fora da janela de 24 horas, mensagens iniciadas pela empresa precisam de template aprovado.
Por onde começar
Decida como os seus clientes vão conectar: Embedded Signup para a base, cadastro manual para a conta corporativa que já chega com credenciais. Depois escolha o webhookMode e exponha no seu painel o tier e a qualidade que vêm no detalhe da conexão. A API oficial do WhatsApp resume quando oferecer a Cloud API ao cliente, e a referência de cada rota está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
Posso continuar chamando a Graph API direto, além da D-API?
Pode. A rota de access token devolve o token da Meta da conexão, já descriptografado, para o seu backend chamar a Graph API, por exemplo para gerenciar o catálogo por fora da D-API.
O token da Meta expira?
O token da conexão não expira, mas é revogado se o app da D-API for removido da WABA. A rota de access token informa o tipo e a data de expiração quando existe.
Onde a mídia recebida pela Cloud API fica guardada?
Por padrão, no bucket da D-API por 3 dias, entregue como media_url no webhook. Também dá para usar um bucket próprio ou desligar o armazenamento e baixar pelo media_id com a rota de download de mídia.
A D-API tem marcação de lida e indicador de digitando na conexão oficial?
Ainda não. As duas estão no roadmap, sem data definida.
O cadastro manual tem custo diferente do Embedded Signup?
Não. As duas formas criam a mesma conexão oficial, cobrada por conexão ativa como a não oficial. As tarifas de mensagem da Meta ficam na WABA do cliente.