Pular para o conteúdo
D-APITestar grátis

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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.