# Vários parceiros no mesmo número Source: https://docs.d-api.cloud/api-oficial/multiplos-parceiros Como usar a D-API junto com outra plataforma no mesmo número da API Oficial: quem responde cada conversa, modo standby, fallback e como trocar o dono de uma conversa. 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. > [!NOTE] > > **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. > [!WARNING] > > 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](#1-descubra-a-situação-do-número). ## Conceitos | Termo | O que é | | - | - | | **Conversa** | A troca de mensagens com **um** cliente num número. O roteamento vale por conversa, não pelo número inteiro: o mesmo número pode ter conversas com donos diferentes. | | **Dono** | O parceiro que atende aquela conversa. É o **único** que recebe a mensagem do cliente como mensagem normal e o **único** que pode enviar mensagem de atendimento (texto livre na janela de 24h). | | **Entrada** | Por onde a conversa começou. Define quem vira dono. São cinco: **Atendimento** (padrão), **Anúncio de clique para WhatsApp**, **Resposta a template de marketing**, **Resposta a template de utilidade** e **Ligação**. | | **Principal** | O parceiro configurado para uma entrada. Vira dono quando a conversa começa por ela. | | **Standby** | O parceiro **observador**: recebe **cópia** de tudo que acontece nas conversas dos outros (mensagens do cliente, o que o dono enviou e status), mas **não responde**. | | **Escalonamento** | No máximo **um** parceiro por conta. Pode **assumir qualquer conversa a qualquer momento**, mesmo com outro dono. É o que torna possível o fallback. | | **Conversa livre** | Sem dono. Acontece depois de **24h sem mensagem do cliente** ou quando o dono solta a conversa. A próxima mensagem do cliente decide o dono de novo, pela entrada. | ### O que cada parceiro pode fazer | | Dono da conversa | Standby | Escalonamento (sem ser dono) | | - | - | - | - | | Recebe a mensagem do cliente | Sim | Cópia, marcada com `is_standby` | Só se também for standby | | Envia texto livre / mídia | Sim | **Não** (erro `131070`) | Sim, e **vira dono** ao enviar | | Envia template (marketing, utilidade, autenticação) | Sim | **Sim** | Sim | | Assume a conversa (`take`) | — | Não | Sim | | Entrega a conversa (`pass`) ou solta (`release`) | Sim | Não | Não (precisa assumir antes) | > [!NOTE] > > **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: ```bash theme={null} curl https://api.d-api.cloud/api/v1/connections/cloud-api/SUA_CONEXAO/routing \ -H "Authorization: SUA_API_KEY" ``` `SUA_CONEXAO` é o id da conexão ou o id da sessão (`cloud-…`). ```json Resposta theme={null} { "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 } } ``` **situation** `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`. **roles** `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. **isStandby** `boolean` `true` se a empresa deu à D-API a visão standby (cópia das conversas dos outros parceiros). **isEscalation** `boolean` `true` se a D-API pode assumir qualquer conversa. Atalho para `roles` conter `escalation`. **subscribedApps** `object[]` Parceiros (apps) conectados à conta. `isCurrentApp: true` marca a D-API. **otherAppsCount** `number` Quantos parceiros além da D-API. > [!WARNING] > > 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`](#1-descubra-a-situação-do-número) e veja se o papel da D-API é o esperado. ## 3. Casos de uso > [tab] D-API como fallback > > **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:** > > | Item | Valor | > | - | - | > | Principal de todas as entradas | Outro parceiro | > | Escalonamento | **D-API** | > | Standby | **D-API** | > > **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`](#assumir-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`](#entregar-pass) com `targetRole: "customer_service"`, ou > [`release`](#soltar-release) para deixar a próxima mensagem do cliente > decidir pela configuração. > > > [!WARNING] > > > > 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. > [tab] Dividir por entrada > > **Cenário.** A D-API dispara campanhas e notificações; o outro parceiro faz > o atendimento. > > **Configuração:** > > | Entrada | Principal | > | - | - | > | Resposta a template de marketing | **Rotear para quem enviou** | > | Resposta a template de utilidade | **Rotear para quem enviou** | > | Atendimento | Outro parceiro | > | Anúncio de clique para WhatsApp | Outro parceiro | > > **Resultado:** quem responde a um template da D-API conversa com a D-API > (flows de resposta funcionam). Quem chega por anúncio ou escreve do nada vai > para o atendimento do outro parceiro. > > Se quiser que a D-API acompanhe o atendimento do outro parceiro, dê a ela > também a visão **standby**. > [tab] Bot e humano > > **Cenário.** Um parceiro faz o primeiro atendimento com bot e outro (ou a > D-API) atende quando o cliente pede um humano. > > **Configuração:** o bot é principal de **Atendimento**; quem faz o > atendimento humano é o **escalonamento**. > > **Operação:** quando o cliente pede um humano, o bot faz um `pass` sem > `targetRole` (vai direto para o escalonamento). Se o bot for a D-API: > > ```bash theme={null} > curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/SUA_CONEXAO/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` chega ao parceiro que recebe a conversa. > [tab] Voltar a usar só a D-API > > Duas formas: > > * **Remover o outro parceiro da conta.** Com menos de dois parceiros, a Meta > **apaga o roteamento** sozinha e tudo volta a chegar normalmente na D-API. > `GET /routing` passa a mostrar `situation: "exclusive"`. > * **Manter os dois e tornar a D-API principal de todas as entradas.** O > outro parceiro continua conectado, mas não recebe mais conversas (a não > ser que também tenha escalonamento ou standby). > > Nos dois casos a mudança é feita pela empresa no Meta Business Suite. ## 4. Trocar o dono de uma conversa Uma rota, três ações. Sempre para **uma conversa** (um cliente). ```http theme={null} POST /api/v1/connections/cloud-api/{id}/thread-control ``` **action** `string` *required* `take`, `pass` ou `release`. **to** `string` *required* Telefone do cliente. Aceita qualquer formatação ou JID (`5551999999999@s.whatsapp.net`). **targetRole** `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. **metadata** `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.** ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/SUA_CONEXAO/thread-control \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "take", "to": "5551999999999" }' ``` ```json Resposta theme={null} { "success": true, "data": { "action": "take", "requestId": "abc123" } } ``` O parceiro que perdeu a conversa é avisado pela Meta. ### Entregar (`pass`) A D-API, **sendo a dona**, entrega a conversa para outro parceiro. ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/SUA_CONEXAO/thread-control \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "pass", "to": "5551999999999", "targetRole": "customer_service" }' ``` 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. ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/SUA_CONEXAO/thread-control \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "release", "to": "5551999999999" }' ``` > [!NOTE] > > O `release` **não gera webhook** para ninguém: não há novo dono até o cliente > escrever de novo. ### Erros | HTTP | `code` | Quando | | - | - | - | | 400 | `INVALID_INPUT` | `to` sem telefone, `targetRole` fora de `pass`, `metadata` maior que 2000 caracteres. | | 403 | `NOT_ESCALATION_PARTNER` | `take` sem a D-API ser o parceiro de escalonamento. | | 400 | `THREAD_CONTROL_NOT_ENABLED` | O número não tem roteamento ou a empresa não aceitou os termos. | | 400 | `ACTION_NOT_ENABLED` | A ação ou o destino não está habilitado na conta (ex.: `ai_agent` sem Meta Business Agent). | | 400 | `META_GRAPH_ERROR` | Outra recusa da Meta (ex.: `pass` sem ser dono). `data.metaCode` traz o código da Meta. | | 404 | — | Conexão não encontrada. | ```json Exemplo de erro theme={null} { "success": false, "error": "You are not permitted to take thread control for this phone number.", "code": "NOT_ESCALATION_PARTNER", "data": { "metaCode": 2494191, "fbtraceId": "AbCdEf123" } } ``` ## 5. Webhooks > [tab] Modo normalized > > ### 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**. > > | O que aconteceu | Evento | Campos que mudam | > | - | - | - | > | O cliente escreveu numa conversa de outro parceiro | `messages.received` | `fromMe: false`, `is_standby: true` | > | O outro parceiro enviou uma mensagem ao cliente | `messages.received` | `fromMe: true`, `is_standby: true` | > | Uma mensagem do outro parceiro foi entregue, lida ou falhou | `message.delivered` / `message.read` / `message.failed` | `is_standby: true` | > > ```json Cliente escreveu numa conversa do outro parceiro theme={null} > { > "event": "messages.received", > "sessionId": "cloud-3f2a…", > "data": { > "id": "wamid.HBgM…", > "from": { "jid": "5551999999999@s.whatsapp.net", "name": "Maria" }, > "to": { "jid": "5511955026302@s.whatsapp.net" }, > "fromMe": false, > "message": "Meu pedido ainda não chegou", > "timestamp": 1761955200, > "is_group": false, > "type": "text", > "is_standby": true > } > } > ``` > > ```json O outro parceiro enviou um template theme={null} > { > "event": "messages.received", > "sessionId": "cloud-3f2a…", > "data": { > "id": "wamid.HBgN…", > "from": { "jid": "5511955026302@s.whatsapp.net" }, > "to": { "jid": "5551999999999@s.whatsapp.net" }, > "fromMe": true, > "message": "[Template pedido_enviado]: Maria, #12345", > "timestamp": 1761955260, > "is_group": false, > "type": "template", > "is_standby": true > } > } > ``` > > 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. > > > [!WARNING] > > > > **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`). > > ```json theme={null} > { > "event": "conversation.control_changed", > "sessionId": "cloud-3f2a…", > "data": { > "type": "control_passed", > "is_owner": true, > "remote_jid": "5551999999999@s.whatsapp.net", > "phone": "5551999999999", > "previous_owner_role": "customer_service", > "new_owner_role": "escalation", > "metadata": "Cliente pediu atendente", > "conversation_summary": "Cliente quer trocar o tamanho do pedido #12345.", > "timestamp": 1761955320 > } > } > ``` > > **type** `string` > > `control_passed` ou `control_taken`. > > **is\_owner** `boolean` > > `true`: a D-API passou a ser a dona da conversa. `false`: deixou de ser. > > **previous\_owner\_role** `string | null` > > Papel de quem era o dono (`customer_service`, `ctwa`, `marketing`, > `utility`, `escalation`, `ai_agent`). > > **new\_owner\_role** `string | null` > > Papel de quem passou a ser o dono. > > **metadata** `string | null` > > Texto enviado por quem fez a troca. > > **conversation\_summary** `string | null` > > Resumo da conversa gerado pela Meta, quando ela envia (só em > `control_passed`). > [tab] Modo meta\_passthrough > > No modo `meta_passthrough` a D-API repassa o payload da Meta **sem > alterações**, como em todos os outros eventos: > > * Cópias chegam no campo `standby` (`change.field === "standby"`), com o > conteúdo em `value.standby.messages`, `value.standby.message_echoes` ou > `value.standby.statuses`. > * Trocas de dono chegam no campo `messaging_handovers` > (`value.type` = `control_passed` ou `control_taken`). > > Veja o formato completo na documentação da Meta: > [standby](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/standby/) > e [thread control](https://developers.facebook.com/documentation/business-messaging/whatsapp/conversation-routing/thread-control/). ## 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: ```json theme={null} { "success": false, "error": "Failed to send message", "message": "Conversa controlada por outro app (Meta 131070). Este número usa Conversation Routing e outro parceiro é o dono desta conversa. Envie um template (permitido sempre), peça ao dono um pass, ou chame POST /api/v1/connections/cloud-api/{id}/thread-control com action=take se a D-API for o parceiro de escalonamento." } ``` 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. > [!NOTE] > > 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 > [accordion] A D-API fica sempre em standby? > > 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`](#1-descubra-a-situação-do-número) para ver o papel > atual. > [accordion] Dá para usar as duas plataformas ao mesmo tempo? > > 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. > [accordion] Como sei se tem outro parceiro no número? > > `GET /routing`: `otherAppsCount` maior que zero e a lista em > `subscribedApps`. > [accordion] Os flows e as automações da D-API rodam nas cópias standby? > > 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. > [accordion] As mensagens do outro parceiro aparecem no painel da D-API? > > 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. > [accordion] Eu pago pelas mensagens do outro parceiro? > > 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. > [accordion] E a integração com a Datacrazy? > > 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. > [accordion] Quanto tempo uma conversa fica com o mesmo dono? > > 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. > [accordion] Ao conectar a D-API num número que já usa outro parceiro, algo muda para ele? > > 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. # API Oficial para SaaS (provedor) Source: https://docs.d-api.cloud/api-oficial/saas Ofereça a conexão do WhatsApp API Oficial dentro do seu próprio SaaS, usando a D-API como provedor. Se você tem um SaaS e quer que **seus clientes** conectem o WhatsApp **API Oficial** (Cloud API) sem sair do seu produto, a D-API funciona como **provedor**: você embute um fluxo de conexão, cada número conectado vira uma conexão na **sua** conta D-API, e você é cobrado **por conexão**. Você repassa como quiser para o seu cliente. * **Você** é um usuário normal da D-API (sua API key secreta fica no seu backend). * Seu cliente conecta o número dele; a conexão fica sob a sua conta, identificada por um `connectionId`. * **Cobrança da Meta é do seu cliente** (ele usa o método de pagamento dele na WABA). A D-API só cobra a **taxa de plataforma por conexão** de você. ## Como funciona O Embedded Signup da Meta **não roda no domínio do seu SaaS** (a Meta exige domínios cadastrados). Por isso o fluxo roda numa **página hospedada pela D-API** (`connect.d-api.cloud`), que você abre como **popup**. O resultado volta pro seu app por `postMessage`. **Seu domínio não precisa ser cadastrado na Meta.** **1. Crie uma publishable key** Uma **publishable key** (`pk_live_…`) é pública de propósito: só inicia o onboarding — não envia mensagens nem lê dados. Crie no painel em **Integrações → Publishable Keys**, ou via API com a sua API key secreta: ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/publishable-keys \ -H "Authorization: " \ -H "content-type: application/json" \ -d '{}' ``` A resposta traz o `key` **uma única vez** — guarde. **2. Abra o connect no seu frontend** Use o pacote `d-api-sdk` (entry `d-api-sdk/connect`): ```ts theme={null} import { DApiConnect } from "d-api-sdk/connect"; const connect = new DApiConnect({ publishableKey: "pk_live_…" }); const { connectionId, phoneNumber, accessToken } = await connect.start({ webhookUrl: "https://seu-saas.com/hooks/dapi", // opcional webhookMode: "normalized", // opcional (padrão) metadata: { tenantId: "acme-42" }, // opcional, volta no webhook }); ``` Isso abre o popup hospedado, roda o Embedded Signup e resolve com o `connectionId` (e o [access token da Meta](#access-token-da-meta)). Também dá para fazer o handshake "na mão", em HTML puro — veja o [exemplo completo](https://github.com/d-api/exemplo-api-oficial-saas). **3. Associe o connectionId ao seu cliente** Guarde o `connectionId` retornado no seu banco, ligado ao cliente correspondente. A partir daí, esse número é uma conexão normal da D-API. **4. Envie mensagens pelo seu backend** Com a sua **API key secreta** (nunca no navegador), o `connectionId` é o `sessionId` nas rotas normais de envio: ```ts theme={null} import { DApi } from "d-api-sdk"; const dapi = new DApi({ apiKey: "" }); await dapi.messages.sendText({ sessionId: connectionId, to, text }); ``` ## Coexistência (manter o app WhatsApp Business) Por padrão o fluxo **cria/onboarda um número novo** na API Oficial. Se o seu cliente quer **manter o app WhatsApp Business** no mesmo número (coexistência), passe `mode: "coexistence"`: ```ts theme={null} const { connectionId } = await connect.start({ mode: "coexistence" }); ``` O fluxo é o mesmo do padrão — a janela vai direto para a Meta e volta com o `connectionId`. A diferença é o que a Meta pede ao cliente: escanear um QR no app WhatsApp Business. A sincronização do histórico começa automaticamente e pode levar alguns minutos; oriente o cliente a manter o app aberto. ## Webhooks Você define o webhook da conexão no `connect.start({ webhookUrl })`, e pode alterar depois pela rota de atualização de sessão. Os eventos chegam com o id da conexão/sessão no payload — então você pode apontar todas as conexões para um único endpoint e distribuir pelo `connectionId`. ### O resultado chega por dois caminhos Toda conexão criada pelo connect hospedado é anunciada **duas vezes**, sem opção a configurar: 1. o `connect.start()` resolve no navegador com o `connectionId` e o access token; 2. um webhook [`session.created`](/whatsapp/webhooks/conexao) vai para o `webhookUrl` daquela conexão, com **todos** os dados — incluindo o access token e o seu `metadata`. O segundo existe por causa do **mobile**. Em navegador de celular o popup abre como uma aba, sem `window.opener` utilizável, então o `postMessage` que o `start()` espera nunca chega: a promise pode rejeitar com "Conexão cancelada" enquanto a conexão foi criada normalmente. Em webview de app nativo vale o mesmo. > [!WARNING] > > Em fluxo mobile, **não trate a rejeição do `start()` como falha** — confirme > pelo `session.created` (ou pela rota de listagem de conexões) antes de mostrar > erro para o seu cliente. ### Correlacionar com o seu cliente (`metadata`) `metadata` é um JSON livre seu, guardado com a conexão e devolvido intacto em `data.metadata` do `session.created`. É o que permite ligar a conexão ao tenant sem depender do retorno síncrono: ```ts theme={null} await connect.start({ webhookUrl: "https://seu-saas.com/hooks/dapi", metadata: { tenantId: "acme-42", plano: "pro" }, }); ``` Limite: **512 bytes** de JSON serializado. O valor viaja na URL do diálogo da Meta, e acima disso o `start()` lança erro antes de abrir a janela. Guarde ali identificadores, não objetos de negócio inteiros. > [!NOTE] > > `metadata` é opcional e novo na versão **1.3.0** do SDK. Integrações em 1.2.0 > ou anterior seguem funcionando sem alteração — apenas recebem `metadata: {}` > no evento. ### Formato dos eventos (`webhookMode`) Você escolhe em que **formato** os eventos chegam: | `webhookMode` | O que chega no seu endpoint | | - | - | | `normalized` *(padrão)* | O evento **canônico da D-API** — o mesmo payload de uma conexão não-oficial, então um único handler serve as duas. | | `meta_passthrough` | O **corpo cru do webhook da Meta**, sem tradução — para quem já tem um parser do formato oficial. | ```ts theme={null} const { connectionId } = await connect.start({ webhookUrl: "https://seu-saas.com/hooks/dapi", webhookMode: "meta_passthrough", // padrão: "normalized" }); ``` Dá para trocar depois em [Atualizar conexão](/api-reference/cloud-api/atualizar-conexao) (`webhookMode`). ## Access token da Meta O resultado do `connect.start()` traz também o **access token da Meta** daquela conexão, já descriptografado — útil se você quer chamar a Graph API direto (por exemplo, para gerenciar templates ou o catálogo por fora da D-API): ```ts theme={null} const { connectionId, accessToken, // token da Graph API — SEGREDO accessTokenKind, // "permanent" | "long_lived" | "short_lived" | "unknown" accessTokenLabel, // resumo em português, pronto para exibir accessTokenExpiresAt, // ISO-8601, ou null quando não expira } = await connect.start({ ... }); ``` No Embedded Signup a Meta emite um token **permanente** (`accessTokenKind: "permanent"`, `accessTokenExpiresAt: null`) — é o caso normal aqui. Os outros tipos aparecem quando o token foi trocado manualmente: `long_lived` (\~60 dias) e `short_lived` (\~1 hora). > [!WARNING] > > O `accessToken` é **segredo**: com ele dá para enviar mensagens e administrar a > WABA do seu cliente. Encaminhe para o **seu backend** e pronto — não registre em > log, não salve no `localStorage`, não exponha em URL. Se preferir que o token **não trafegue pelo navegador**, ignore o campo e busque no seu backend quando precisar, com a sua API key secreta: ```bash theme={null} curl https://api.d-api.cloud/api/v1/connections/cloud-api//access-token \ -H "Authorization: " ``` A resposta traz o token e a mesma classificação — veja [Obter access token da Meta](/api-reference/cloud-api/obter-access-token). ## Quando a conexão falha Se o onboarding não conclui, a janela hospedada mostra o motivo **em português, com o código embaixo** — um print dela já serve para o suporte. O mesmo motivo volta para o seu app: ```js theme={null} { type: "dapi-connect-result", ok: false, error: "trial_required", errorLabel: "A conta D-API do parceiro precisa de uma assinatura ativa para criar conexões." } ``` Com o SDK, o `connect.start()` **rejeita** com essa mensagem. Se você fez o handshake na mão, cheque o `ok` **antes** de ler o `data` — numa falha não existe `data`, e ler `data.connectionId` direto faz você perder o motivo real: ```js theme={null} if (!msg.ok) { throw Object.assign(new Error(msg.errorLabel || msg.error), { code: msg.error }); } ``` | `error` | O que aconteceu | O que fazer | | - | - | - | | `trial_required` | A **sua** conta D-API (a do parceiro) não tem assinatura ativa. | Ative o plano/teste na sua conta. | | `number_in_use` | O número já está conectado em outra conta. | Desconecte antes de reconectar. | | `invalid_key` | Publishable key inválida, expirada ou revogada. | Gere outra. | | `plan_not_ready`, `billing_not_ready` | Cobrança da sua conta ainda não configurada. | Finalize o cadastro de cobrança. | | `missing_code`, `access_denied` | A Meta não devolveu o código — geralmente o cliente cancelou. | Peça para repetir. | | `config_error` | Configuração do app Meta no servidor da D-API. | Falar com o suporte da D-API. | | `onboarding_failed` | A Meta não concluiu o cadastro do número. | Tentar novamente. | > [!NOTE] > > `trial_required`, `plan_not_ready` e `billing_not_ready` são sobre a **sua** > conta D-API, não a do seu cliente — é a taxa de plataforma por conexão. A > cobrança das conversas continua sendo da conta Meta do cliente. ## Cobrança (pass-through) A cobrança das conversas pela Meta é do **seu cliente**: durante o Embedded Signup ele usa o método de pagamento da conta Meta dele na WABA. A D-API **não** cobra as conversas — só a **taxa de plataforma por conexão ativa**, na sua conta. Lembre o seu cliente de finalizar o método de pagamento no WhatsApp Manager, se a Meta pedir. ## Segurança * A **publishable key** é pública por design: escopo `onboard` apenas, com rate limit. O pior caso de vazamento é alguém iniciar um popup de Embedded Signup — sem acesso a dados nem envio. * A sua **API key secreta** nunca vai para o navegador — só no seu backend. * O resultado do onboarding só é entregue para a janela que abriu o popup, e o SDK valida que a mensagem veio do domínio hospedado da D-API. * O **access token da Meta** volta pela página hospedada no *fragmento* da URL (`#…`), que o navegador nunca envia ao servidor — ele não aparece em log de acesso nem em `Referer`, e a página o apaga da barra de endereço depois de repassar. Daí em diante a responsabilidade é sua: mande para o backend e não persista no browser. > [card] [Exemplo completo (HTML puro)](https://github.com/d-api/exemplo-api-oficial-saas) > > Um único arquivo, sem framework, mostrando o fluxo popup + postMessage passo a passo. # Busca avançada de chats Source: https://docs.d-api.cloud/api-reference/chat/busca-avançada-de-chats /api-reference/openapi.json post /api/v1/chats/search Busca chats com filtros avançados e suporte a múltiplas sessões. **Funcionalidades:** - Se `sessionIds` estiver vazio, busca em todas as sessões do usuário - Se `sessionIds` tiver valores, filtra apenas essas sessões - Administradores podem ver chats de todos os usuários - Usuários comuns veem apenas seus próprios chats - Busca otimizada por nome de contato, telefone ou nome do grupo - Resolução automática de nome do contato (fallback para phone se pushName não existir) # Busca avançada de mensagens Source: https://docs.d-api.cloud/api-reference/chat/busca-avançada-de-mensagens /api-reference/openapi.json post /api/v1/chats/messages/search Busca mensagens com filtros avançados e suporte a múltiplas sessões. **Funcionalidades:** - Se `sessionIds` estiver vazio, busca em todas as sessões do usuário - Permite buscar por `chatId` (ID do banco) OU por `phone` (número do contato) - Filtros por tipo de mensagem, remetente (fromMe), e intervalo de datas - Administradores podem ver mensagens de todos os usuários - Usuários comuns veem apenas suas próprias mensagens - Suporte a polling para atualizações em tempo real # Deletar mensagem Source: https://docs.d-api.cloud/api-reference/chat/deletar-mensagem /api-reference/openapi.json delete /api/v1/chats/messages/{messageId} Deleta uma mensagem específica via PodWorker. Para deletar mensagens de outros usuários (como admin), passe o JID do remetente no campo 'sender'. # Editar mensagem Source: https://docs.d-api.cloud/api-reference/chat/editar-mensagem /api-reference/openapi.json put /api/v1/messages/{messageId} Edita o texto de uma mensagem específica # Enviar presença Source: https://docs.d-api.cloud/api-reference/chat/enviar-presença /api-reference/openapi.json post /api/v1/chats/presence Envia presença global (available/unavailable) ou por chat (typing/recording/paused) via PodWorker. Opcionalmente, para typing/recording, informe 'durationMs' para manter o estado por um tempo antes de pausar automaticamente. # Listar chats de uma sessão Source: https://docs.d-api.cloud/api-reference/chat/listar-chats-de-uma-sessão /api-reference/openapi.json get /api/v1/chats/ Retorna uma lista simplificada de chats com informações essenciais. Suporta busca inteligente por nome de contato ou telefone normalizado. # Listar mensagens de um chat (simplificado) Source: https://docs.d-api.cloud/api-reference/chat/listar-mensagens-de-um-chat-simplificado /api-reference/openapi.json get /api/v1/chats/{chatId}/messages Retorna uma lista simplificada de mensagens de um chat específico com parâmetros essenciais. Suporta busca inteligente por conteúdo da mensagem. # Marcar como lidas Source: https://docs.d-api.cloud/api-reference/chat/marcar-como-lidas /api-reference/openapi.json post /api/v1/chats/read Marca mensagens como lidas em um chat via PodWorker # Obter detalhes de um chat Source: https://docs.d-api.cloud/api-reference/chat/obter-detalhes-de-um-chat /api-reference/openapi.json get /api/v1/chats/{chatId} Retorna os detalhes de um chat específico # Atualizar blocklist Source: https://docs.d-api.cloud/api-reference/contacts/atualizar-blocklist /api-reference/openapi.json post /api/v1/contacts/blocklist Bloqueia ou desbloqueia um contato (update_blocklist) # Listar contatos Source: https://docs.d-api.cloud/api-reference/contacts/listar-contatos /api-reference/openapi.json get /api/v1/contacts/ Lista todos os contatos da agenda do WhatsApp # Obter avatar do usuário Source: https://docs.d-api.cloud/api-reference/contacts/obter-avatar-do-usuário /api-reference/openapi.json get /api/v1/contacts/{phone}/avatar Obtém o avatar de um usuário específico. Use force=true para ignorar cache e buscar direto do WhatsApp. # Obter blocklist Source: https://docs.d-api.cloud/api-reference/contacts/obter-blocklist /api-reference/openapi.json get /api/v1/contacts/blocklist Retorna a lista de contatos bloqueados (JIDs e phones) # Obter informações do usuário Source: https://docs.d-api.cloud/api-reference/contacts/obter-informações-do-usuário /api-reference/openapi.json post /api/v1/contacts/getuser Mesma resposta de GET /contacts/{phone}: contato enriquecido com nomes, dados de negócio, perfil business (businessProfile) e avatar. business=false pula o perfil business. # Reportar contato Source: https://docs.d-api.cloud/api-reference/contacts/reportar-contato /api-reference/openapi.json post /api/v1/contacts/report Reporta um contato ao WhatsApp e, opcionalmente, bloqueia (report_contact). Resposta em data: { report: { status, report_id?, error? }, block?: { status, blocklist?, error? } }. success=true no envelope significa que o bridge atendeu o pedido — não que ambos sub-steps deram certo. report.status='ok' com report_id vazio é descarte legítimo do servidor (evidência sintética) e não é erro. block é avaliado independente do report: pode falhar (LID resolution miss) mesmo com report ok. Erros que derrubam o envelope (success=false): sessão não conectada, JID inválido, recipient vazio, warmup/rate-limit. # Verificar usuários Source: https://docs.d-api.cloud/api-reference/contacts/verificar-usuários /api-reference/openapi.json post /api/v1/contacts/check Verifica se números de telefone estão registrados no WhatsApp # Conectar via QR code Source: https://docs.d-api.cloud/api-reference/endpoints/conectar-qr api-reference/openapi.json GET /api/v1/sessions/{sessionId}/qr Obtenha o QR code para conectar a sessão ao WhatsApp. Depois de criar uma sessão `unofficial`, conecte-a escaneando o QR code no WhatsApp do celular (**Aparelhos conectados → Conectar um aparelho**). Use `?image=1` para receber o QR diretamente como **imagem PNG**. Sem o parâmetro, a resposta traz os dados do QR em JSON, ideais para renderizar o código no seu próprio front-end. > [!NOTE] > > O QR code expira em segundos e é renovado automaticamente. Consulte o endpoint > novamente para obter um código atualizado enquanto a sessão não conecta. > [!NOTE] > > Uma sessão que passa **45 minutos** gerando QR sem ser conectada, e sem > consultas a este endpoint, é hibernada e dispara o webhook > [`connection.status` com `qrcode_timeout`](/whatsapp/webhooks/conexao). > A próxima consulta acorda a sessão: ela responde com `expired: true` e o QR > novo aparece em alguns segundos. # Criar grupo Source: https://docs.d-api.cloud/api-reference/endpoints/criar-grupo api-reference/openapi.json POST /api/v1/groups/create Crie um grupo do WhatsApp com participantes e configurações. Cria um grupo com um `name` e uma lista de `participants` (números no formato internacional). Suporta configurações avançadas na criação: * `admin_only_messages` — apenas admins enviam mensagens. * `admin_approval` — entradas exigem aprovação de admin. * `description`, `picture` — metadados do grupo. * `disappearing_messages` — mensagens temporárias (`24h`, `7d`, `90d`). > [!NOTE] > > Para grupos grandes, use `async` para criar o grupo de forma assíncrona e > evitar timeouts. Os participantes são adicionados em segundo plano. ## Comunidades ### Criar uma comunidade Envie `is_parent: true`. O WhatsApp cria a comunidade junto com o **grupo de avisos** e um subgrupo **Geral**. ```json theme={null} { "sessionId": "minha-sessao", "name": "Minha Comunidade", "participants": ["5511999999999"], "is_parent": true } ``` * A comunidade nasce só com você como admin. `participants` continua obrigatório, mas é ignorado nesse caso. * A resposta traz o JID da comunidade. Os JIDs do grupo de avisos e do Geral aparecem em `GET /api/v1/groups/list`; no `/info` de cada grupo, `is_community`, `linked_parent_jid` e `is_announcement_group` indicam o papel dele. * Membros entram pelo grupo de avisos: use `add` em `/groups/{groupId}/participants` com o JID dele. Um `add` no JID da comunidade é redirecionado para os avisos. * Admins são definidos no JID da comunidade, com `promote`/`demote`. A pessoa precisa já ser membro. ### Criar um grupo dentro da comunidade Envie `parent_jid` com o JID da comunidade. O grupo é criado já vinculado a ela, com os `participants` informados. ```json theme={null} { "sessionId": "minha-sessao", "name": "Turma A", "participants": ["5511999999999"], "parent_jid": "120363432278592836@g.us" } ``` `parent_jid` não pode ser usado junto com `is_parent`. ### Vincular um grupo existente Para levar um grupo que já existe para dentro da comunidade, use `POST /api/v1/groups/{groupId}/link` com o JID da comunidade em `parent_jid`. A sessão precisa ser admin da comunidade. ```json theme={null} { "sessionId": "minha-sessao", "parent_jid": "120363432278592836@g.us" } ``` > [!NOTE] > > Vincular um grupo segundos depois de criá-lo costuma falhar. Para ter um grupo > novo dentro da comunidade, crie-o já com `parent_jid`. # Criar uma sessão Source: https://docs.d-api.cloud/api-reference/endpoints/criar-sessao api-reference/openapi.json POST /api/v1/sessions Crie ou inicie uma sessão do WhatsApp. Uma **sessão** é um número de WhatsApp gerenciado pela D-API. Use `type: "unofficial"` para o WhatsApp não oficial (via QR code) ou `type: "cloud_api"` para a API Oficial. Você pode já configurar o `webhookUrl` na criação para receber eventos em tempo real (mensagens, status, conexão). Veja a [documentação de webhooks](/whatsapp/webhooks/visao-geral). > [!TIP] > > Escolha um `sessionId` estável e único por número — ele é usado em > praticamente todos os outros endpoints. # Enviar imagem Source: https://docs.d-api.cloud/api-reference/endpoints/enviar-imagem api-reference/openapi.json POST /api/v1/messages/send/image Envie uma mensagem com imagem e legenda. Envia uma imagem para o destinatário. O campo `image` aceita uma **URL pública** ou o conteúdo em **base64**. Use `caption` para adicionar uma legenda. > [!NOTE] > > Formatos suportados incluem JPEG e PNG. Para arquivos grandes, prefira enviar > por URL — é mais rápido e evita payloads pesados. # Enviar mensagem de lista Source: https://docs.d-api.cloud/api-reference/endpoints/enviar-lista api-reference/openapi.json POST /api/v1/interactive/send/list Envie uma mensagem interativa com lista de opções. Mensagens de **lista** apresentam opções organizadas em seções, abertas por um botão (`buttonText`). Ótimas para menus, catálogos e fluxos de atendimento. A estrutura mínima exige `description`, `buttonText` e `sections`. Cada seção tem um título e uma lista de linhas (`rows`), cada uma com `title` e um identificador retornado quando o usuário seleciona a opção. > [!TIP] > > Use `title` e `footerText` para dar contexto ao menu. O identificador de cada > linha chega no webhook de mensagem recebida quando o usuário escolhe. # Enviar mensagem de texto Source: https://docs.d-api.cloud/api-reference/endpoints/enviar-texto api-reference/openapi.json POST /api/v1/messages/send/text Envie uma mensagem de texto simples via WhatsApp. O endpoint mais básico da API: envia texto para um número (`to`) a partir de uma sessão conectada (`sessionId`). O número usa o formato internacional sem `+` (ex: `5511999999999`). Recursos opcionais: * `linkPreview` — gera pré-visualização de links no texto. * `mentionAll` — menciona todos os participantes (em grupos). * `contextInfo` — responde a uma mensagem (reply), menciona contatos ou encaminha, via JSON do ContextInfo. > [!TIP] > > Para responder a uma mensagem específica, informe o `stanzaId` e o > `participant` da mensagem original dentro de `contextInfo`. # Gerar código de migração (OTP) Source: https://docs.d-api.cloud/api-reference/endpoints/gerar-otp api-reference/openapi.json POST /api/v1/sessions/{sessionId}/migration-otp Gere um código de uso único para migrar uma sessão do WhatsApp Web. Gera um **código de uso único** (8 caracteres, `A-Z0-9`) vinculado a uma sessão. O código é exibido ao usuário final, que o informa na extensão **Assistente de Integração** para migrar uma conexão do WhatsApp Web **já autenticada** para esta sessão — sem escanear o QR code. * **Validade:** 30 minutos. * **Uso único:** consumido na primeira migração bem-sucedida (uma falha mantém o código válido até expirar, permitindo nova tentativa). * **Autenticação:** sua `apiKey` no header `Authorization`. A sessão informada em `sessionId` precisa pertencer à sua conta. > [!NOTE] > > Este endpoint apenas **gera** o código. A migração em si é feita pela extensão, > que lê as credenciais da sessão do WhatsApp Web e as envia junto com o código. > Veja [Instalar o Assistente de Integração](/whatsapp/instalar-assistente). > [!TIP] > > No painel, o código também aparece na tela **Conectar dispositivo**, logo abaixo > do QR code, pronto para copiar. # Obter informações do contato Source: https://docs.d-api.cloud/api-reference/endpoints/obter-contato api-reference/openapi.json GET /api/v1/contacts/{phone} Dados de um contato, com foto e perfil WhatsApp Business. Retorna os dados de um contato: nomes, `username`, se a conta é Business (`isBusiness`) ou API Oficial (`isOfficial`), recado (`status`) e foto (`avatar`). O `POST /api/v1/contacts/getuser` devolve a mesma resposta, com os parâmetros no body. ## Perfil WhatsApp Business Quando o contato é uma conta business (app WhatsApp Business ou API Oficial), a resposta traz `data.businessProfile` com o perfil comercial público: descrição, e-mail, endereço, sites, localização, categorias, horário de atendimento, contas vinculadas do Instagram e do Facebook, serviços oferecidos e capa. O perfil vem **por padrão**. Ele custa uma consulta a mais ao WhatsApp (até 10 s); se você não precisa dele, desligue com `business=false` (query) no `GET` ou `"business": false` (body) no `POST`. > [!NOTE] > > `businessProfile` só existe para contas business e quando a consulta dá certo. > Em contato pessoal, com `business=false` ou se o WhatsApp não responder a tempo, > a chave **não vem** — o resto do contato chega normalmente. Trate o campo como > opcional. ```json theme={null} { "success": true, "commandId": "b7e2c1d4-5f60-4a8b-9c3d-1e2f3a4b5c6d", "data": { "jid": "5511988887777@s.whatsapp.net", "phone": "5511988887777", "lid": "163896103039140@lid", "contactName": "Minha Empresa", "pushName": "Minha Empresa", "username": "", "isBusiness": true, "isOfficial": false, "isOnWhatsApp": true, "status": "Atendimento de segunda a sábado", "avatar": "https://s3.us-east-005.backblazeb2.com/d-api-media/avatars/5511988887777.jpg", "businessProfile": { "description": "Agência de marketing digital", "email": "contato@minhaempresa.com.br", "address": "Avenida Paulista, 1000, São Paulo SP", "websites": ["https://minhaempresa.com.br", "https://loja.minhaempresa.com.br/"], "location": { "latitude": -23.5632, "longitude": -46.6543 }, "categories": [{ "id": "123377808095874", "name": "Agência de marketing" }], "businessHours": { "timezone": "America/Sao_Paulo", "days": [ { "dayOfWeek": "mon", "mode": "specific_hours", "openTime": "08:00", "closeTime": "12:00" }, { "dayOfWeek": "mon", "mode": "specific_hours", "openTime": "13:30", "closeTime": "18:00" }, { "dayOfWeek": "sat", "mode": "appointment_only", "openTime": "", "closeTime": "" } ] }, "instagram": { "handle": "minhaempresa", "followers": 1494, "url": "https://www.instagram.com/minhaempresa/" }, "facebook": { "id": "1132445806627829", "name": "Minha Empresa", "likes": 17, "url": "https://www.facebook.com/1132445806627829" }, "offerings": [ { "category": "Opções de pagamento e estacionamento", "items": [{ "id": "business_pix_accepted", "name": "Aceitamos Pix", "offered": true }] } ], "coverPhotoUrl": "https://media.cdn.whatsapp.net/v/t61.24694-24/...", "commerceExperience": "catalog", "cartEnabled": true, "accountType": "smb", "verificationLevel": "unknown", "automatedType": "unknown", "memberSince": "2023-07-03T19:35:10Z", "memberSinceText": "Empresa cadastrada desde julho, 2023." } }, "timestamp": "2026-11-05T22:10:00.000Z" } ``` ### Campos de `businessProfile` **description** `string` Descrição do negócio **email** `string` E-mail público **address** `string` Endereço **websites** `string[]` Sites cadastrados (lista vazia quando não há). Algumas empresas colocam o link do Instagram aqui em vez de vincular a conta. **location** `object | null` `{ latitude, longitude }` do local fixado no perfil, ou `null` **categories** `object[]` Categorias do negócio: `{ id, name }` **businessHours** `object` **Campos de businessHours** **timezone** `string` Fuso horário do horário de atendimento (ex: `America/Sao_Paulo`) **days** `object[]` Uma entrada por faixa de horário. Turno partido (ex: manhã e tarde) gera **duas entradas no mesmo dia**. **Campos de days** **dayOfWeek** `string` `mon` | `tue` | `wed` | `thu` | `fri` | `sat` | `sun` **mode** `string` `specific_hours` (horário definido) | `open_24h` (24 horas) | `appointment_only` (só com agendamento) **openTime** `string` Abertura em `HH:MM`. Vazio quando `mode` não é `specific_hours` **closeTime** `string` Fechamento em `HH:MM`. Vazio quando `mode` não é `specific_hours` **instagram** `object | null` Conta do Instagram vinculada: `{ handle, followers, url }`, ou `null` **facebook** `object | null` Página do Facebook vinculada: `{ id, name, likes, url }`, ou `null` **offerings** `object[]` Serviços e comodidades marcados no perfil, agrupados por categoria: `{ category, items: [{ id, name, offered }] }` **coverPhotoUrl** `string` Foto de capa. É um link assinado do CDN do WhatsApp que **expira** — baixe a imagem se precisar guardá-la. **commerceExperience** `string` `catalog` | `shop` | `none` **cartEnabled** `boolean` Se o carrinho de compras está ativo **accountType** `string` `smb` (app WhatsApp Business) | `ent` (API / conta hospedada) **verificationLevel** `string` Nível de verificação informado pelo WhatsApp **automatedType** `string` Tipo de automação informado pelo WhatsApp **memberSince** `string` Data de cadastro da empresa em RFC 3339, ou vazio quando o WhatsApp não informa **memberSinceText** `string` O mesmo dado em texto, como o WhatsApp exibe # Definir descrição do grupo Source: https://docs.d-api.cloud/api-reference/grupos/definir-descrição-do-grupo /api-reference/openapi.json put /api/v1/groups/{groupId}/description Altera a descrição/tópico de um grupo # Definir foto do grupo Source: https://docs.d-api.cloud/api-reference/grupos/definir-foto-do-grupo /api-reference/openapi.json put /api/v1/groups/{groupId}/profile-picture Altera a foto de perfil do grupo. Aceita base64 (data:image/jpeg;base64,...) ou URL da imagem # Definir nome do grupo Source: https://docs.d-api.cloud/api-reference/grupos/definir-nome-do-grupo /api-reference/openapi.json put /api/v1/groups/{groupId}/name Altera o nome (subject) de um grupo # Entrar no grupo Source: https://docs.d-api.cloud/api-reference/grupos/entrar-no-grupo /api-reference/openapi.json post /api/v1/groups/{groupId}/join Entra em um grupo usando o ID do grupo # Gerenciar participantes do grupo Source: https://docs.d-api.cloud/api-reference/grupos/gerenciar-participantes-do-grupo /api-reference/openapi.json post /api/v1/groups/{groupId}/participants Adiciona, remove, promove ou rebaixe participantes de um grupo # Listar grupos Source: https://docs.d-api.cloud/api-reference/grupos/listar-grupos /api-reference/openapi.json get /api/v1/groups/list Lista todos os grupos do WhatsApp da sessão. Use 'participants=true' para incluir informações dos participantes (padrão: false). Use 'timeout' (em ms) para ajustar o timeout (padrão: 30000ms, máximo: 300000ms) # Obter convite do grupo Source: https://docs.d-api.cloud/api-reference/grupos/obter-convite-do-grupo /api-reference/openapi.json get /api/v1/groups/{groupId}/invite Obtém o link de convite de um grupo # Obter informações do grupo Source: https://docs.d-api.cloud/api-reference/grupos/obter-informações-do-grupo /api-reference/openapi.json get /api/v1/groups/{groupId}/info Obtém informações detalhadas de um grupo específico # Sair do grupo Source: https://docs.d-api.cloud/api-reference/grupos/sair-do-grupo /api-reference/openapi.json post /api/v1/groups/{groupId}/leave Sai de um grupo específico # Vincular grupo a uma comunidade Source: https://docs.d-api.cloud/api-reference/grupos/vincular-grupo-a-uma-comunidade /api-reference/openapi.json post /api/v1/groups/{groupId}/link Move um grupo existente para dentro de uma comunidade. Só admins da comunidade podem vincular. # Introdução Source: https://docs.d-api.cloud/api-reference/introduction Base URL, autenticação, erros e limites da API REST da D-API. A API REST da D-API permite enviar mensagens, gerenciar sessões do WhatsApp, grupos, contatos, mídia e muito mais. Esta referência é gerada a partir da especificação OpenAPI oficial e mantida em sincronia com a API em produção. ## Base URL Todos os endpoints usam a base URL: ``` https://api.d-api.cloud ``` ## Autenticação A API usa autenticação por **API Key** enviada no header `Authorization`. Gere a sua chave no [painel](https://app.d-api.cloud). ```bash theme={null} curl https://api.d-api.cloud/api/v1/sessions \ -H "Authorization: SUA_API_KEY" ``` > [!WARNING] > > Nunca exponha sua API Key no front-end ou em repositórios públicos. Trate-a > como uma senha. ## Formato de erro Respostas de erro seguem um envelope JSON consistente, com o status HTTP indicando a categoria (`4xx` para erros do cliente, `5xx` para erros do servidor). ```json theme={null} { "success": false, "error": "Mensagem descritiva do erro", "statusCode": 400 } ``` ## Identificadores A maioria das operações exige um `sessionId` — o identificador da sua sessão do WhatsApp. Destinatários (`to`) usam o número no formato internacional sem `+` (ex: `5511999999999`). ## Limites A API tem alta disponibilidade (99.9% de uptime) e latência inferior a 30ms. Limites de uso por plano estão disponíveis no endpoint `GET /api/v1/limits/{sessionId}` e no [painel](https://app.d-api.cloud). ## Próximos passos > [card] [Quickstart](/api-reference/quickstart) > > Do zero ao primeiro envio em poucos minutos. > [card] [Conectar via QR](/api-reference/endpoints/conectar-qr) > > Conecte uma sessão lendo o QR code. # Retorna informações básicas sobre a API Source: https://docs.d-api.cloud/api-reference/início/retorna-informações-básicas-sobre-a-api /api-reference/openapi.json get / # Retorna o status de saúde da API incluindo DB, RabbitMQ e Redis Source: https://docs.d-api.cloud/api-reference/início/retorna-o-status-de-saúde-da-api-incluindo-db-rabbitmq-e-redis /api-reference/openapi.json get /health # Enviar mensagem carousel Source: https://docs.d-api.cloud/api-reference/mensagens-interativas/enviar-mensagem-carousel /api-reference/openapi.json post /api/v1/interactive/send/carousel Envia uma mensagem carousel com múltiplos cards (máximo 10 cards, 2 botões por card) via WhatsApp. Na API Oficial: só dentro da janela de 24h. Exige body, 2 a 10 cards, todos com header de imagem ou vídeo e o mesmo tipo e quantidade de botões (um url ou quick_reply). title e footer entram no body; o footer do card entra no texto do card (até 160 caracteres). # Enviar mensagem com botão PIX Source: https://docs.d-api.cloud/api-reference/mensagens-interativas/enviar-mensagem-com-botão-pix /api-reference/openapi.json post /api/v1/interactive/send/pix Envia uma mensagem com botão de cópia PIX (com valor opcional) via WhatsApp. Na API Oficial: só dentro da janela de 24h. Sai como texto com a chave Pix em linha própria, o valor e a mensagem (a Meta não tem botão de copiar em mensagem livre). # Enviar mensagem NativeFlow (Mobile apenas) Source: https://docs.d-api.cloud/api-reference/mensagens-interativas/enviar-mensagem-nativeflow-mobile-apenas /api-reference/openapi.json post /api/v1/interactive/send/nativeflow Envia uma mensagem NativeFlow com botões interativos (quick_reply, url, call, copy) - APENAS MOBILE via WhatsApp. Na API Oficial: só dentro da janela de 24h. Até 3 quick_reply viram botões nativos; sem quick_reply, o primeiro url vira botão nativo. A Meta não tem botão de call nem de copy em mensagem livre: eles (e os demais) entram no texto como "Título: valor". # Enviar mensagem template Source: https://docs.d-api.cloud/api-reference/mensagens-interativas/enviar-mensagem-template /api-reference/openapi.json post /api/v1/interactive/send/template Envia uma mensagem template com botões CTA (URL e Call) via WhatsApp. Na API Oficial: só dentro da janela de 24h. O primeiro botão url vira botão nativo; os demais e os de call entram no texto como "Título: valor". # Enviar contato Source: https://docs.d-api.cloud/api-reference/mensagens/enviar-contato /api-reference/openapi.json post /api/v1/messages/send/contact Envia um cartão de contato via WhatsApp # Enviar enquete Source: https://docs.d-api.cloud/api-reference/mensagens/enviar-enquete /api-reference/openapi.json post /api/v1/messages/send/poll Envia uma mensagem de enquete com pergunta e opções de resposta # Enviar localização Source: https://docs.d-api.cloud/api-reference/mensagens/enviar-localização /api-reference/openapi.json post /api/v1/messages/send/location Envia uma localização com coordenadas GPS via WhatsApp # Enviar mensagem com documento Source: https://docs.d-api.cloud/api-reference/mensagens/enviar-mensagem-com-documento /api-reference/openapi.json post /api/v1/messages/send/document Envia um documento (PDF, DOC, etc.) via WhatsApp # Enviar mensagem com vídeo Source: https://docs.d-api.cloud/api-reference/mensagens/enviar-mensagem-com-vídeo /api-reference/openapi.json post /api/v1/messages/send/video Envia um vídeo com legenda opcional, suporte a video note (ptv) e GIF playback # Enviar mensagem com áudio Source: https://docs.d-api.cloud/api-reference/mensagens/enviar-mensagem-com-áudio /api-reference/openapi.json post /api/v1/messages/send/audio Envia um áudio ou nota de voz (ptt) via WhatsApp # Enviar reação Source: https://docs.d-api.cloud/api-reference/mensagens/enviar-reação /api-reference/openapi.json post /api/v1/messages/send/reaction Envia uma reação emoji para uma mensagem específica. Envie emoji vazio para remover a reação. # Enviar sticker Source: https://docs.d-api.cloud/api-reference/mensagens/enviar-sticker /api-reference/openapi.json post /api/v1/messages/send/sticker Envia um sticker via WhatsApp # Enviar álbum Source: https://docs.d-api.cloud/api-reference/mensagens/enviar-álbum /api-reference/openapi.json post /api/v1/messages/send/album Envia múltiplas imagens/vídeos como um álbum # Migrar sessão do WhatsApp Web com código único Source: https://docs.d-api.cloud/api-reference/migração/migrar-sessão-do-whatsapp-web-com-código-único /api-reference/openapi.json post /api/v1/session-migration/migrate # Quickstart Source: https://docs.d-api.cloud/api-reference/quickstart Crie uma sessão, conecte o WhatsApp e envie a primeira mensagem. Este guia leva você do zero ao primeiro envio. Você vai precisar de uma [API Key](https://app.d-api.cloud). ## 1. Crie uma sessão Uma **sessão** representa um número de WhatsApp conectado. Crie uma com um `sessionId` à sua escolha. ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/sessions \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sessionId": "minha-sessao", "type": "unofficial" }' ``` ## 2. Conecte lendo o QR code Obtenha o QR code da sessão e escaneie com o WhatsApp do celular (**Aparelhos conectados → Conectar um aparelho**). ```bash theme={null} curl "https://api.d-api.cloud/api/v1/sessions/minha-sessao/qr?image=1" \ -H "Authorization: SUA_API_KEY" \ --output qr.png ``` > [!TIP] > > Sem o parâmetro `?image=1`, o endpoint retorna os dados do QR em JSON, úteis > para renderizar o código no seu próprio front-end. ## 3. Envie a primeira mensagem Com a sessão conectada, envie uma mensagem de texto. ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/messages/send/text \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sessionId": "minha-sessao", "to": "5511999999999", "text": "Olá do D-API! 🚀" }' ``` Pronto — você enviou sua primeira mensagem. Explore os [guias](/api-reference/endpoints/criar-sessao) e a referência completa de endpoints para os próximos passos. # Atualizar armazenamento de mensagens Source: https://docs.d-api.cloud/api-reference/sessões/atualizar-armazenamento-de-mensagens /api-reference/openapi.json post /api/v1/sessions/{sessionId}/disable-message-storage-settings Atualiza a configuração disable_message_storage. Quando ativada, o conteúdo das mensagens NÃO é persistido no banco para esta conexão. Os contatos continuam sendo armazenados (para resolução de LID) e os webhooks não são afetados. # Atualizar configurações de chamada Source: https://docs.d-api.cloud/api-reference/sessões/atualizar-configurações-de-chamada /api-reference/openapi.json post /api/v1/sessions/{sessionId}/call-settings Atualiza as configurações reject_calls e reject_calls_message da sessão. Elas controlam a recusa automática de chamadas e a mensagem de resposta automática. # Atualizar filtros de mensagens Source: https://docs.d-api.cloud/api-reference/sessões/atualizar-filtros-de-mensagens /api-reference/openapi.json post /api/v1/sessions/{sessionId}/ignore-settings Atualiza as configurações ignore_groups e ignore_status da sessão. Elas controlam se mensagens de grupos e atualizações de status são descartadas. # Atualizar marcação automática como lida Source: https://docs.d-api.cloud/api-reference/sessões/atualizar-marcação-automática-como-lida /api-reference/openapi.json post /api/v1/sessions/{sessionId}/mark-previous-as-read-settings Atualiza a configuração mark_previous_as_read da sessão. Quando ativada, as mensagens anteriores são marcadas como lidas automaticamente após o envio de uma mensagem. # Atualizar modo de entrega de comandos Source: https://docs.d-api.cloud/api-reference/sessões/atualizar-modo-de-entrega-de-comandos /api-reference/openapi.json post /api/v1/sessions/{sessionId}/command-mode Atualiza o modo de entrega de comandos da sessão. 'rabbitmq' (padrão) usa a fila de mensagens; 'http' envia os comandos direto ao pod, com a fila como fallback. Use 'http' para testes com menor latência. # Atualizar recebimento de chamadas Source: https://docs.d-api.cloud/api-reference/sessões/atualizar-recebimento-de-chamadas /api-reference/openapi.json post /api/v1/sessions/{sessionId}/receive-calls-settings Ativa ou desativa o recebimento e o atendimento de chamadas do WhatsApp nesta conexão. Desativado por padrão: ao ativar, o bridge pré-aceita as chamadas recebidas, o que sobe a mídia mesmo para chamadas que ninguém atende. Ative apenas se o seu sistema for tratar os eventos call.offer (com POST /calls/accept ou POST /calls/reject). Indisponível em conexões cloud_api. A alteração muda a env do pod, então vale a partir do próximo restart. # Atualizar uso do código do Brasil Source: https://docs.d-api.cloud/api-reference/sessões/atualizar-uso-do-código-do-brasil /api-reference/openapi.json post /api/v1/sessions/{sessionId}/assume-br-country-code-settings Atualiza a configuração assume_br_country_code. Quando ativada, as rotas de envio assumem Brasil (+55) para números sem código do país (com validação de DDD). # Atualizar webhook de uma sessão Source: https://docs.d-api.cloud/api-reference/sessões/atualizar-webhook-de-uma-sessão /api-reference/openapi.json post /api/v1/sessions/{sessionId}/webhook Atualiza a URL do webhook de uma sessão existente. O webhook será usado para receber notificações de eventos da sessão. # Dados de uma sessão Source: https://docs.d-api.cloud/api-reference/sessões/dados-de-uma-sessão /api-reference/openapi.json get /api/v1/sessions/{sessionId} Retorna os dados de uma sessão do WhatsApp, incluindo status e configurações # Deletar uma sessão Source: https://docs.d-api.cloud/api-reference/sessões/deletar-uma-sessão /api-reference/openapi.json delete /api/v1/sessions/{sessionId} Deleta uma sessão existente e desconecta o WhatsApp se estiver conectado. Aceita tanto o UUID (id) quanto o session_id como parâmetro. # Desconectar uma sessão Source: https://docs.d-api.cloud/api-reference/sessões/desconectar-uma-sessão /api-reference/openapi.json post /api/v1/sessions/{sessionId}/disconnect Desconecta uma sessão existente do WhatsApp sem deletá-la do banco de dados # Enviar a assinatura de passkey por código (fallback popup) Source: https://docs.d-api.cloud/api-reference/sessões/enviar-a-assinatura-de-passkey-por-código-fallback-popup /api-reference/openapi.json post /api/v1/session-passkey/{code} # Enviar a assinatura WebAuthn (passkey) de uma sessão Source: https://docs.d-api.cloud/api-reference/sessões/enviar-a-assinatura-webauthn-passkey-de-uma-sessão /api-reference/openapi.json post /api/v1/sessions/{sessionId}/auth/passkey Encaminha a assertion assinada ao bridge (SendPasskeyResponse) para concluir o pareamento por passkey. # Gerar código de fallback para passkey (popup) Source: https://docs.d-api.cloud/api-reference/sessões/gerar-código-de-fallback-para-passkey-popup /api-reference/openapi.json post /api/v1/sessions/{sessionId}/auth/passkey/code Gera um código curto de uso único (TTL 5min) que o usuário digita na extensão para concluir o passkey quando o caminho page-callable não está disponível. # Importar sessão migrada do WhatsApp Web Source: https://docs.d-api.cloud/api-reference/sessões/importar-sessão-migrada-do-whatsapp-web /api-reference/openapi.json post /api/v1/sessions/{sessionId}/import-web-auth # Listar todas as sessões Source: https://docs.d-api.cloud/api-reference/sessões/listar-todas-as-sessões /api-reference/openapi.json get /api/v1/sessions Lista sessões com paginação, busca e filtros # Logs de uma sessão Source: https://docs.d-api.cloud/api-reference/sessões/logs-de-uma-sessão /api-reference/openapi.json get /api/v1/sessions/{sessionId}/logs Retorna os logs de uma sessão do WhatsApp, incluindo status e configurações # Obter o código de pareamento de uma sessão Source: https://docs.d-api.cloud/api-reference/sessões/obter-o-código-de-pareamento-de-uma-sessão /api-reference/openapi.json get /api/v1/sessions/{sessionId}/pair-code Retorna os dados do código de pareamento de uma sessão configurada para usar pareamento por código. # Obter o desafio de passkey por código (fallback popup) Source: https://docs.d-api.cloud/api-reference/sessões/obter-o-desafio-de-passkey-por-código-fallback-popup /api-reference/openapi.json get /api/v1/session-passkey/{code} # Obter o desafio WebAuthn (passkey) de uma sessão Source: https://docs.d-api.cloud/api-reference/sessões/obter-o-desafio-webauthn-passkey-de-uma-sessão /api-reference/openapi.json get /api/v1/sessions/{sessionId}/auth/passkey Retorna o PublicKeyCredentialRequestOptions emitido pelo bridge para assinatura pela extensão, e o código de confirmação quando disponível. # Passkey connect disponível? Source: https://docs.d-api.cloud/api-reference/sessões/passkey-connect-disponível? /api-reference/openapi.json get /api/v1/sessions/passkey/available Reporta se o modo de conexão por passkey (WebAuthn) está habilitado. # Reconectar uma sessão com restart do pod Source: https://docs.d-api.cloud/api-reference/sessões/reconectar-uma-sessão-com-restart-do-pod /api-reference/openapi.json get /api/v1/sessions/{sessionId}/connect Força a reconexão de uma sessão existente reiniciando o pod Kubernetes e usando o webhookUrl configurado na sessão. Se o restart do pod falhar, executa um fallback com reconexão simples. # Salvar configurações do RabbitMQ Source: https://docs.d-api.cloud/api-reference/sessões/salvar-configurações-do-rabbitmq /api-reference/openapi.json post /api/v1/sessions/{sessionId}/rabbitmq-config Salva as configurações de conexão do RabbitMQ para uma sessão específica # Salvar configurações do Webhook Source: https://docs.d-api.cloud/api-reference/sessões/salvar-configurações-do-webhook /api-reference/openapi.json post /api/v1/sessions/{sessionId}/webhook-config Salva as configurações de webhook para uma sessão específica # Eventos Source: https://docs.d-api.cloud/sms/webhooks/eventos Eventos de status de entrega de SMS e códigos de erro normalizados. Os webhooks de SMS notificam o **status final de entrega** de cada mensagem. Cada evento define o valor do campo `status`. Os exemplos abaixo usam o [envelope do webhook de conta](/sms/webhooks/visao-geral); o envelope por campanha carrega os mesmos campos no nível raiz. ## Eventos e status resultante | Evento | Quando dispara | `status` resultante | | - | - | - | | `sms.delivered` | A mensagem foi **entregue** ao destinatário | `delivered` | | `sms.undelivered` | A operadora reportou que a mensagem **não foi entregue** | `undelivered` | | `sms.failed` | **Falha de rede após o aceite** — a mensagem já foi cobrada | `undelivered` | | `sms.expired` | A mensagem **expirou** antes de ser entregue | `expired` | > [!NOTE] > > `sms.failed` mapeia para o status `undelivered`. Trata-se de uma falha de rede > ocorrida **após o aceite** do envio: como a cobrança fecha no aceite, a > mensagem **já foi cobrada**. ## Campos de `data` (webhook de conta) **messageId** `string` *required* ID da mensagem. Permite correlacionar o evento com o envio original. **to** `string` *required* Número de destino em formato E.164. **status** `string` *required* Status resultante: `delivered`, `undelivered` ou `expired`. **errorCode** `string | null` *required* Código de erro normalizado em caso de falha, ou `null` quando não há erro. Veja a tabela de [códigos de erro](#c-digos-de-erro). **segments** `number` *required* Quantidade de segmentos (partes) do SMS. **timestamp** `string` *required* Momento do evento em ISO 8601 (UTC). ## Exemplos por evento > [accordion] sms.delivered — entregue > > ```json theme={null} > { > "event": "sms.delivered", > "channel": "sms", > "data": { > "messageId": "a1b2c3d4-...", > "to": "+5511999999999", > "status": "delivered", > "errorCode": null, > "segments": 1, > "timestamp": "2026-01-24T23:00:00.000Z" > }, > "timestamp": "2026-01-24T23:00:00.000Z" > } > ``` > [accordion] sms.undelivered — não entregue > > ```json theme={null} > { > "event": "sms.undelivered", > "channel": "sms", > "data": { > "messageId": "a1b2c3d4-...", > "to": "+5511999999999", > "status": "undelivered", > "errorCode": "INVALID_NUMBER", > "segments": 1, > "timestamp": "2026-01-24T23:00:00.000Z" > }, > "timestamp": "2026-01-24T23:00:00.000Z" > } > ``` > [accordion] sms.failed — falha de rede após o aceite > > ```json theme={null} > { > "event": "sms.failed", > "channel": "sms", > "data": { > "messageId": "a1b2c3d4-...", > "to": "+5511999999999", > "status": "undelivered", > "errorCode": "NETWORK_ERROR", > "segments": 1, > "timestamp": "2026-01-24T23:00:00.000Z" > }, > "timestamp": "2026-01-24T23:00:00.000Z" > } > ``` > [accordion] sms.expired — expirou > > ```json theme={null} > { > "event": "sms.expired", > "channel": "sms", > "data": { > "messageId": "a1b2c3d4-...", > "to": "+5511999999999", > "status": "expired", > "errorCode": null, > "segments": 1, > "timestamp": "2026-01-24T23:00:00.000Z" > }, > "timestamp": "2026-01-24T23:00:00.000Z" > } > ``` ## Códigos de erro Quando há falha, o campo `errorCode` traz um valor **normalizado**. Os valores abaixo são os possíveis. | `errorCode` | Significado | | - | - | | `NETWORK_ERROR` | Erro de rede entre o gateway e a operadora | | `INVALID_NUMBER` | Número de destino inválido | | `LANDLINE` | Número de telefone fixo (não recebe SMS) | | `BLACKLIST` | Número em lista de bloqueio (blacklist) | | `CANCELED` | Envio cancelado | | `NO_WHATSAPP` | Destino sem WhatsApp | | `CONTENT_BLOCKED` | Conteúdo da mensagem bloqueado | | `NO_COVERAGE` | Sem cobertura para o destino | | `REJECTED` | Mensagem rejeitada pela operadora | | `NOT_RECEIVED` | Mensagem não recebida pelo destino | > [!NOTE] > > Em eventos de sucesso (`sms.delivered`) ou expiração (`sms.expired`), o campo > `errorCode` vem como `null`. # Visão geral dos webhooks Source: https://docs.d-api.cloud/sms/webhooks/visao-geral Como o D-API notifica seu sistema sobre o status de entrega dos SMS. Os webhooks de SMS notificam seu sistema sobre o **status de entrega** das mensagens enviadas: quando um SMS é **entregue**, **não entregue** ou **expira**. O produto é **outbound-only** — não há eventos de SMS recebido. ## Os dois canais Há dois canais independentes de webhook, que podem ser usados juntos ou separadamente. > [accordion] Webhook de conta — todos os envios > > Configurado **uma vez por conta** no painel. Dispara para **todos os > envios** da conta (API avulsa, disparos em massa e fluxos), independente da > campanha. Use quando um único endpoint concentra o status de tudo que a > conta envia. > [accordion] Webhook por campanha — apenas aquela campanha > > Configurado na própria campanha de disparo em massa. Dispara **somente** > para os destinatários daquela campanha. Use para rotear o status de uma > campanha específica a um endpoint dedicado. > [!NOTE] > > O evento `sms.sent` **não** é entregue aos webhooks: a cobrança e o aceite > acontecem no momento do envio, então só os eventos de status final são > notificados. O produto é **outbound-only** — não existe evento de SMS > recebido. ## Envelope — webhook de conta O webhook de conta envia o conteúdo do evento dentro de `data`, junto de `channel` e `timestamp` no nível raiz. ```json theme={null} { "event": "sms.delivered", "channel": "sms", "data": { "messageId": "a1b2c3d4-...", "to": "+5511999999999", "status": "delivered", "errorCode": null, "segments": 1, "timestamp": "2026-01-24T23:00:00.000Z" }, "timestamp": "2026-01-24T23:00:00.000Z" } ``` **event** `string` *required* Nome do evento (ex: `sms.delivered`). Veja [Eventos](/sms/webhooks/eventos). **channel** `string` *required* Canal de origem. Sempre `"sms"`. **data** `object` *required* Detalhes da entrega. Veja a página de [Eventos](/sms/webhooks/eventos) para cada campo. **timestamp** `string` *required* Momento do envio do webhook em ISO 8601 (UTC). ## Envelope — webhook por campanha O webhook por campanha é **plano**: os campos ficam no nível raiz e ele inclui `campaignId` e `recipientId` para correlação. ```json theme={null} { "event": "sms.delivered", "campaignId": "...", "recipientId": "...", "to": "+5511999999999", "status": "delivered", "errorCode": null, "segments": 1, "timestamp": "2026-01-24T23:00:00.000Z" } ``` **event** `string` *required* Nome do evento (ex: `sms.delivered`). **campaignId** `string` *required* ID da campanha que originou o disparo. **recipientId** `string` *required* ID do destinatário dentro da campanha. **to** `string` *required* Número de destino em formato E.164. **status** `string` *required* Status resultante da entrega. Veja [Eventos](/sms/webhooks/eventos). **errorCode** `string | null` *required* Código de erro normalizado em caso de falha, ou `null`. Veja a tabela de códigos em [Eventos](/sms/webhooks/eventos). **segments** `number` *required* Quantidade de segmentos (partes) do SMS. **timestamp** `string` *required* Momento do evento em ISO 8601 (UTC). ## Headers | Header | Valor | Canal | | - | - | - | | `Content-Type` | `application/json` | Ambos | | `X-DAPI-Webhook-Channel` | `sms` | Apenas webhook de conta | | `X-DAPI-Signature` | HMAC-SHA256 (hex) do corpo bruto | Ambos, somente se houver secret | A `X-DAPI-Signature` só é enviada quando um **secret** está configurado. Ela é o HMAC-SHA256, em hexadecimal, do **corpo bruto** (raw body) da requisição. > [!NOTE] > > O header `X-DAPI-Webhook-Channel` é enviado **somente** no webhook de conta. > O webhook por campanha envia apenas `Content-Type` (mais os headers > personalizados configurados na campanha, se houver) e, quando há secret, a > `X-DAPI-Signature`. ### Validando a assinatura Calcule o HMAC sobre o corpo **bruto** recebido (não sobre o JSON re-serializado) e compare com o header usando comparação de tempo constante (timing-safe): ```javascript theme={null} const sig = crypto.createHmac("sha256", secret).update(rawBody).digest("hex"); // comparar (timing-safe) com o header X-DAPI-Signature ``` ## Entrega e confiabilidade A garantia de entrega difere entre os dois canais. > [accordion] Webhook de conta — fila durável > > Entregue por uma **fila durável**, com **retentativas**, **circuit breaker** > por URL e **logs** de entrega (`webhook_logs`). Em caso de falha temporária, > a entrega é repetida automaticamente. > [accordion] Webhook por campanha — fire-and-forget > > Entregue por uma única chamada HTTP **sem retentativa** (fire-and-forget). > Se o endpoint estiver indisponível no momento, **o evento não é reenviado**. > [!WARNING] > > Como o webhook por campanha não tem retentativa, garanta que o endpoint > responda rapidamente e esteja disponível. Para entrega confiável, prefira o > **webhook de conta**. ## Próximos passos Veja a lista de eventos, o status resultante de cada um e os códigos de erro normalizados em [Eventos](/sms/webhooks/eventos). # Ligações por Stream Source: https://docs.d-api.cloud/ura/ligacoes/stream Ligue para qualquer telefone pela URA e troque o áudio da chamada em tempo real com o seu app, por WebSocket. As **Ligações URA por Stream** deixam o seu aplicativo conversar com um telefone (fixo ou celular) em tempo real: você inicia a ligação por uma chamada HTTP, abre um **WebSocket** e troca áudio nos dois sentidos — o seu áudio (microfone, robô, agente de IA) vai para o telefone, e a voz de quem atendeu volta para você. O contrato do WebSocket é **o mesmo** das [Ligações de WhatsApp por Stream](/whatsapp/ligacoes/stream): mesma URL, mesmo formato de áudio e o mesmo modelo de eventos. Se você já integrou o WhatsApp, reaproveita o código. > [!NOTE] > > Você precisa de **saldo na carteira** e da **API Key da conta**. A ligação é > cobrada da carteira com a mesma tarifa das ligações URA (veja > [Cobrança](#cobrança)). Gere a sua chave no [painel](https://app.d-api.cloud). ## Como funciona **1. Inicie a ligação** `POST /voice/live/start` reserva saldo, disca para o número e retorna um `callId` e uma `wsUrl` pronta para abrir. **2. Abra o WebSocket em até 30 segundos** O telefone já está tocando. Frames de **texto** são eventos; frames **binários** são áudio. **3. Troque áudio** Envie PCM binário e reproduza (ou processe) o PCM binário recebido. **4. Finalize** Feche o WebSocket para desligar. O valor é debitado pelo tempo falado e a gravação fica disponível. Por baixo, a D-API disca pela rede de telefonia e faz a ponte entre o telefone e o seu WebSocket, convertendo o áudio da telefonia (8 kHz) para o formato do stream (16 kHz) nos dois sentidos. ## Com o SDK Node O [`d-api-sdk`](https://www.npmjs.com/package/d-api-sdk) faz os passos abaixo por você. A ligação usa a mesma interface das chamadas de WhatsApp: ```js theme={null} import { DApi } from "d-api-sdk"; const dapi = new DApi({ apiKey: process.env.DAPI_API_KEY }); const call = await dapi.voice.live({ to: "5511999999999" }); call.on("audio", (frame) => speaker.write(frame)); // Int16Array, 16 kHz, mono, 20 ms mic.on("data", (chunk) => call.sendAudio(chunk)); call.on("event", (e) => e.type === "dtmf" && console.log("tecla", e.digit)); call.on("ended", (e) => console.log("fim", e.reason)); ``` Para o áudio ir por WebRTC, passe `{ transport: "webrtc" }` como segundo argumento de `voice.live()`; os detalhes estão em [WebRTC (recomendado)](/whatsapp/ligacoes/webrtc). ## Passo 1 — Inicie a ligação Chame `POST /voice/live/start` com o número de destino (com DDI, apenas dígitos). ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/voice/live/start \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "5551999998888" }' ``` A resposta traz o identificador da ligação e a URL do stream: ```json theme={null} { "success": true, "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "wsUrl": "wss://api.d-api.cloud/voip/stream?callId=a1b2c3d4-...&token=...", "token": "..." } ``` **callId** `string` Identificador da ligação. É o mesmo `callId` dos [webhooks](#webhooks) e da gravação. **wsUrl** `string` URL **opaca** do WebSocket, com `callId` e `token` já embutidos. Abra-a exatamente como veio — **não** monte a URL você mesmo. **token** `string` Token de acesso **exclusivo desta ligação**, gerado a cada chamada. Já está dentro da `wsUrl`. Ele **não** é a sua API Key: só abre o WebSocket desta ligação e deixa de valer quando ela termina. > [!WARNING] > > A sua **API Key nunca deve ir ao navegador**. Inicie a ligação **pelo seu > backend** e entregue ao navegador apenas a `wsUrl` — ela carrega só o token da > ligação. Mesmo assim, trate a `wsUrl` como um segredo de curta duração (não > registre em logs) enquanto a ligação está ativa. Um exemplo de início pelo backend, que mantém a chave fora do navegador: ```js theme={null} // backend do seu app — Node.js app.post("/api/iniciar-ligacao", async (req, res) => { const r = await fetch("https://api.d-api.cloud/api/v1/voice/live/start", { method: "POST", headers: { "Content-Type": "application/json", Authorization: process.env.DAPI_API_KEY, // fica só no servidor }, body: JSON.stringify({ to: req.body.to }), }); const data = await r.json(); if (!data.success) return res.status(r.status).json(data); res.json({ callId: data.callId, wsUrl: data.wsUrl }); // só isso vai ao navegador }); ``` ## Passo 2 — Conecte ao WebSocket A ligação **já foi discada** quando a resposta chega. Abra a `wsUrl` em até **30 segundos**: se o WebSocket não conectar nesse prazo, a ligação é desligada e a reserva de saldo é devolvida. ```js theme={null} const ws = new WebSocket(wsUrl); ws.binaryType = "arraybuffer"; ws.onmessage = (e) => { if (typeof e.data === "string") { handleEvent(JSON.parse(e.data)); // evento do ciclo de vida (Passo 4) } else { playDownlink(e.data); // áudio binário do telefone (Passo 3) } }; ``` Não há handshake pós-conexão: a autenticação está na URL. Se o servidor recusar, ele envia um evento `error` e fecha a conexão com o código `1008`. ## Passo 3 — Troque o áudio O áudio no WebSocket é **PCM cru** (`s16le`, **16 kHz**, **mono**), em frames de **20 ms = 320 amostras = 640 bytes**, nos dois sentidos. Veja a seção [Encoding de áudio](#encoding-de-áudio) para converter de/para outros formatos. > [tab] Navegador (atendente humano) > > No navegador o caminho é idêntico ao da ligação de WhatsApp: rode o > `AudioContext` a `sampleRate: 16000` (o navegador reamostra o microfone para > você) e converta Float32 ⇄ Int16 num `AudioWorklet`. Use o worklet > `voip-worklet.js` de referência da página [Ligações de WhatsApp por > Stream](/whatsapp/ligacoes/stream) sem nenhuma alteração. > > ```js theme={null} > const ctx = new AudioContext({ sampleRate: 16000 }); > await ctx.audioWorklet.addModule("/voip-worklet.js"); > > const mic = await navigator.mediaDevices.getUserMedia({ > audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true, autoGainControl: true }, > }); > const node = new AudioWorkletNode(ctx, "voip-io", { > numberOfInputs: 1, > numberOfOutputs: 1, > outputChannelCount: [1], > }); > ctx.createMediaStreamSource(mic).connect(node); > node.connect(ctx.destination); // voz do telefone -> alto-falante > > let canSendUplink = false; // liberado no evento "accepted" (Passo 4) > > node.port.onmessage = (ev) => { > if (ev.data?.kind === "out" && canSendUplink && ws.readyState === WebSocket.OPEN) { > ws.send(ev.data.pcm); > } > }; > > function playDownlink(buffer) { > node.port.postMessage({ kind: "in", pcm: buffer }, [buffer]); > } > ``` > > > [!TIP] > > > > Mantenha `echoCancellation: true`. Na telefonia o eco do alto-falante > > voltando pelo microfone é muito perceptível para quem está no telefone. > [tab] Servidor (robô / agente de IA) > > No servidor não há `AudioContext` nem relógio de áudio: **você** é responsável > por fatiar o áudio em frames de 640 bytes e enviá-los em **cadência de tempo > real** (um a cada 20 ms). Exemplo em Node.js com a biblioteca > [`ws`](https://www.npmjs.com/package/ws), que toca um arquivo PCM no telefone > e grava o que o telefone fala: > > ```js theme={null} > import WebSocket from "ws"; > import fs from "node:fs"; > > const FRAME_BYTES = 640; // 20 ms @ 16 kHz, s16le mono > const FRAME_MS = 20; > > const ws = new WebSocket(wsUrl); > const recebido = fs.createWriteStream("telefone.pcm"); // s16le 16 kHz mono > > ws.on("message", (data, isBinary) => { > if (isBinary) return recebido.write(data); // voz do telefone > const msg = JSON.parse(data.toString()); > if (msg.type === "accepted") tocar(fs.readFileSync("saudacao.pcm")); > if (msg.type === "ended" || msg.type === "error") ws.close(1000); > }); > ws.on("close", () => recebido.end()); > > // Envia o PCM em frames de 20 ms no ritmo do relógio (sem acumular deriva). > function tocar(pcm) { > const inicio = Date.now(); > let n = 0; > const tick = () => { > if (ws.readyState !== WebSocket.OPEN) return; > const frame = pcm.subarray(n * FRAME_BYTES, (n + 1) * FRAME_BYTES); > if (frame.length === 0) return; > ws.send(frame.length === FRAME_BYTES ? frame : padFrame(frame)); > n++; > setTimeout(tick, Math.max(0, inicio + n * FRAME_MS - Date.now())); > }; > tick(); > } > > function padFrame(frame) { > const out = Buffer.alloc(FRAME_BYTES); // completa o último frame com silêncio > frame.copy(out); > return out; > } > ``` > > Para gerar o `saudacao.pcm` a partir de qualquer áudio: > > ```bash theme={null} > ffmpeg -i saudacao.mp3 -ar 16000 -ac 1 -f s16le -acodec pcm_s16le saudacao.pcm > ``` > [!WARNING] > > **Não envie áudio antes do evento `accepted`.** Antes disso o telefone ainda está > tocando e o áudio é descartado. ## Encoding de áudio A rede de telefonia trafega voz em **banda estreita**: 8 kHz, normalmente em G.711 (μ-law/A-law), com conteúdo útil até \~3,4 kHz. A D-API cuida dessa ponta e entrega para você sempre o mesmo formato do stream de WhatsApp: | Ponto | Formato | | - | - | | **WebSocket (você ⇄ D-API)** | PCM `s16le`, **16 kHz**, mono, frames de 640 bytes / 20 ms | | Telefonia (D-API ⇄ telefone) | 8 kHz, convertido pela D-API com filtro anti-aliasing | | Gravação | WAV PCM 16 bits, 16 kHz, mono | Isso significa que **você nunca envia μ-law, A-law, base64, WAV, MP3 ou Opus pelo WebSocket** — só PCM cru de 16 kHz. Se o seu sistema trabalha em outro formato, converta na sua ponta antes de enviar e depois de receber. > [!NOTE] > > O áudio recebido do telefone vem em 16 kHz, mas o conteúdo é de telefonia: não > há nada acima de \~3,6 kHz. Isso é esperado — não é perda na D-API. ### Conversões mais comuns | Seu sistema usa | Para enviar ao WebSocket | Ao receber do WebSocket | | - | - | - | | PCM 16 kHz `s16le` | Envie direto | Use direto | | PCM 8 kHz `s16le` | Reamostre 8 → 16 kHz | Reamostre 16 → 8 kHz | | PCM 24 kHz (ex.: modelos de voz em tempo real) | Reamostre 24 → 16 kHz | Reamostre 16 → 24 kHz | | μ-law 8 kHz (G.711 PCMU) | Decodifique μ-law → PCM 8 kHz, reamostre 8 → 16 kHz | Reamostre 16 → 8 kHz, codifique PCM → μ-law | | Float32 (Web Audio, numpy) | Limite em \[-1, 1], multiplique por 32767, Int16 | Divida por 32768 | | WAV / MP3 / OGG (arquivo) | Converta com `ffmpeg` (abaixo) | Grave o PCM e adicione um cabeçalho WAV | Arquivos, com `ffmpeg`: ```bash theme={null} # qualquer arquivo -> PCM pronto para o WebSocket ffmpeg -i entrada.wav -ar 16000 -ac 1 -f s16le -acodec pcm_s16le saida.pcm # PCM recebido do WebSocket -> WAV para ouvir ffmpeg -f s16le -ar 16000 -ac 1 -i telefone.pcm telefone.wav # PCM recebido -> μ-law 8 kHz (ex.: para outro sistema de telefonia) ffmpeg -f s16le -ar 16000 -ac 1 -i telefone.pcm -ar 8000 -f mulaw telefone.ulaw ``` ### Funções de referência (Node.js) Implementações sem dependências para converter em tempo real, frame a frame. > [accordion] Reamostragem (8, 16, 24, 48 kHz...) > > Reamostrador linear com estado entre frames (sem estalos na emenda). Para > **reduzir** a taxa, ele aplica antes uma média móvel simples como filtro > passa-baixa. É suficiente para voz de telefonia; para qualidade de estúdio, > use `ffmpeg`/`libsoxr`. > > ```js theme={null} > // Converte Int16Array mono de `fromRate` para `toRate`, mantendo o estado entre chamadas. > export class Resampler { > constructor(fromRate, toRate) { > this.step = fromRate / toRate; > this.pos = 0; // posição fracionária no fluxo de entrada > this.last = 0; // última amostra do frame anterior > this.taps = Math.max(1, Math.round(this.step)); // tamanho da média móvel ao reduzir > this.hist = new Float64Array(this.taps); > this.hi = 0; > } > > push(input) { > const src = this.step > 1 ? this.lowPass(input) : Float64Array.from(input); > const out = []; > while (this.pos < src.length) { > const i = Math.floor(this.pos); > const frac = this.pos - i; > const a = i === 0 ? this.last : src[i - 1]; > const b = src[i]; > out.push(a + (b - a) * frac); > this.pos += this.step; > } > this.pos -= src.length; > this.last = src[src.length - 1] ?? this.last; > return Int16Array.from(out, (v) => Math.max(-32768, Math.min(32767, Math.round(v)))); > } > > lowPass(input) { > const out = new Float64Array(input.length); > for (let i = 0; i < input.length; i++) { > this.hist[this.hi] = input[i]; > this.hi = (this.hi + 1) % this.taps; > out[i] = this.hist.reduce((s, v) => s + v, 0) / this.taps; > } > return out; > } > } > > // Uso: um reamostrador por ligação e por sentido. > const paraWs = new Resampler(24000, 16000); // seu áudio 24 kHz -> WebSocket > const doWs = new Resampler(16000, 24000); // WebSocket -> seu sistema 24 kHz > ``` > [accordion] μ-law (G.711 PCMU) ⇄ PCM > > ```js theme={null} > export function muLawDecode(u) { > u = ~u & 0xff; > let t = ((u & 0x0f) << 3) + 0x84; > t <<= (u & 0x70) >> 4; > return u & 0x80 ? 0x84 - t : t - 0x84; > } > > export function muLawEncode(sample) { > const BIAS = 0x84; > const CLIP = 32635; > const sign = (sample >> 8) & 0x80; > if (sign) sample = -sample; > if (sample > CLIP) sample = CLIP; > sample += BIAS; > let exp = 7; > for (let mask = 0x4000; (sample & mask) === 0 && exp > 0; exp--, mask >>= 1); > const mantissa = (sample >> (exp + 3)) & 0x0f; > return ~(sign | (exp << 4) | mantissa) & 0xff; > } > > // μ-law 8 kHz -> frame para o WebSocket (16 kHz) > const up = new Resampler(8000, 16000); > function ulawParaWs(ulaw /* Buffer */) { > const pcm8 = Int16Array.from(ulaw, muLawDecode); > return Buffer.from(up.push(pcm8).buffer); > } > > // frame do WebSocket (16 kHz) -> μ-law 8 kHz > const down = new Resampler(16000, 8000); > function wsParaUlaw(frame /* Buffer */) { > const pcm16 = new Int16Array(Uint8Array.from(frame).buffer); // cópia alinhada > return Buffer.from(Uint8Array.from(down.push(pcm16), muLawEncode)); > } > ``` > [accordion] Ler o áudio recebido com segurança > > Não assuma que todo frame recebido tem exatamente 640 bytes. Acumule os bytes e > leia sempre um número **par** de bytes, em **little-endian**: > > ```js theme={null} > let sobra = Buffer.alloc(0); > > function onAudio(chunk /* Buffer */) { > const buf = Buffer.concat([sobra, chunk]); > const usaveis = buf.length - (buf.length % 2); > sobra = buf.subarray(usaveis); > // Copia para um ArrayBuffer alinhado antes de criar o Int16Array. > const pcm = new Int16Array(Uint8Array.from(buf.subarray(0, usaveis)).buffer); > processar(pcm); // Int16 16 kHz mono > } > ``` > [accordion] Gravar o PCM recebido como WAV > > ```js theme={null} > function wavHeader(dataBytes, sampleRate = 16000) { > const h = Buffer.alloc(44); > h.write("RIFF", 0); > h.writeUInt32LE(36 + dataBytes, 4); > h.write("WAVEfmt ", 8); > h.writeUInt32LE(16, 16); // tamanho do bloco fmt > h.writeUInt16LE(1, 20); // PCM > h.writeUInt16LE(1, 22); // mono > h.writeUInt32LE(sampleRate, 24); > h.writeUInt32LE(sampleRate * 2, 28); // byte rate > h.writeUInt16LE(2, 32); // block align > h.writeUInt16LE(16, 34); // bits por amostra > h.write("data", 36); > h.writeUInt32LE(dataBytes, 40); > return h; > } > > const wav = Buffer.concat([wavHeader(pcm.length), pcm]); > ``` > > Para **enviar** um WAV, descarte o cabeçalho (normalmente os 44 primeiros > bytes) e confira que ele já é 16 kHz, mono, 16 bits — senão converta com > `ffmpeg`. ### Diagnóstico de problemas de áudio | Sintoma | Causa provável | | - | - | | Voz **aguda e acelerada** ("esquilo") ou **grave e lenta** | Taxa de amostragem errada: enviando 8/24/48 kHz como se fosse 16 kHz (ou lendo o recebido em outra taxa) | | **Chiado / ruído branco** no lugar da voz | Endianness errado (big-endian), bytes desalinhados (número ímpar) ou envio de μ-law/WAV/MP3 em vez de PCM cru | | Áudio **picotado** ou com cortes | Envio em rajada em vez de 1 frame a cada 20 ms, ou falta de buffer de jitter na reprodução | | Telefone não ouve nada | Áudio enviado antes do `accepted`, ou microfone/faixa desativada | | Quem atende ouve **eco** | Alto-falante entrando no microfone sem `echoCancellation` | | Volume muito alto e distorcido | Float32 fora de \[-1, 1] convertido sem limitar (*clipping*) | ## Passo 4 — Acompanhe o ciclo de vida Os frames de **texto** do WebSocket são eventos JSON no formato `{ "type": ... }`. | `type` | Significado | O que fazer | | - | - | - | | `accepted` | **Telefone atendeu, áudio ao vivo.** A cobrança começa aqui | Liberar o envio de áudio | | `dtmf` | O telefone **pressionou uma tecla** (`digit`: `"0"`–`"9"`, `"*"`, `"#"`; `at`: instante em ms) | Tratar a opção escolhida | | `recording` | Gravação disponível | Guardar `url` / `files` | | `ended` | Ligação encerrada (com `reason`) | Encerrar e limpar | | `error` | Falha (com `code` / `msg`) | Mostrar erro e limpar | > [!NOTE] > > Diferente do WhatsApp, a telefonia **não emite `calling` nem `ringing`**: entre > a resposta do `POST /voice/live/start` e o `accepted`, o telefone está tocando. > Uma ligação **não atendida** (ocupado, sem resposta, recusada) termina com > `ended` **sem** ter passado por `accepted`. ```js theme={null} let atendeu = false; function handleEvent(msg) { switch (msg.type) { case "accepted": atendeu = true; canSendUplink = true; setStatus("em ligação"); break; case "dtmf": onKeyPress(msg.digit); break; case "recording": saveRecording(msg.url, msg.files); break; case "ended": setStatus(atendeu ? `encerrada: ${msg.reason}` : "não atendida"); cleanup(); break; case "error": setStatus(`erro: ${msg.msg || msg.code}`); cleanup(); break; } } ``` O `reason` do evento `ended`: | `reason` | Significado | | - | - | | `remote-hangup` | O telefone desligou — ou não atendeu, se não houve `accepted` | | `hangup` | Você desligou, ou o **saldo reservado acabou** (corte automático) | | `false-answer` | A operadora "atendeu" mas o áudio nunca chegou ao aparelho. **Não é cobrada** | | `setup-failed` | Falha ao conectar o áudio da ligação | | `terminate` | Duração máxima da ligação atingida | ## Passo 5 — Controle a ligação > [accordion] Mutar / desmutar > > Na URA o mute é **do seu lado**: pare de enviar frames de áudio (ou envie > silêncio). O controle `{ "type": "mute" }` do WhatsApp é ignorado aqui. > > ```js theme={null} > function setMuted(muted) { > mic.getAudioTracks().forEach((t) => (t.enabled = !muted)); > } > ``` > [accordion] Desligar > > **Fechar o WebSocket desliga a ligação.** Você também pode enviar um controle > por texto: > > ```js theme={null} > ws.send(JSON.stringify({ type: "hangup" })); // ou: ws.close(1000) > ``` ## Cobrança A ligação é paga com o **saldo da carteira**, na mesma tarifa das ligações URA do seu plano (**30/6**: primeiro bloco de 30 segundos, depois blocos de 6 segundos). * **Reserva no início.** O `POST /voice/live/start` reserva o valor de `min(duração máxima, tempo que o seu saldo cobre)`. Sem saldo para o primeiro bloco de 30 segundos, a resposta é `402`. * **Cobrança pelo tempo falado.** Conta do evento `accepted` até o fim. Ligações não atendidas e falsos atendimentos (`false-answer`) não são cobrados. * **Corte automático.** Quando o tempo reservado acaba, a ligação é desligada (`ended` com `reason: "hangup"`). Para ligações longas, mantenha saldo suficiente antes de discar. * **Devolução da sobra.** Ao encerrar, a parte não usada da reserva volta para o saldo disponível — inclusive se o WebSocket nunca conectar. ## Reconexão (opcional) Funciona como no WhatsApp: adicione `&resume=1` à `wsUrl` e uma queda do socket não desliga a ligação — ela aguarda você reconectar com a **mesma `wsUrl`** por até **20 segundos**. O tempo continua contando (e sendo cobrado) enquanto o socket está fora. Veja o exemplo de reconexão em [Ligações de WhatsApp por Stream](/whatsapp/ligacoes/stream). ## Gravação Toda ligação **atendida** é gravada. Perto do fim, o servidor envia: ```json theme={null} { "type": "recording", "files": { "full": "https://...", "sender": "https://...", "recipient": "https://..." }, "url": "https://..." } ``` Os arquivos são WAV mono de 16 kHz: `full` é a mixagem, `sender` é o seu lado e `recipient` é o telefone. A gravação também fica disponível depois em `GET /api/v1/calls/:callId`. Contas com armazenamento de mídia desativado não têm gravação. ## Webhooks As ligações por stream disparam os mesmos eventos do [webhook de conta do canal `voice`](/ura/webhooks/visao-geral) que as demais ligações URA, além de um evento com a gravação. O `data.callId` é **o mesmo `callId`** retornado por `POST /voice/live/start` — é ele que relaciona a resposta, o WebSocket, os webhooks e a gravação. Em ligações por stream, `bulkCallId` vem sempre `null`. | Evento | Quando dispara | | - | - | | `call.started` | A ligação foi discada (logo após o `POST /voice/live/start`) | | `call.answered` | O telefone atendeu (junto do evento `accepted` do WebSocket) | | `call.dtmf` | O telefone pressionou uma tecla (junto do evento `dtmf` do WebSocket) — um webhook por tecla, em `digits` | | `call.ended` | A ligação encerrou. `answered` e `talkSeconds` são os valores **cobrados** | | `call.audio` | A gravação de uma ligação atendida foi enviada | ```json theme={null} { "event": "call.ended", "channel": "voice", "data": { "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "bulkCallId": null, "to": "+5551999998888", "answered": true, "talkSeconds": 42, "digits": null, "cause": null, "causeDescription": null, "timestamp": "2026-01-24T23:01:02.000Z" }, "timestamp": "2026-01-24T23:01:02.000Z" } ``` > [!NOTE] > > Em ligações por stream, `cause` e `causeDescription` vêm `null`: o motivo do > encerramento chega pelo `reason` do evento `ended` no WebSocket. Falsos > atendimentos encerram com `answered: false` e não são cobrados. O `call.audio` traz os mesmos arquivos do evento `recording` do WebSocket: ```json theme={null} { "event": "call.audio", "channel": "voice", "data": { "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "to": "+5551999998888", "files": { "full": "https://...", "sender": "https://...", "recipient": "https://..." }, "url": "https://...", "durationMs": 42000, "sizeBytes": 1344044, "mimetype": "audio/wav", "timestamp": "2026-01-24T23:01:05.000Z" }, "timestamp": "2026-01-24T23:01:05.000Z" } ``` ## Erros e limites **402 Payment Required** Saldo insuficiente para o primeiro bloco de 30 segundos (`code: "insufficient_balance"`). **502 Bad Gateway** A operadora recusou a ligação (`code: "gateway_error"`). Nada é cobrado e a reserva é devolvida. **503 Service Unavailable** O stream de voz está indisponível no momento. Tente novamente mais tarde. **Conexão do WebSocket** `30 s` Prazo para abrir a `wsUrl` depois do início. Passou, a ligação é desligada. **Duração máxima** `3600 s` Ou menos, se o saldo cobrir menos tempo. Ao atingir, a ligação encerra. Os eventos `error` trazem um `code`: `unavailable`, `not_found`, `unauthorized` ou `forbidden`. ## Próximos passos > [card] [Ligações de WhatsApp por Stream](/whatsapp/ligacoes/stream) > > O mesmo WebSocket para chamadas de voz do WhatsApp, com o worklet de referência. > [card] [Referência da API](/api-reference/introduction) > > Autenticação e todos os endpoints da D-API. # Eventos Source: https://docs.d-api.cloud/ura/webhooks/eventos Eventos do ciclo de vida da ligação URA e tabela de códigos de cause. Os webhooks de URA acompanham o **ciclo de vida de cada ligação**, do início ao encerramento. Todos usam o [envelope do webhook de conta](/ura/webhooks/visao-geral): o conteúdo fica em `data`, com `channel: "voice"` e `timestamp` no nível raiz. Os campos não aplicáveis a um evento vêm como `null`. ## Eventos do ciclo de vida | Evento | Quando dispara | | - | - | | `call.started` | A ligação foi **iniciada** (demais campos `null`) | | `call.answered` | A ligação foi **atendida** (`answered: true`) | | `call.dtmf` | O destinatário **pressionou uma tecla** — um webhook por tecla | | `call.ended` | A ligação **encerrou** (traz duração e código de `cause`) | | `call.audio` | A gravação de uma [ligação por stream](/ura/ligacoes/stream#webhooks) foi enviada | ## Campos de `data` **callId** `string` *required* Identificador da ligação (o `bulkId` retornado no disparo, ou o `callId` retornado por `POST /voice/live/start` nas ligações por stream). Permite correlacionar todos os eventos da mesma ligação/lote. **bulkCallId** `string | null` *required* Identificador da chamada individual dentro do lote, ou `null` (sempre `null` nas ligações por stream). **to** `string | null` *required* Número de destino em formato E.164, ou `null`. **answered** `boolean | null` *required* `true` quando a ligação foi atendida. Em `call.answered` é sempre `true`. Em `call.ended` pode ser `true`, `false` ou `null`. Nos demais eventos, `null`. **talkSeconds** `number | null` *required* Tempo de conversação em segundos. Presente em `call.ended` (pode ser `null`); `null` nos demais eventos. **digits** `string | null` *required* Tecla pressionada em `call.dtmf` — um único caractere: `"0"`–`"9"`, `"*"` ou `"#"`. `null` nos demais eventos. **cause** `number | null` *required* Código numérico de encerramento (Q.850 + códigos próprios). Presente em `call.ended` (pode ser `null`); `null` nos demais eventos. Veja a [tabela de cause](#tabela-de-cause). **causeDescription** `string | null` *required* Descrição em pt-BR correspondente ao `cause`, ou `null`. Para um código sem descrição mapeada, retorna `Causa `. **timestamp** `string` *required* Momento do evento em ISO 8601 (UTC). ## Exemplos por evento > [accordion] call.started — ligação iniciada > > Os demais campos vêm como `null`. > > ```json theme={null} > { > "event": "call.started", > "channel": "voice", > "data": { > "callId": "...", > "bulkCallId": "...", > "to": "+5511999999999", > "answered": null, > "talkSeconds": null, > "digits": null, > "cause": null, > "causeDescription": null, > "timestamp": "2026-01-24T23:00:00.000Z" > }, > "timestamp": "2026-01-24T23:00:00.000Z" > } > ``` > [accordion] call.answered — ligação atendida > > `answered` é sempre `true`. > > ```json theme={null} > { > "event": "call.answered", > "channel": "voice", > "data": { > "callId": "...", > "bulkCallId": "...", > "to": "+5511999999999", > "answered": true, > "talkSeconds": null, > "digits": null, > "cause": null, > "causeDescription": null, > "timestamp": "2026-01-24T23:00:10.000Z" > }, > "timestamp": "2026-01-24T23:00:10.000Z" > } > ``` > [accordion] call.dtmf — tecla pressionada (um webhook por tecla) > > `digits` traz **uma** tecla. Cada tecla pressionada gera um webhook > separado. > > ```json theme={null} > { > "event": "call.dtmf", > "channel": "voice", > "data": { > "callId": "...", > "bulkCallId": "...", > "to": "+5511999999999", > "answered": null, > "talkSeconds": null, > "digits": "1", > "cause": null, > "causeDescription": null, > "timestamp": "2026-01-24T23:00:20.000Z" > }, > "timestamp": "2026-01-24T23:00:20.000Z" > } > ``` > [accordion] call.ended — ligação encerrada > > Traz `talkSeconds`, `cause` e `causeDescription`. > > ```json theme={null} > { > "event": "call.ended", > "channel": "voice", > "data": { > "callId": "...", > "bulkCallId": "...", > "to": "+5511999999999", > "answered": true, > "talkSeconds": 42, > "digits": null, > "cause": 16, > "causeDescription": "Encerramento normal", > "timestamp": "2026-01-24T23:01:02.000Z" > }, > "timestamp": "2026-01-24T23:01:02.000Z" > } > ``` ## Tabela de `cause` O campo `cause` segue os códigos **Q.850** acrescidos de dois códigos próprios (`150` e `151`). O `causeDescription` traz a descrição correspondente em pt-BR. | `cause` | `causeDescription` | | - | - | | `0` | Desconhecido | | `1` | Número inexistente | | `16` | Encerramento normal | | `17` | Ocupado | | `18` | Sem resposta do usuário | | `19` | Não atendeu | | `20` | Assinante ausente | | `21` | Chamada rejeitada | | `22` | Número alterado | | `27` | Destino fora de serviço | | `28` | Número inválido | | `31` | Normal, não especificado | | `34` | Sem canal disponível | | `38` | Rede fora de serviço | | `41` | Falha temporária | | `42` | Congestionamento | | `44` | Canal solicitado indisponível | | `50` | Facilidade não assinada | | `57` | Capacidade não autorizada | | `58` | Capacidade indisponível | | `65` | Capacidade não implementada | | `88` | Destino incompatível | | `102` | Expiração de temporizador | | `111` | Erro de protocolo | | `127` | Interfuncionamento não especificado | | `150` | Não atendeu (tempo de toque esgotado) | | `151` | Caixa postal / secretária eletrônica | > [!NOTE] > > Para um `cause` sem descrição mapeada na tabela, o `causeDescription` retorna > o texto genérico `Causa `. # Visão geral dos webhooks Source: https://docs.d-api.cloud/ura/webhooks/visao-geral Como o D-API notifica seu sistema sobre o ciclo de vida das ligações URA (voz). Os webhooks de URA notificam seu sistema sobre o **ciclo de vida de cada ligação**: quando a chamada **inicia**, é **atendida**, recebe um **dígito** (DTMF) e quando **encerra**. Eles permitem acompanhar a campanha de voz em tempo real e reagir às interações do destinatário. ## Webhook de conta (canal `voice`) A URA usa um **webhook de conta**, configurado **uma vez por conta** no painel, no canal `voice`. Todos os eventos de voz da conta — disparos em massa e ligações avulsas — são entregues a esse mesmo endpoint. > [!NOTE] > > No painel é possível restringir **quais eventos** o webhook recebe. Se nenhuma > restrição for definida, **todos** os eventos do canal `voice` são entregues. ## Envelope Cada webhook envia o conteúdo do evento dentro de `data`, junto de `channel` e `timestamp` no nível raiz. ```json theme={null} { "event": "call.started", "channel": "voice", "data": { "callId": "...", "bulkCallId": "...", "to": "+5511999999999", "answered": null, "talkSeconds": null, "digits": null, "cause": null, "causeDescription": null, "timestamp": "2026-01-24T23:00:00.000Z" }, "timestamp": "2026-01-24T23:00:00.000Z" } ``` **event** `string` *required* Nome do evento: `call.started`, `call.answered`, `call.dtmf` ou `call.ended`. Veja [Eventos](/ura/webhooks/eventos). **channel** `string` *required* Canal de origem. Sempre `"voice"`. **data** `object` *required* Detalhes da ligação. Os campos não aplicáveis ao evento vêm como `null`. Veja a página de [Eventos](/ura/webhooks/eventos) para cada campo. **timestamp** `string` *required* Momento do envio do webhook em ISO 8601 (UTC). ## Headers | Header | Valor | | - | - | | `Content-Type` | `application/json` | | `X-DAPI-Webhook-Channel` | `voice` | | `X-DAPI-Signature` | HMAC-SHA256 (hex) do corpo bruto, somente se houver secret | A `X-DAPI-Signature` só é enviada quando um **secret** está configurado. Ela é o HMAC-SHA256, em hexadecimal, do **corpo bruto** (raw body) da requisição. ### Validando a assinatura Calcule o HMAC sobre o corpo **bruto** recebido (não sobre o JSON re-serializado) e compare com o header usando comparação de tempo constante (timing-safe): ```javascript theme={null} const sig = crypto.createHmac("sha256", secret).update(rawBody).digest("hex"); // comparar (timing-safe) com o header X-DAPI-Signature ``` ## Entrega e confiabilidade Os webhooks de conta são entregues por uma **fila durável**, com **retentativas**, **circuit breaker** por URL e **logs** de entrega. Em caso de falha temporária, a entrega é repetida automaticamente. ## Como a chamada inicia As ligações são disparadas pela API; ambos os endpoints retornam o `callId` que você verá nos webhooks. > [accordion] POST /api/v1/voice/bulk — disparo em massa > > Dispara um **lote** de ligações. Informe `audioUrl` (áudio único) **ou** > `flowId` (fluxo IVR interativo) — exatamente um dos dois. Retorna o > identificador do lote (`bulkId`), que é o mesmo valor entregue como `callId` > nos webhooks. > [accordion] POST /api/v1/voice/call — ligação única > > Dispara **uma** ligação para um número. Também aceita `audioUrl` **ou** > `flowId`. Retorna `callId` — o identificador usado nos webhooks dessa > ligação. > [accordion] POST /api/v1/voice/live/start — ligação por stream > > Disca e entrega o áudio da ligação em tempo real por WebSocket. Retorna o > `callId` usado nos webhooks dessa ligação. Veja [Ligações por > Stream](/ura/ligacoes/stream). > [!NOTE] > > Para uma URA **interativa** (que captura dígitos via DTMF), dispare com um > `flowId`. Apenas fluxos IVR geram eventos `call.dtmf`. ## Próximos passos Veja a lista de eventos do ciclo de vida da chamada, os campos de cada um e a tabela completa de códigos de `cause` em [Eventos](/ura/webhooks/eventos). # Comandos assíncronos Source: https://docs.d-api.cloud/whatsapp/comandos-assincronos Envie comandos com async: true, receba o resultado pelo webhook command.result ou consulte pelo commandId. Por padrão, a API só responde depois que o WhatsApp executa o comando. Um envio de mídia pesada, por exemplo, segura o request até a mensagem sair. Com `async: true`, a API enfileira o comando, responde na hora com um `commandId` e executa em segundo plano. O resultado chega de duas formas, ambas com o mesmo payload: * **Webhook `command.result`**: a API avisa seu sistema quando o comando termina. É o canal de entrega garantida. * **Consulta pelo `commandId`**: `GET /api/v1/commands/{commandId}`, útil para depuração ou como complemento. O resultado expira depois de cerca de 1 hora. ## Fluxo **1. Envie o comando com async: true** ```json theme={null} POST /api/v1/messages/send/text { "sessionId": "minha-sessao", "to": "5511999999999", "text": "Olá!", "async": true } ``` **2. Guarde o commandId da resposta** A API responde `200` imediatamente, antes de executar o comando: ```json theme={null} { "commandId": "9f1c8f2e-4b7a-4f10-9c3d-2e1a8b5d7c40", "success": true, "status": "queued", "message": "Command queued", "timestamp": "2026-09-03T04:15:21.902Z", "sessionId": "minha-sessao", "to": "5511999999999", "messageType": "text" } ``` `success: true` aqui significa só que o comando **entrou na fila**. Ainda não diz se ele deu certo. **3. Receba o resultado no webhook** Quando o comando termina, com sucesso ou falha, a API envia **um** evento `command.result` com o mesmo `commandId`. ## Ativando o modo assíncrono Envie `async` no corpo (JSON) ou na query string, nas rotas `GET`. O campo aceita booleano (`true`) ou string (`"true"` ou `"1"`). Ausente ou `false`, o comando é síncrono como sempre. > [!NOTE] > > Sessões da **API Oficial** (`cloud_api`) ignoram o `async` e sempre respondem > de forma síncrona: o envio passa direto pela Meta, sem fila. ### Resposta do enfileiramento **commandId** `string` *required* UUID do comando. É a chave para correlacionar com o webhook e para consultar o status. **success** `boolean` *required* Sempre `true` nesta resposta: o comando foi aceito na fila. **status** `string` *required* Sempre `"queued"`. **message** `string` *required* Sempre `"Command queued"`. **timestamp** `string` *required* Momento do enfileiramento em ISO 8601 (UTC). As rotas de envio de mensagem também devolvem `sessionId`, `to` e `messageType`. Se a API não conseguir enfileirar, ela responde com erro e o comando **não** é executado. Nesse caso é seguro tentar de novo. ### Rotas compatíveis > [accordion] Mensagens > > | Rota | > | - | > | `POST /api/v1/messages/send/text` | > | `POST /api/v1/messages/send/image` | > | `POST /api/v1/messages/send/video` | > | `POST /api/v1/messages/send/audio` | > | `POST /api/v1/messages/send/document` | > | `POST /api/v1/messages/send/sticker` | > | `POST /api/v1/messages/send/location` | > | `POST /api/v1/messages/send/contact` | > | `POST /api/v1/messages/send/poll` | > | `POST /api/v1/messages/send/reaction` | > | `POST /api/v1/messages/send/album` | > [accordion] Grupos > > | Rota | > | - | > | `GET /api/v1/groups/list` | > | `GET /api/v1/groups/{groupId}/info` | > | `POST /api/v1/groups/create` | > | `POST /api/v1/groups/{groupId}/participants` | > | `POST /api/v1/groups/{groupId}/join` | > | `POST /api/v1/groups/{groupId}/leave` | > | `GET /api/v1/groups/{groupId}/invite` | > | `POST /api/v1/groups/{groupId}/invite/revoke` | > | `PUT /api/v1/groups/{groupId}/name` | > | `PUT /api/v1/groups/{groupId}/description` | > | `PUT /api/v1/groups/{groupId}/profile-picture` | > | `PUT /api/v1/groups/{groupId}/settings` | > | `POST /api/v1/groups/{groupId}/join-requests/approve` | > | `POST /api/v1/groups/{groupId}/join-requests/reject` | > [accordion] Contatos e chats > > | Rota | > | - | > | `GET /api/v1/contacts/` | > | `GET /api/v1/contacts/{phone}` | > | `GET /api/v1/contacts/{phone}/avatar` | > | `POST /api/v1/contacts/check` | > | `POST /api/v1/contacts/getuser` | > | `GET /api/v1/contacts/blocklist` | > | `POST /api/v1/contacts/blocklist` | > | `POST /api/v1/contacts/report` | > | `POST /api/v1/chats/presence` | > | `POST /api/v1/chats/read` | > | `DELETE /api/v1/chats/messages/{messageId}` | > [accordion] Etiquetas, catálogo, canais, histórico e mídia > > | Rota | > | - | > | `POST /api/v1/labels/sync` | > | `POST /api/v1/labels/upsert` | > | `POST /api/v1/labels/attach` | > | `POST /api/v1/catalog/list` | > | `POST /api/v1/catalog/collections/list` | > | `POST /api/v1/catalog/product/get` | > | `POST /api/v1/catalog/product/create` | > | `POST /api/v1/catalog/product/edit` | > | `POST /api/v1/catalog/product/delete` | > | `POST /api/v1/catalog/collection/create` | > | `POST /api/v1/catalog/collection/edit` | > | `POST /api/v1/catalog/collection/delete` | > | `GET /api/v1/newsletters/list` | > | `POST /api/v1/newsletters/create` | > | `POST /api/v1/history/full-sync` | > | `POST /api/v1/history/on-demand` | > | `POST /api/v1/media/download` | ## Webhook `command.result` ### Configuração O webhook de comandos é **de conta**: uma URL recebe o resultado de todos os comandos assíncronos de todas as sessões da conta. Ele é separado dos webhooks de eventos de cada sessão do WhatsApp. No painel, acesse **Integrações → Webhook de Comandos** e informe: * **URL**: endpoint `https://` que vai receber os eventos. * **Secret** (opcional, recomendado): ativa a assinatura `X-DAPI-Signature`. * **Ativo**: sem isso, nenhum evento é enviado. Também dá para configurar pela API: ```json theme={null} PUT /api/v1/account/webhooks/command { "url": "https://meu-sistema.com/webhooks/dapi-comandos", "secret": "um-segredo-forte", "events": ["command.result"], "enabled": true } ``` | Campo | Comportamento | | - | - | | `url` | URL de destino. `null` remove. | | `secret` | Omitido mantém o secret atual; `null` remove; string substitui. O valor nunca é devolvido. | | `events` | Lista de eventos aceitos. Vazia equivale a todos. O único evento do canal é `command.result`. | | `enabled` | Liga ou desliga a entrega. O padrão é `false`. | `GET /api/v1/account/webhooks` lista a configuração atual, com `hasSecret` no lugar do secret. > [!WARNING] > > Sem webhook de comandos configurado e ativo, o comando assíncrono executa > normalmente, mas o resultado **não é enviado** a lugar nenhum. Ele só fica > disponível na [consulta pelo commandId](#consulta-pelo-commandid), durante a > janela de retenção. ### Envelope ```json theme={null} { "event": "command.result", "channel": "command", "data": { "commandId": "9f1c8f2e-4b7a-4f10-9c3d-2e1a8b5d7c40", "sessionId": "minha-sessao", "commandType": "send_text", "success": true, "data": { "messageId": "3EB0C767D26B8CA3F7A1" }, "error": null, "timestamp": "2026-09-03T04:15:22.318Z" }, "timestamp": "2026-09-03T04:15:22.401Z" } ``` **event** `string` *required* Sempre `"command.result"`. **channel** `string` *required* Sempre `"command"`. **timestamp** `string` *required* Momento em que o webhook foi gerado, em ISO 8601 (UTC). **data** `object` *required* Resultado do comando. **campos** **commandId** `string` *required* O mesmo `commandId` devolvido no enfileiramento. **sessionId** `string` *required* Sessão em que o comando executou. **commandType** `string` *required* Tipo interno do comando (ex: `send_text`, `send_poll`). Use para rotear o tratamento quando o mesmo endpoint recebe vários tipos. **success** `boolean` *required* `true` se o comando executou com sucesso. É o campo que diz se deu certo. **data** `object | null` *required* Retorno do comando quando há sucesso, com o mesmo conteúdo que a rota devolveria no modo síncrono. Em envios de mensagem traz o `messageId`. `null` em caso de falha. **error** `string | null` *required* Motivo da falha quando `success` é `false`. `null` em caso de sucesso. **timestamp** `string` *required* Momento em que o comando terminou, em ISO 8601 (UTC). ### Exemplo de falha Um comando que executou e falhou, ou que estourou o tempo limite, também gera `command.result`, com `success: false`: ```json theme={null} { "event": "command.result", "channel": "command", "data": { "commandId": "1b7e4c90-2d3f-4a61-8e55-0c9f7a2b6d11", "sessionId": "minha-sessao", "commandType": "send_image", "success": false, "data": null, "error": "session not connected", "timestamp": "2026-09-03T04:16:05.120Z" }, "timestamp": "2026-09-03T04:16:05.198Z" } ``` > [!NOTE] > > O texto de `error` vem do WhatsApp ou da camada de execução e pode mudar. > Use `success` para decidir o fluxo e trate `error` como mensagem de log. ### Headers | Header | Valor | | - | - | | `Content-Type` | `application/json` | | `X-DAPI-Webhook-Channel` | `command` | | `X-DAPI-Signature` | HMAC-SHA256 (hex) do corpo bruto, enviado só se houver secret | ### Validando a assinatura Calcule o HMAC sobre o corpo **bruto** recebido, não sobre o JSON re-serializado, e compare com o header usando comparação de tempo constante: ```javascript theme={null} import crypto from "node:crypto"; function isValidSignature(rawBody, header, secret) { if (!header) return false; const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex"); const a = Buffer.from(expected, "hex"); const b = Buffer.from(header, "hex"); return a.length === b.length && crypto.timingSafeEqual(a, b); } ``` ## Garantias de execução e entrega > [accordion] Um resultado por comando > > Cada comando assíncrono gera exatamente um `command.result`: com > `success: true` se deu certo ou `success: false` se falhou ou estourou o > tempo limite. > [accordion] O comando nunca é reexecutado > > Se o comando falhar, a API **não tenta de novo**: muitos comandos, como > envio de mensagem, não podem ser repetidos sem risco de duplicar. Reenviar > fica a seu critério, depois de ler o `error`. > [accordion] A entrega do webhook tem retentativa > > O webhook sai por uma fila durável. Seu endpoint precisa responder `2xx` > em até 30 segundos. Fora disso, a entrega é repetida com backoff > exponencial (15 s, depois 30 s), em até 3 tentativas no total. > > * `404` ou `410` encerram as tentativas na hora: o endpoint é tratado como > inexistente. > * Um endpoint que falha repetidamente tem a entrega suspensa por um tempo > (circuit breaker), para não acumular tentativas inúteis. > [!WARNING] > > Por causa da retentativa, o mesmo `command.result` pode chegar mais de uma > vez. Isso acontece, por exemplo, se seu endpoint processar o evento mas > responder depois de 30 segundos. Trate o `commandId` como chave de > idempotência e ignore repetições. Boas práticas no endpoint: * Responda `200` assim que validar a assinatura e processe o evento depois, em fila própria. * Guarde o `commandId` no momento do envio, junto da entidade do seu sistema (pedido, conversa, notificação), para casar o resultado depois. * Não dependa da ordem de chegada dos webhooks. Comandos rodam em paralelo e podem terminar em ordem diferente da de envio. ## Consulta pelo commandId `GET /api/v1/commands/{commandId}` mostra o estado atual do comando, se ainda está na fila, executando ou já terminou, e traz o mesmo payload do webhook em `result`. Detalhes em [Consultar comando assíncrono](/api-reference/endpoints/consultar-comando). | Use | Quando | | - | - | | Webhook `command.result` | Integração em produção: entrega garantida, sem polling | | Consulta pelo `commandId` | Depuração, reconciliação pontual ou checagem logo após o envio | > [!NOTE] > > O resultado fica consultável por cerca de **1 hora** após a execução (24 > horas se o worker falhar). Depois disso a consulta responde `404`. ## Ordem de entrega (sequential) Comandos assíncronos rodam em paralelo. Dois envios seguidos para o mesmo contato podem chegar fora de ordem: uma imagem pesada pode sair depois do texto enviado logo em seguida. Para envios de mensagem, adicione `sequential: true` junto de `async: true`. Os envios para o mesmo destinatário saem um de cada vez, na ordem em que chegaram na API. Cada um continua gerando seu próprio `command.result`. Veja [Envio assíncrono em ordem](/api-reference/endpoints/envio-sequencial). ## Erros comuns | Sintoma | Causa provável | | - | - | | Recebo `status: "queued"`, mas nenhum webhook chega | Webhook de comandos não configurado, desativado, ou com `events` sem `command.result` | | O webhook chega com `success: false` | O comando executou e falhou (sessão desconectada, número inválido, tempo limite). Veja `error` | | `async: true` não teve efeito | Sessão da API Oficial (`cloud_api`), que é sempre síncrona | | A consulta pelo `commandId` responde `404` | O resultado expirou, o `commandId` não existe ou pertence a outra conta | | O mesmo `commandId` chegou duas vezes | Retentativa de entrega. Deduplique pelo `commandId` | # Assistente de Integração Source: https://docs.d-api.cloud/whatsapp/instalar-assistente Instale a extensão do Chrome e migre uma conexão do WhatsApp Web já ativa, sem escanear QR. O **Assistente de Integração** é uma extensão do Chrome que migra uma conexão do WhatsApp Web **já conectada** para a D-API usando um **código de uso único** — sem precisar escanear o QR code novamente. > [!NOTE] > > Requer o Google Chrome (ou navegador baseado em Chromium) com uma aba do > **web.whatsapp.com** já conectada à conta que você quer migrar. ## Instalação > [card] [Chrome Web Store](https://chromewebstore.google.com/detail/egjhdgcdbekophdhjnnoeeckjeiofnln/) > > Instale com um clique pela loja oficial (recomendado). > [card] [Download manual (.zip)](https://drive.google.com/uc?export=download\&id=1flaN8E8KPDg5W8GC3Aasx46NqoHz3qMw) > > Baixe o pacote e carregue como extensão desempacotada. > [accordion] Instalação manual (a partir do .zip) > > 1. Baixe e **descompacte** o arquivo `.zip`. > 2. Abra `chrome://extensions` no navegador. > 3. Ative o **Modo do desenvolvedor** (canto superior direito). > 4. Clique em **Carregar sem compactação** e selecione a pasta descompactada. > 5. O ícone do Assistente de Integração aparece na barra do Chrome. ## Como migrar uma conexão 1. **Gere o código** da instância de destino: * No painel, abra **Conectar dispositivo** — o código aparece abaixo do QR code; ou * Via API: [`POST /sessions/:sessionId/migration-otp`](/api-reference/endpoints/gerar-otp). 2. Abra uma aba do **web.whatsapp.com** já conectada com a conta a ser migrada. 3. Clique no ícone do **Assistente de Integração** e confira o número detectado na aba. 4. Informe o **código de 8 caracteres** e clique em **Integrar**. 5. Ao concluir, o WhatsApp Web deste navegador é **desconectado** e a conexão passa a operar na D-API. > [!WARNING] > > O código é de **uso único** e expira em **30 minutos**. Ao migrar, a sessão do > WhatsApp Web neste navegador é encerrada — a conexão continua ativa no servidor. > Nunca compartilhe o código: quem o tiver pode vincular uma conta à sua instância. # WhatsApp (não oficial) Source: https://docs.d-api.cloud/whatsapp/introducao Conexão via QR code ou pareamento, organizada por sessão. O produto **WhatsApp não oficial** conecta um número de WhatsApp à D-API por **QR code** ou **código de pareamento**. Cada conexão é uma **sessão**, identificada por `sessionId`, presente em todos os webhooks. > [card] [Webhooks](/whatsapp/webhooks/visao-geral) > > Como configurar e receber os eventos da sua sessão. # Canais de Voz Source: https://docs.d-api.cloud/whatsapp/ligacoes/canais Quantas ligações de WhatsApp a conexão faz ou recebe ao mesmo tempo, como contratar canais extras e o que muda com mais de um canal. Um **canal de voz** é uma ligação de WhatsApp em andamento. Ele é a unidade de simultaneidade da conexão: com 3 canais, a conexão pode ter até 3 ligações ao mesmo tempo, somando as de saída e as recebidas. > [!NOTE] > > Toda conexão WhatsApp não oficial vem com **1 canal incluso**. > Conexões da API Oficial (`cloud_api`) não fazem ligações por esta API. ## Limites e preço | | | | - | - | | Incluso por conexão | 1 canal | | Extras | contratados um a um, até **4** | | Máximo por conexão | **5 canais** | | Preço | **R\$ 10,00/mês por canal extra** | | Plano | contratar extras exige o plano **Scale** | Os canais são **por conexão**: cada número tem os seus. Na fatura, os extras de todas as conexões da conta aparecem somados numa linha. ## Consultar os canais da conexão ```bash theme={null} curl https://api.d-api.cloud/api/v1/sessions/SUA_SESSAO/voice-channels \ -H "Authorization: SUA_API_KEY" ``` ```json theme={null} { "success": true, "data": { "sessionId": "SUA_SESSAO", "connectionType": "unofficial", "voiceChannels": 1, "maxPerSession": 5, "unitPriceBrl": 10, "billingProvider": "stripe", "scaleRequired": false } } ``` **voiceChannels** `integer` Canais da conexão hoje (inclui o canal incluso). **maxPerSession** `integer` Máximo de canais por conexão. **unitPriceBrl** `number` Preço mensal de cada canal extra, em reais. **billingProvider** `string | null` Como a conta paga: `stripe` (cartão) ou `internal_pix` (fatura Pix). `null` quando não há assinatura Scale. **scaleRequired** `boolean` `true` quando a conta não está no plano Scale e, por isso, não pode contratar canais extras. ## Alterar a quantidade de canais `PUT /sessions/{sessionId}/voice-channels` define o **total** de canais da conexão. Envie o número final desejado, não o incremento: para ir de 1 para 3 canais, envie `3`. Repetir a mesma chamada não cobra de novo nem reinicia a conexão. ```bash theme={null} curl -X PUT https://api.d-api.cloud/api/v1/sessions/SUA_SESSAO/voice-channels \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "voiceChannels": 3 }' ``` ```json theme={null} { "success": true, "sessionId": "SUA_SESSAO", "voiceChannels": 3, "billedExtras": 2, "updatedAt": "2026-11-04T12:00:00.000Z" } ``` **voiceChannels** `integer` *required* Total de canais da conexão, de `1` a `5`. **billedExtras** `integer` Canais extras cobrados nesta conexão depois da troca. ### Cobrança **1. Aumento** No **cartão**, o valor proporcional até o fim do ciclo é cobrado na hora. Se o cartão for recusado, a troca é desfeita e a API responde `402`. Na **fatura Pix**, o proporcional entra na próxima fatura. **2. Redução** Vale na hora e **não gera crédito** do período já pago. **3. Aplicação** A conexão **reinicia** para aplicar a nova quantidade. Ligações em andamento nessa conexão caem; mensagens não são perdidas. ### Erros | Status | `code` | Quando | | - | - | - | | `400` | — | Conexão da API Oficial (`cloud_api`) ou `voiceChannels` fora de 1–5 | | `402` | `VOICE_CHANNEL_PAYMENT_DECLINED` | Cartão recusado no aumento; nada mudou | | `404` | — | Conexão não encontrada | | `409` | `SCALE_REQUIRED` | Aumento numa conta fora do plano Scale | ## Ligações com mais de um canal Com mais de um canal, cada ligação é independente e identificada pelo seu `callId`. * **Novas ligações** (`POST /calls/place`, `POST /calls/stream`) e **atender** uma recebida (`POST /calls/accept`) ocupam um canal. Com todos ocupados, a API recusa com o erro `a call is already in progress` — trate como "ocupado" e tente de novo quando uma ligação terminar. * **Ofertas recebidas** só ocupam canal quando você atende. Uma oferta tocando não bloqueia novas ligações. * **Encerrar, silenciar e consultar estado** (`POST /calls/end`, `POST /calls/mute`, `POST /calls/state`) passam a exigir o `callId` quando houver mais de uma ligação ativa. Sem ele, a API responde `callId is required: N calls active` em vez de agir na ligação errada. Com uma ligação só, o `callId` continua opcional. * **Áudio em tempo real**: cada ligação tem o seu próprio WebSocket de mídia (`wsUrl`), exatamente como em [Ligações por Stream](/whatsapp/ligacoes/stream). Fechar o WebSocket encerra só aquela ligação. * **Webhooks** `call.*` não mudam: cada evento já traz o `callId` da ligação a que pertence. Use-o para separar as conversas. > [!TIP] > > Guarde o `callId` devolvido por `place`, `stream` ou `accept` junto do seu > atendimento. É ele que endereça a ligação certa quando várias estão ativas. # Receber Ligações Source: https://docs.d-api.cloud/whatsapp/ligacoes/receber Assine as chamadas de WhatsApp recebidas em tempo real, atenda pelo gateway e fale pelo WebSocket de mídia. As **chamadas recebidas** permitem que o seu aplicativo saiba, no instante em que o telefone toca, que alguém está ligando para o número da sessão — e que atenda ou recuse essa chamada pela API. Quando você atende, a D-API devolve um **WebSocket de mídia** idêntico ao das [Ligações por Stream](/whatsapp/ligacoes/stream): o áudio trafega nos dois sentidos pelo mesmo canal. > [!NOTE] > > Você precisa de uma **conexão WhatsApp não oficial já conectada** e > de uma **API Key**. Gere a sua chave no [painel](https://app.d-api.cloud). ## Como funciona **1. Ative o recebimento na conexão** `POST /sessions/{sessionId}/receive-calls-settings` liga a capacidade. A conexão reinicia. **2. Assine os eventos** Abra o WebSocket `/voip/events` e fique escutando. A oferta (`call.offer`) chega por ali. **3. Atenda ou recuse** `POST /calls/accept` devolve a `wsUrl` da mídia. `POST /calls/reject` encerra a oferta. **4. Troque áudio** Abra a `wsUrl` e siga exatamente o fluxo da página de [Ligações por Stream](/whatsapp/ligacoes/stream). O canal de **eventos** e o canal de **mídia** são WebSockets diferentes. O de eventos é único, de longa duração e cobre várias sessões; o de mídia é por chamada e nasce a cada `accept`. ## Passo 1 — Ative o recebimento na conexão O recebimento vem **desligado por padrão**. Enquanto estiver desligado, a conexão não engaja chamadas entrantes: você continua recebendo o webhook [`call.offer`](/whatsapp/webhooks/chamadas), mas a mídia não sobe e a chamada não é atendível pelo gateway. > [!WARNING] > > **Chamadas recebidas exigem uma conexão não-oficial.** A API Oficial (Cloud > API) não expõe API de chamadas e não tem o pod de bridge que fala o protocolo > de chamada do WhatsApp: `receive-calls-settings` responde `400` para conexões > desse tipo, assim como `/calls/accept` e `/calls/reject`. ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/sessions/minha-sessao/receive-calls-settings \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "receiveCalls": true }' ``` ```json theme={null} { "message": "Receive calls setting updated successfully", "sessionId": "minha-sessao", "receiveCalls": true, "updatedAt": "2026-05-26T12:00:00.000Z" } ``` > [!WARNING] > > **Esta chamada reinicia a conexão.** O valor é gravado no banco e aplicado como > variável de ambiente no pod da sessão, o que dispara um restart. Durante o > reinício a sessão fica indisponível por alguns segundos: mensagens não são > enviadas nem recebidas nesse intervalo. Faça a mudança em janela controlada, > não a cada chamada. > [!NOTE] > > Se a atualização da variável de ambiente falhar, o valor continua persistido e > passa a valer na **próxima subida** do pod. A resposta ainda é de sucesso > nesse caso. Para desligar, envie `{ "receiveCalls": false }`. A conexão reinicia de novo. ## Com o SDK Node Com o recebimento ativo (Passo 1), o [`d-api-sdk`](https://www.npmjs.com/package/d-api-sdk) assina os eventos, reconecta sozinho e entrega cada chamada já com `answer()` e `reject()`. A chamada atendida é a mesma das [Ligações por Stream](/whatsapp/ligacoes/stream), inclusive com `{ transport: "webrtc" }` ([recomendado](/whatsapp/ligacoes/webrtc)). ```js theme={null} const incoming = await dapi.calls.listen({ sessionIds: ["minha-sessao"] }); incoming.on("call", async (offer) => { console.log("tocando:", offer.from); const call = await offer.answer({ transport: "webrtc" }); // ou: await offer.reject() call.on("audio", (frame) => bot.hear(frame)); bot.on("speech", (pcm) => call.sendAudio(pcm)); }); incoming.on("withdrawn", (e) => console.log("parou de tocar:", e.callId, e.type)); ``` Uma oferta que tocou com o socket desconectado não é reentregue (ela já estaria vencida). ## Passo 2 — Assine os eventos em tempo real Abra um WebSocket em `/voip/events`. A autenticação vai na query string, porque o navegador não define cabeçalhos em WebSocket. ``` wss://api.d-api.cloud/voip/events?token=SUA_API_KEY&sessions=sessao-1,sessao-2 ``` **token** `string` *required* Sua API Key. Aceita chave de usuário ou chave com escopo de sessão — nesse caso, só as sessões dela passam. **sessions** `string` *required* Lista de `sessionId` separados por vírgula. Valores repetidos e vazios são descartados. **Máximo de 20 sessões por conexão.** > [!WARNING] > > A URL embute a sua API Key. Abra o socket **pelo seu backend**, ou entregue ao > navegador uma URL gerada sob demanda com uma **chave de escopo de sessão**. > Não registre essa URL em log. A autorização é **tudo ou nada**: cada sessão da lista é verificada individualmente (chave válida *e* sessão pertencente ao dono da chave). Se uma falhar, a conexão inteira é recusada com `unauthorized`. Um cliente que recebesse um subconjunto silenciosamente acharia que está ouvindo sessões que nunca assinou. Assim que a assinatura é aceita, o servidor envia o primeiro frame: ```json theme={null} { "type": "subscribed", "sessions": ["sessao-1", "sessao-2"] } ``` Se a assinatura for recusada, chega um frame de erro e o socket fecha com o código `1008`: ```json theme={null} { "type": "error", "code": "unauthorized", "msg": "Invalid API key or session not owned" } ``` | `code` | Quando acontece | | - | - | | `unavailable` | Os eventos em tempo real estão indisponíveis no momento | | `bad_request` | Nenhuma sessão informada em `sessions` | | `too_many_sessions` | Mais de 20 sessões em uma conexão | | `unauthorized` | Chave inválida ou sessão que não é sua | ### Sem replay de histórico > [!NOTE] > > O socket entrega **apenas os eventos que chegarem com ele já conectado**. Não > há reentrega de backlog, e isso é intencional: uma oferta de chamada vale > poucos segundos e não é atendível depois disso. Reentregar o histórico faria o > seu app anunciar uma ligação que já acabou — junto com o `call.rejected` dela. A consequência prática: quem reconectar no meio de uma oferta **perde aquela oferta**. Mantenha o socket aberto de forma contínua, com reconexão automática, e trate a queda como perda de chamadas naquele intervalo. Para trilha histórica completa, use os [webhooks de chamadas](/whatsapp/webhooks/chamadas) — eles continuam sendo entregues em paralelo. ### Formato dos frames Todos os frames são **texto JSON**. Este canal é somente leitura: atender e recusar são chamadas HTTP, e o áudio vive no outro WebSocket. ```json theme={null} { "type": "call.offer", "callId": "ABCD1234", "from": "5511999999999@s.whatsapp.net", "callCreator": "201234567890123@lid", "timestamp": 1716724496789, "sessionId": "minha-sessao" } ``` **type** `string` *required* Um de `call.offer`, `call.accepted`, `call.rejected` ou `call.ended`. Veja a tabela abaixo. **callId** `string` *required* Identificador da chamada. É o que você envia em `/calls/accept` e `/calls/reject`. **from** `string` JID de quem está ligando, já resolvido para o número de telefone quando possível. Opcional. **callCreator** `string` JID original informado pelo bridge. Pode vir como `@lid`. Opcional. **timestamp** `number` *required* Momento do evento em milissegundos (epoch). Quando o bridge não carimba o evento, vale o horário de chegada no servidor. **sessionId** `string` *required* Conexão que recebeu a chamada. Acrescentado pelo servidor, porque um socket cobre várias sessões e o `accept` exige o `sessionId`. ### Eventos que chegam neste canal | Evento | Quando chega | O que fazer | | - | - | - | | `call.offer` | Chamada entrando, tocando | Mostrar a chamada e decidir entre `/calls/accept` e `/calls/reject` | | `call.accepted` | Atendida **fora da sua integração** | Parar de tocar: a chamada não é sua | | `call.rejected` | Recusada **fora da sua integração** | Parar de tocar | | `call.ended` | Encerrada, em qualquer cenário | Parar de tocar e limpar o estado | > [!WARNING] > > **`call.accepted` não confirma o seu atendimento.** Ele avisa que a chamada > saiu do estado de toque **sem passar por aqui**: foi atendida no próprio > aparelho ou em outro dispositivo conectado à mesma conta. O mesmo vale para > `call.rejected`. > > A confirmação de que **você** atendeu é a resposta HTTP de `/calls/accept`, > com a `wsUrl` da mídia. Tratar `call.accepted` como sucesso próprio faz a sua > aplicação assumir chamadas que foram atendidas no celular. Os três eventos terminais têm o mesmo formato do `call.offer`, só mudando o `type`: ```json theme={null} { "type": "call.ended", "callId": "ABCD1234", "from": "5511999999999@s.whatsapp.net", "callCreator": "201234567890123@lid", "timestamp": 1716724500123, "sessionId": "minha-sessao" } ``` > [!NOTE] > > Qualquer um dos três terminais encerra o ciclo daquela chamada. Trate os três > como "pare de tocar" — não espere sempre pelo `call.ended`, porque uma chamada > atendida no aparelho pode fechar com `call.accepted` e só depois, ou nunca, > gerar o `call.ended`. ## Passo 3 — Atenda a chamada `POST /calls/accept` com o `sessionId` e o `callId` que vieram no `call.offer`. ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/calls/accept \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sessionId": "minha-sessao", "callId": "ABCD1234" }' ``` ```json theme={null} { "success": true, "sessionId": "minha-sessao", "callId": "ABCD1234", "wsUrl": "wss://api.d-api.cloud/voip/stream?callId=ABCD1234&token=...", "token": "..." } ``` **callId** `string` Identificador da chamada **confirmado pelo bridge**. Pode diferir do que você enviou — use sempre o valor da resposta daqui em diante. **wsUrl** `string` URL do WebSocket de mídia, com `callId` e `token` já embutidos. Abra-a exatamente como veio. **token** `string` Token de acesso **exclusivo desta chamada**, gerado a cada chamada. Já está dentro da `wsUrl`. Ele **não** é a sua API Key: só abre o WebSocket desta chamada e deixa de valer quando ela termina. A resposta tem o **mesmo formato** de `POST /calls/stream`. A partir daqui o áudio, os eventos de ciclo de vida, o mute, o desligar e a gravação funcionam exatamente como descrito em [Ligações por Stream](/whatsapp/ligacoes/stream) — PCM `s16le`, 16 kHz, mono, frames de 320 amostras. Essa documentação não é repetida aqui. Para referência rápida, o socket de **mídia** envia estes eventos de controle, que são outros, diferentes dos do canal de eventos acima: | Evento | Quando chega | O que fazer | | - | - | - | | `recording` | Gravação disponível | Guardar `url` / `files` | | `ended` | Chamada encerrada, com `reason` | Encerrar e limpar | | `error` | Falha, com `code` e `msg` | Mostrar o erro e limpar | > [!NOTE] > > Não confunda os dois canais. `call.ended` chega no canal de **eventos** e > avisa que a chamada acabou. `ended` chega no canal de **mídia** e encerra > aquele streaming. Numa chamada atendida por você, os dois acontecem. > [!WARNING] > > A `wsUrl` embute a sua API Key no parâmetro `token`. Chame `/calls/accept` pelo > seu backend e entregue ao navegador apenas a `wsUrl`. Erros possíveis: **404 Not Found** Sessão inexistente ou fora do seu escopo. **400 Bad Request** Conexão da API Oficial (Cloud API), ou o bridge recusou o atendimento — a oferta pode já ter expirado ou sido atendida em outro lugar. Nada é registrado nesse caso: você não recebe uma `wsUrl` que nunca entregaria áudio. **503 Service Unavailable** O stream de voz está indisponível no momento. ## Passo 4 — Recuse a chamada `POST /calls/reject` precisa de três campos. Além do `sessionId` e do `callId`, vai o **`from`**: o JID de quem ligou, exatamente como veio no `call.offer`. ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/calls/reject \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sessionId": "minha-sessao", "callId": "ABCD1234", "from": "5511999999999@s.whatsapp.net" }' ``` ```json theme={null} { "success": true, "sessionId": "minha-sessao" } ``` > [!NOTE] > > Repasse o `from` **sem transformar**. O WhatsApp rejeita contra aquele JID, não > contra um número normalizado — se o evento trouxe um `@lid`, envie o `@lid`. O `call.rejected` correspondente é **assíncrono**: ele chega depois, pelo socket de eventos e pelo webhook. A resposta `200` significa que o comando foi aceito pelo bridge, não que a outra ponta já parou de tocar. ## Exemplo completo Um cliente Node que assina os eventos, atende a primeira oferta e conecta no WebSocket de mídia. A API Key nunca sai do servidor. ```js theme={null} // Node.js 18+ — npm i ws import WebSocket from "ws"; const HOST = "api.d-api.cloud"; const API_KEY = process.env.DAPI_API_KEY; const SESSIONS = ["minha-sessao"]; const api = (path, body) => fetch(`https://${HOST}/api/v1${path}`, { method: "POST", headers: { "Content-Type": "application/json", Authorization: API_KEY }, body: JSON.stringify(body), }).then((r) => r.json()); function assinarEventos() { const url = `wss://${HOST}/voip/events?token=${encodeURIComponent(API_KEY)}&sessions=${SESSIONS.join(",")}`; const ws = new WebSocket(url); ws.on("message", async (raw) => { const ev = JSON.parse(raw.toString()); if (ev.type === "error") { console.error("assinatura recusada:", ev.code, ev.msg); return; } if (ev.type === "subscribed") { console.log("assinado:", ev.sessions); return; } // Terminais: a chamada saiu do toque. `accepted` e `rejected` significam // que ela foi tratada FORA daqui, no próprio aparelho — não que você // atendeu. Sem parar de tocar nos três, a interface fica tocando à toa. if (["call.accepted", "call.rejected", "call.ended"].includes(ev.type)) { pararDeTocar(ev.callId, ev.type); return; } if (ev.type !== "call.offer") { console.log("evento:", ev.type, ev.callId); return; } console.log(`chamada de ${ev.from} na sessão ${ev.sessionId}`); tocando.add(ev.callId); await atender(ev.sessionId, ev.callId); }); // Sem replay: uma queda perde as ofertas do intervalo. Reconecte rápido. ws.on("close", () => setTimeout(assinarEventos, 1000)); ws.on("error", (err) => console.error("events ws:", err.message)); } const tocando = new Set(); function pararDeTocar(callId, motivo) { if (tocando.delete(callId)) console.log("chamada encerrada:", callId, motivo); } async function atender(sessionId, callId) { const res = await api("/calls/accept", { sessionId, callId }); if (!res.success) { console.error("falha ao atender:", res.error); tocando.delete(callId); return; } conectarMidia(res.wsUrl); } // Daqui em diante é o mesmo fluxo da página de Ligações por Stream: // frames binários = PCM s16le 16 kHz mono; frames de texto = ciclo de vida. function conectarMidia(wsUrl) { const media = new WebSocket(wsUrl); let podeEnviarAudio = false; media.on("message", (data, isBinary) => { if (isBinary) { reproduzir(data); // áudio de quem ligou return; } const msg = JSON.parse(data.toString()); if (msg.type === "accepted" || msg.type === "connected") podeEnviarAudio = true; if (msg.type === "ended" || msg.type === "error") media.close(); console.log("mídia:", msg.type); }); // Envie o microfone em frames de 640 bytes (320 amostras = 20 ms), // em cadência de tempo real, só depois de `accepted`. onFrameDoMicrofone((pcm) => { if (podeEnviarAudio && media.readyState === WebSocket.OPEN) media.send(pcm); }); media.on("close", () => console.log("chamada encerrada")); } assinarEventos(); ``` Para recusar em vez de atender, troque a chamada a `atender` por: ```js theme={null} await api("/calls/reject", { sessionId: ev.sessionId, callId: ev.callId, from: ev.from }); ``` ## Próximos passos > [card] [Ligações por Stream](/whatsapp/ligacoes/stream) > > O WebSocket de mídia em detalhe: formato de áudio, ciclo de vida e gravação. > [card] [Webhooks de chamadas](/whatsapp/webhooks/chamadas) > > A trilha server-to-server dos mesmos eventos, com histórico. # Ligações por Stream Source: https://docs.d-api.cloud/whatsapp/ligacoes/stream Faça e receba o áudio de chamadas de voz do WhatsApp em tempo real no seu app, por WebSocket. As **Ligações por Stream** deixam o seu aplicativo transmitir o áudio de uma chamada de voz do WhatsApp em tempo real: você inicia a ligação por uma chamada HTTP, abre um **WebSocket** e troca áudio nos dois sentidos — microfone do seu usuário para o outro lado, e a voz do outro lado para o alto-falante. > [!NOTE] > > Você precisa de uma **conexão WhatsApp não oficial já conectada** e > de uma **API Key**. Gere a sua chave no [painel](https://app.d-api.cloud). ## Como funciona O fluxo é sempre **de saída** (você liga para um número) e roda no **navegador**, onde estão o microfone e o alto-falante: **1. Inicie a chamada** `POST /calls/stream` retorna um `callId` e uma `wsUrl` pronta para abrir. **2. Abra o WebSocket** A `wsUrl` já carrega a autenticação. Frames de **texto** são eventos do ciclo de vida; frames **binários** são áudio. **3. Troque áudio** Envie o microfone como PCM binário e reproduza o áudio binário recebido. **4. Finalize** Feche o WebSocket para desligar. A gravação fica disponível ao final. Por baixo, o áudio trafega entre o navegador e o bridge do WhatsApp; a D-API é um cano bidirecional. Chamadas **recebidas** não entram por aqui — elas chegam pelo webhook [`call.offer`](/whatsapp/webhooks/chamadas). ## Com o SDK Node O [`d-api-sdk`](https://www.npmjs.com/package/d-api-sdk) faz os passos abaixo por você: inicia a chamada, abre o WebSocket, entrega o áudio em frames de 20 ms e reconecta se a rede cair. Os passos seguintes descrevem o protocolo, para quem integra em outra linguagem ou direto no navegador. ```js theme={null} import { DApi } from "d-api-sdk"; const dapi = new DApi({ apiKey: process.env.DAPI_API_KEY }); const call = await dapi.calls.start({ sessionId: "minha-sessao", phone: "5511999999999" }); call.on("event", (e) => console.log(e.type)); // calling, ringing, accepted... call.on("audio", (frame) => speaker.write(frame)); // Int16Array, 16 kHz, mono, 20 ms mic.on("data", (chunk) => call.sendAudio(chunk)); // Int16Array ou bytes s16le, ritmo real call.on("ended", (e) => console.log("fim", e.reason)); call.mute(true); call.hangup(); ``` > [!TIP] > > **Recomendado: [WebRTC](/whatsapp/ligacoes/webrtc).** O mesmo código com > `{ transport: "webrtc" }`: o áudio vai por UDP com Opus e FEC, aguenta melhor > rede ruim e volta sozinho para o WebSocket se a rede bloquear. ## Passo 1 — Inicie a chamada Chame `POST /calls/stream` com a sessão e o número de destino (com DDI, apenas dígitos). ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/calls/stream \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sessionId": "minha-sessao", "phone": "5551999998888" }' ``` A resposta traz o identificador da chamada e a URL do stream: ```json theme={null} { "success": true, "sessionId": "minha-sessao", "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "wsUrl": "wss://api.d-api.cloud/voip/stream?callId=a1b2c3d4-...&token=...", "token": "..." } ``` **callId** `string` Identificador da chamada. Use-o para consultar a gravação depois. **wsUrl** `string` URL **opaca** do WebSocket, com `callId` e `token` já embutidos. Abra-a exatamente como veio — **não** monte a URL você mesmo. **token** `string` Token de acesso **exclusivo desta chamada**, gerado a cada chamada. Já está dentro da `wsUrl`. Ele **não** é a sua API Key: só abre o WebSocket desta chamada e deixa de valer quando ela termina. > [!WARNING] > > A sua **API Key nunca deve ir ao navegador**. Inicie a chamada **pelo seu > backend** e entregue ao navegador apenas a `wsUrl` — ela carrega só o token da > chamada. Mesmo assim, trate a `wsUrl` como um segredo de curta duração (não > registre em logs) enquanto a chamada está ativa. Um exemplo de início pelo backend, que mantém a chave fora do navegador: ```js theme={null} // backend do seu app — Node.js app.post("/api/iniciar-chamada", async (req, res) => { const r = await fetch("https://api.d-api.cloud/api/v1/calls/stream", { method: "POST", headers: { "Content-Type": "application/json", Authorization: process.env.DAPI_API_KEY, // fica só no servidor }, body: JSON.stringify({ sessionId: req.body.sessionId, phone: req.body.phone }), }); const data = await r.json(); res.json({ callId: data.callId, wsUrl: data.wsUrl }); // só isso vai ao navegador }); ``` ## Passo 2 — Conecte ao WebSocket Abra a `wsUrl` e configure `binaryType` para receber áudio como `ArrayBuffer`. ```js theme={null} const ws = new WebSocket(wsUrl); ws.binaryType = "arraybuffer"; ws.onmessage = (e) => { if (typeof e.data === "string") { handleEvent(JSON.parse(e.data)); // evento do ciclo de vida (Passo 4) } else { playDownlink(e.data); // áudio binário do outro lado (Passo 3) } }; ``` Não há handshake pós-conexão: a autenticação está na URL. Se o servidor recusar, ele envia um evento `error` e fecha a conexão. ## Passo 3 — Capture e reproduza o áudio O áudio na rede é **PCM cru** (`s16le`, **16 kHz**, **mono**), em frames de **20 ms \= 320 amostras = 640 bytes**. A forma mais simples de acertar o formato é rodar o `AudioContext` a **16 kHz** — o navegador reamostra o microfone para você — e converter Float32 ⇄ Int16 dentro de um `AudioWorklet`. > [!TIP] > > Rode o `AudioContext` a `sampleRate: 16000`. Assim você evita reamostrar o > microfone na mão, e cada frame do worklet já sai no formato exato do stream. Crie o worklet `voip-worklet.js` (implementação de referência, adaptada da extensão oficial da D-API): ```js theme={null} // voip-worklet.js — converte Float32 (navegador) ⇄ Int16 (rede) e amortece jitter const FRAME = 320; // 20 ms @ 16 kHz const PREBUFFER = 1600; // ~100 ms de buffer para o áudio recebido class VoipIO extends AudioWorkletProcessor { constructor() { super(); this.ring = new Float32Array(16000 * 2); // ~2 s de buffer de recepção this.wr = 0; this.rd = 0; this.filled = 0; this.primed = false; this.outAccum = new Float32Array(FRAME); this.outLen = 0; // Áudio recebido (Int16 -> Float32) entra no ring buffer. this.port.onmessage = (e) => { if (e.data?.kind !== "in") return; const i16 = new Int16Array(e.data.pcm); for (let i = 0; i < i16.length; i++) { this.ring[this.wr] = i16[i] / 32768; this.wr = (this.wr + 1) % this.ring.length; this.filled = Math.min(this.filled + 1, this.ring.length); } }; } process(inputs, outputs) { // Uplink: microfone -> frames Int16 de 320 amostras. const mic = inputs[0]?.[0]; if (mic) { for (let i = 0; i < mic.length; i++) { this.outAccum[this.outLen++] = mic[i]; if (this.outLen === FRAME) { const i16 = new Int16Array(FRAME); for (let k = 0; k < FRAME; k++) { let v = this.outAccum[k]; v = v > 1 ? 1 : v < -1 ? -1 : v; i16[k] = v * 32767; } this.port.postMessage({ kind: "out", pcm: i16.buffer }, [i16.buffer]); this.outLen = 0; } } } // Downlink: ring buffer -> alto-falante, com pré-buffer e silêncio se faltar. const out = outputs[0][0]; if (!this.primed && this.filled >= PREBUFFER) this.primed = true; for (let i = 0; i < out.length; i++) { if (this.primed && this.filled > 0) { out[i] = this.ring[this.rd]; this.rd = (this.rd + 1) % this.ring.length; this.filled--; } else { out[i] = 0; if (this.primed && this.filled === 0) this.primed = false; // re-buffer } } return true; } } registerProcessor("voip-io", VoipIO); ``` Ligue o microfone, o worklet e o WebSocket: ```js theme={null} const ctx = new AudioContext({ sampleRate: 16000 }); await ctx.audioWorklet.addModule("/voip-worklet.js"); const mic = await navigator.mediaDevices.getUserMedia({ audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true, autoGainControl: true, }, }); const node = new AudioWorkletNode(ctx, "voip-io", { numberOfInputs: 1, numberOfOutputs: 1, outputChannelCount: [1], }); ctx.createMediaStreamSource(mic).connect(node); node.connect(ctx.destination); // voz do outro lado -> alto-falante let canSendUplink = false; // liberado só quando o outro lado atende (Passo 4) // Uplink: frames do worklet -> WebSocket node.port.onmessage = (ev) => { if (ev.data?.kind === "out" && canSendUplink && ws.readyState === WebSocket.OPEN) { ws.send(ev.data.pcm); } }; // Downlink: áudio binário do WebSocket -> worklet function playDownlink(buffer) { node.port.postMessage({ kind: "in", pcm: buffer }, [buffer]); } ``` > [!WARNING] > > **Não envie áudio do microfone antes do evento `accepted`.** Antes disso o outro > lado ainda não está pronto. O flag `canSendUplink` acima cuida disso. ## Passo 4 — Acompanhe o ciclo de vida Os frames de **texto** do WebSocket são eventos JSON no formato `{ "type": ... }`. | `type` | Significado | O que fazer | | - | - | - | | `calling` | Discagem iniciada | Mostrar "chamando" | | `ringing` | Telefone do destino tocando | Mostrar "tocando" | | `accepted` | **Destino atendeu, áudio ao vivo** | Liberar o uplink (`canSendUplink = true`) | | `connected` | Alias de `accepted` | Igual a `accepted` | | `recording` | Gravação disponível | Guardar `url` / `files` | | `ended` | Chamada encerrada (com `reason`) | Encerrar e limpar | | `error` | Falha (com `code` / `msg`) | Mostrar erro e limpar | ```js theme={null} function handleEvent(msg) { switch (msg.type) { case "calling": case "ringing": setStatus("tocando"); break; case "accepted": case "connected": canSendUplink = true; // agora pode enviar o microfone setStatus("conectado"); break; case "recording": saveRecording(msg.url, msg.files); break; case "ended": setStatus(`encerrada: ${msg.reason}`); cleanup(); break; case "error": setStatus(`erro: ${msg.msg || msg.code}`); cleanup(); break; } } ``` O evento `ended` traz um `reason`: `hangup`, `rejected`, `timeout`, `accepted_elsewhere`, `terminate` (duração máxima atingida), `ws_closed`, entre outros. Se o WebSocket fechar sem um `ended`, trate como encerramento. ## Passo 5 — Controle a chamada > [accordion] Mutar / desmutar > > Basta parar de enviar o microfone. O jeito mais simples é desabilitar a faixa > de áudio: > > ```js theme={null} > function setMuted(muted) { > mic.getAudioTracks().forEach((t) => (t.enabled = !muted)); > } > ``` > > Como alternativa, o servidor também aceita um controle por texto: > `ws.send(JSON.stringify({ type: "mute", muted: true }))`. > [accordion] Desligar > > **Fechar o WebSocket já desliga a chamada** — o servidor interpreta o > fechamento como um `hangup`. > > ```js theme={null} > function hangup() { > ws.close(); // ou: ws.send(JSON.stringify({ type: "hangup" })) > } > ``` > [accordion] Encerrar e liberar recursos > > Ao terminar, pare o microfone e feche o `AudioContext`: > > ```js theme={null} > function cleanup() { > mic.getTracks().forEach((t) => t.stop()); > ctx.close(); > } > ``` ## Reconexão (opcional) Por padrão, se o WebSocket cair, o servidor desliga a chamada. Para manter a ligação durante uma queda de rede ou a troca de servidor em um deploy, adicione `&resume=1` à `wsUrl`. Com ele: * Uma queda do socket **não desliga**: a chamada continua ativa e fica aguardando você reconectar por até **20 segundos**. * Reconecte com **a mesma `wsUrl`**. O servidor retoma a chamada e reenvia os eventos desde o início (`calling`, `ringing`, `accepted`...). Ignore os que você já tratou. * O servidor pode fechar a conexão com o código **`1012`** (reinício do serviço) para você reconectar. Trate como queda. * Para **desligar**, feche com o código `1000` — `ws.close(1000)` — ou envie `{ "type": "hangup" }`. Qualquer outro fechamento é tratado como queda. * Se ninguém reconectar em 20 segundos, a chamada é desligada. A gravação cobre a ligação inteira, com silêncio no intervalo em que o socket esteve fora. ```js theme={null} const url = `${wsUrl}&resume=1`; let deadline = 0; function connect() { const ws = new WebSocket(url); ws.binaryType = "arraybuffer"; ws.onopen = () => (deadline = 0); ws.onclose = (e) => { if (e.code === 1000 || e.code === 1008) return cleanup(); // desligou ou foi recusado deadline ||= Date.now() + 18_000; if (Date.now() < deadline) setTimeout(connect, 500); else cleanup(); }; // ...onmessage como nos passos anteriores } ``` ## Formato de áudio Todo o áudio, nos dois sentidos, segue exatamente este formato: **Codec** `PCM s16le` Inteiros de 16 bits com sinal, little-endian. Frames **binários** (não base64). **Taxa de amostragem** `16000 Hz` **Canais** `1 (mono)` **Tamanho do frame** `320 amostras = 640 bytes = 20 ms` Envie em cadência de tempo real (um frame a cada \~20 ms), sem acumular e despejar em lote. ## Gravação Toda chamada por stream é gravada. Perto do fim, o servidor envia: ```json theme={null} { "type": "recording", "files": { "full": "https://...", "sender": "https://...", "recipient": "https://..." }, "url": "https://..." } ``` Os arquivos são WAV mono de 16 kHz (`full` = mixagem, `sender`/`recipient` = lados separados). A mesma gravação também fica disponível depois em `GET /api/v1/calls/:callId`. ## Erros e limites **429 Too Many Requests** Limite de novas chamadas por usuário (padrão: **10 a cada 60 s**). Evita bloqueios do WhatsApp por excesso de tentativas. Aguarde antes de tentar de novo. **503 Service Unavailable** O stream de voz está indisponível no momento. Tente novamente mais tarde. **Duração máxima** `3600 s` Ao atingir o limite, a chamada encerra com `ended` e `reason: "terminate"`. Os eventos `error` trazem um `code`: `unavailable`, `not_found`, `unauthorized` ou `forbidden`. ## Exemplo completo Um cliente mínimo que inicia (via seu backend), conecta, transmite áudio e oferece mutar/desligar: ```js theme={null} async function iniciarChamada({ sessionId, phone }) { // 1. Inicie pelo seu backend — a API Key não vai ao navegador. const { wsUrl } = await fetch("/api/iniciar-chamada", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ sessionId, phone }), }).then((r) => r.json()); // 2. Áudio. const ctx = new AudioContext({ sampleRate: 16000 }); await ctx.audioWorklet.addModule("/voip-worklet.js"); const mic = await navigator.mediaDevices.getUserMedia({ audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true, autoGainControl: true }, }); const node = new AudioWorkletNode(ctx, "voip-io", { numberOfInputs: 1, numberOfOutputs: 1, outputChannelCount: [1], }); ctx.createMediaStreamSource(mic).connect(node); node.connect(ctx.destination); // 3. WebSocket. let canSendUplink = false; const ws = new WebSocket(wsUrl); ws.binaryType = "arraybuffer"; node.port.onmessage = (ev) => { if (ev.data?.kind === "out" && canSendUplink && ws.readyState === WebSocket.OPEN) { ws.send(ev.data.pcm); } }; ws.onmessage = (e) => { if (typeof e.data !== "string") { node.port.postMessage({ kind: "in", pcm: e.data }, [e.data]); return; } const msg = JSON.parse(e.data); if (msg.type === "accepted" || msg.type === "connected") canSendUplink = true; if (msg.type === "ended" || msg.type === "error") cleanup(); console.log("evento", msg); }; ws.onclose = () => cleanup(); function cleanup() { mic.getTracks().forEach((t) => t.stop()); if (ctx.state !== "closed") ctx.close(); } return { mutar: (m) => mic.getAudioTracks().forEach((t) => (t.enabled = !m)), desligar: () => ws.close(), }; } ``` ## Próximos passos > [card] [Webhooks de chamadas](/whatsapp/webhooks/chamadas) > > Receba chamadas de entrada (`call.offer`) e o ciclo de vida por webhook. > [card] [Referência da API](/api-reference/introduction) > > Autenticação, sessões e todos os endpoints da D-API. # Ligações com WebRTC Source: https://docs.d-api.cloud/whatsapp/ligacoes/webrtc A forma recomendada de falar em tempo real nas ligações: o SDK cuida do áudio por WebRTC, com volta automática para o WebSocket. O **WebRTC é o transporte recomendado** para o áudio das ligações em tempo real. O áudio vai por UDP com Opus e correção de perda (FEC), então aguenta bem melhor rede ruim, Wi-Fi instável e 4G do que o áudio pelo WebSocket. Você usa pelo [`d-api-sdk`](https://www.npmjs.com/package/d-api-sdk), com uma opção: ```js theme={null} const call = await LiveCall.connect(callId, wsUrl, { transport: "webrtc" }); ``` > [!NOTE] > > Vale para ligações de WhatsApp (saída e recebidas) e para a > [URA ao vivo](/ura/ligacoes/stream). Você precisa de uma **conexão WhatsApp não > oficial já conectada** e de uma **API Key** do [painel](https://app.d-api.cloud). ## Como funciona **1. Seu backend inicia a chamada** Com a API Key, `dapi.calls.stream()` retorna `callId` e `wsUrl`. Só esses dois vão para o navegador, nunca a API Key. **2. O navegador abre a chamada** `LiveCall.connect()` pede o microfone, abre o WebSocket de controle e já toca o áudio por ele. **3. O áudio passa para o WebRTC** Em menos de um segundo o SDK negocia o WebRTC e move o áudio para ele. Eventos, mudo e desligar continuam no WebSocket. **4. Se a rede bloquear o WebRTC** O áudio volta sozinho para o WebSocket, sem derrubar a chamada, e o SDK tenta o WebRTC de novo em segundo plano. Os eventos, os webhooks `call.*` e a gravação são os mesmos do WebSocket: só o caminho do áudio muda. ## Instalação ```bash theme={null} npm install d-api-sdk ``` No **Node** (bots, agentes de IA), o WebRTC usa um pacote opcional: ```bash theme={null} npm install d-api-sdk @roamhq/wrtc ``` Sem o `@roamhq/wrtc`, `transport: "webrtc"` continua funcionando pelo WebSocket. No navegador nada mais é preciso: o WebRTC é nativo. ## No navegador O exemplo completo tem duas partes: uma rota no seu backend, que guarda a API Key, e a página. ### Backend: inicie a chamada ```js server.js theme={null} import express from "express"; import { DApi } from "d-api-sdk"; const dapi = new DApi({ apiKey: process.env.DAPI_API_KEY }); const app = express(); app.use(express.json()); // Autentique o SEU usuário aqui antes de ligar em nome dele. app.post("/api/call", async (req, res) => { const { callId, wsUrl } = await dapi.calls.stream({ sessionId: req.body.sessionId, phone: req.body.phone, // DDI + DDD + número, só dígitos }); res.json({ callId, wsUrl }); // só isso vai ao navegador }); app.listen(3000); ``` ### Página: fale e ouça ```js call.js theme={null} import { LiveCall } from "d-api-sdk"; let call = null; document.querySelector("#ligar").onclick = async () => { const res = await fetch("/api/call", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ sessionId: "minha-sessao", phone: "5511999999999" }), }); const { callId, wsUrl } = await res.json(); call = await LiveCall.connect(callId, wsUrl, { transport: "webrtc" }); call.on("event", (e) => console.log("chamada:", e.type)); call.on("transport", (t) => console.log("áudio via", t.transport, t.reason ?? "")); call.on("ended", (e) => console.log("fim", e.reason ?? "")); call.on("recording", (r) => console.log("gravação:", r.url)); }; document.querySelector("#mudo").onclick = () => call?.mute(true); document.querySelector("#desligar").onclick = () => call?.hangup(); ``` O SDK pede o microfone, toca a voz do outro lado e só envia o seu áudio depois que a pessoa atende. Chame `LiveCall.connect()` dentro de um clique: os navegadores só liberam áudio a partir de uma ação do usuário. A página precisa estar em HTTPS (ou `localhost`). > [!TIP] > > Use um bundler (Vite, webpack, Next.js) para importar o `d-api-sdk` no navegador. ## No Node (bots e agentes de IA) No Node o SDK entrega o áudio cru para o seu código: **PCM `s16le`, 16 kHz, mono**, em frames de 20 ms (320 amostras). ```js bot.js theme={null} import { DApi } from "d-api-sdk"; const dapi = new DApi({ apiKey: process.env.DAPI_API_KEY }); const call = await dapi.calls.start( { sessionId: "minha-sessao", phone: "5511999999999" }, { transport: "webrtc" }, ); call.on("audio", (frame) => stt.write(frame)); // Int16Array, 20 ms tts.on("audio", (pcm) => call.sendAudio(pcm)); // Int16Array ou bytes s16le, ritmo real call.on("event", (e) => e.type === "accepted" && tts.say("Olá! Como posso ajudar?")); call.on("ended", () => process.exit(0)); ``` Áudio enviado antes do `accepted` é descartado: o outro lado ainda não está ouvindo, e esse áudio atrasaria a chamada inteira. Envie no ritmo real (20 ms de áudio a cada 20 ms); rajadas grandes ficam enfileiradas e chegam atrasadas. ## Receber ligações Com o [recebimento ativo](/whatsapp/ligacoes/receber) na conexão: ```js theme={null} const incoming = await dapi.calls.listen({ sessionIds: ["minha-sessao"] }); incoming.on("call", async (offer) => { console.log("tocando:", offer.from); const call = await offer.answer({ transport: "webrtc" }); // ou: await offer.reject() }); incoming.on("withdrawn", (e) => console.log("parou de tocar:", e.callId)); ``` No navegador, siga o mesmo padrão do exemplo acima: o seu backend chama `dapi.calls.accept({ sessionId, callId, from })` e entrega `{ callId, wsUrl }` à página, que chama `LiveCall.connect()`. ## URA ao vivo ```js theme={null} const call = await dapi.voice.live({ to: "5511999999999" }, { transport: "webrtc" }); ``` A mesma interface: eventos (incluindo `dtmf`), áudio, `hangup()`. Veja [cobrança e limites](/ura/ligacoes/stream) da URA. ## Eventos | Evento | Quando | | - | - | | `event` | Cada evento do ciclo de vida, como a D-API envia: `calling`, `ringing`, `accepted`, `dtmf` (URA), `ended`, `not_answered` | | `transport` | O áudio mudou de caminho: `{ transport: "webrtc" }` ou `{ transport: "websocket", reason }` | | `audio` | 20 ms do outro lado (Node, ou navegador com `audio: "pcm"`) | | `ended` | A chamada terminou | | `recording` | URL da gravação, depois do fim | | `error` / `close` | Erro do servidor / socket fechado de vez | ## Opções | Opção | Padrão | | | - | - | - | | `transport` | `"websocket"` | `"webrtc"` move o áudio para o WebRTC (recomendado) | | `fallback` | `true` | Fica no WebSocket quando o WebRTC falha. `false` encerra a chamada em vez disso | | `audio` | `"device"` no navegador, `"pcm"` no Node | Quem cuida do áudio: o SDK (microfone e alto-falante) ou o seu código | | `webrtcConnectTimeoutMs` | `10000` | Tempo para o WebRTC conectar antes de cair para o WebSocket | | `resume` | `true` | Reconecta o WebSocket se a rede cair, sem perder a chamada | ## Quando o WebRTC cai O evento `transport` diz por onde o áudio está indo e por quê: | `reason` | O que aconteceu | O SDK tenta de novo? | | - | - | - | | `webrtc_disconnected`, `webrtc_failed` | A rede caiu ou bloqueou o UDP | Sim, com intervalo crescente (2 s até 30 s) | | `ice_timeout`, `signal_timeout`, `gateway_error`, `at_capacity` | O WebRTC não conectou desta vez | Sim | | `unavailable` | WebRTC indisponível no servidor | Não | | `missing_dependency` | Node sem o `@roamhq/wrtc` | Não | | `unsupported_runtime` | Ambiente sem WebRTC | Não | Durante a troca o áudio para por poucos segundos e a chamada continua. Redes corporativas que bloqueiam UDP ficam no WebSocket. ## Migrando do WebSocket manual Se você seguiu as [Ligações por Stream](/whatsapp/ligacoes/stream), o Passo 1 (o backend chamando `POST /calls/stream`) não muda. Os Passos 2 a 5 viram uma linha: ```js Antes (WebSocket manual) theme={null} const ws = new WebSocket(wsUrl); ws.binaryType = "arraybuffer"; const ctx = new AudioContext({ sampleRate: 16000 }); await ctx.audioWorklet.addModule("/voip-worklet.js"); const mic = await navigator.mediaDevices.getUserMedia({ audio: true }); // ... worklet, canSendUplink, onmessage, reconexão ... ``` ```js Depois (SDK com WebRTC) theme={null} import { LiveCall } from "d-api-sdk"; const call = await LiveCall.connect(callId, wsUrl, { transport: "webrtc" }); call.on("event", (e) => handleEvent(e)); // os mesmos eventos de antes ``` Os eventos que o seu código já trata chegam iguais em `call.on("event")`. ## Outras linguagens O SDK fala um protocolo aberto no mesmo WebSocket da `wsUrl`. Para implementar em outra linguagem, com qualquer biblioteca WebRTC: | Você envia | A D-API responde | | - | - | | `{"type":"webrtc.config"}` | `{"type":"webrtc.config","iceServers":[...]}`: use na sua `RTCPeerConnection` | | `{"type":"webrtc.offer","sdp":"..."}`, offer completa (sem trickle ICE) com uma trilha de áudio Opus | `{"type":"webrtc.answer","sdp":"..."}` | | `{"type":"media","transport":"webrtc"}`, depois do peer conectado | A partir daqui o áudio só passa pelo WebRTC | | `{"type":"media","transport":"websocket"}` | O áudio volta para o WebSocket | Se algo falhar, chega `{"type":"webrtc.error","code":"..."}` com `unavailable`, `invalid_offer`, `at_capacity`, `gateway_error` ou `not_negotiated`, e o áudio segue no WebSocket. Quem nunca envia essas mensagens continua exatamente como antes. ## Próximos passos > [card] [Ligações por Stream](/whatsapp/ligacoes/stream) > > O protocolo do WebSocket, os eventos e a gravação. > [card] [Receber Ligações](/whatsapp/ligacoes/receber) > > Ative o recebimento e atenda pelo SDK. # Eventos de chamadas de voz (VoIP) Source: https://docs.d-api.cloud/whatsapp/webhooks/chamadas Chamadas de voz do WhatsApp recebidas e realizadas no número da sessão. Estes eventos cobrem as **chamadas de voz do WhatsApp (VoIP)** no número da sessão: chamadas recebidas e o ciclo de vida de chamadas de saída. Todos são entregues no webhook **por sessão**, com o [envelope comum](/whatsapp/webhooks/visao-geral) `{ event, sessionId, data, timestamp, traceId? }`. > [!WARNING] > > **Não confunda com o produto URA.** Os eventos de URA usam outro envelope — > `{ event, channel: "voice", data: { callId, bulkCallId, ... } }` — e não são > o que esta página documenta. Aqui tratamos apenas das chamadas de voz do > WhatsApp no número da sessão. > [!NOTE] > > Eventos de chamada são despachados **apenas para o webhook D-API e para o > RabbitMQ** — eles **não** são enviados para integrações de CRM. O evento > `call.offer` é entregue **mesmo com a rejeição automática ligada**. ## Direção dos eventos | Evento | Direção | | - | - | | `call.offer` | Entrada (chamada recebida) | | `call.accepted` | Entrada (atendida em outro dispositivo) | | `call.rejected` | Entrada ou saída (recusada) | | `call.ringing` | Saída (chamando) | | `call.connected` | Saída (conectada) | | `call.ended` | Entrada ou saída (encerrada; na saída, só se **atendida**) | | `call.not_answered` | Saída (tocou mas **não foi atendida**) | | `call.audio` | Saída (áudio da chamada) | As chamadas de saída são iniciadas via `POST /calls/place` (chamada padrão) e `POST /calls/stream` (modo com gravação). Os eventos abaixo refletem o andamento dessas chamadas. ## Quem é a outra ponta: `phone` Todos os eventos `call.*` trazem `phone`: o telefone **da outra ponta da chamada** — quem ligou para a sessão ou quem a sessão chamou —, **só dígitos**, sem `@s.whatsapp.net`. Nunca é o número da própria sessão, em nenhuma direção. Use este campo para identificar o contato. **phone** `string | null` *required* Telefone da outra ponta, só dígitos (ex.: `5511999999999`). Vem `null` quando o WhatsApp só informou um LID sem telefone conhecido; nesse caso o LID vem em `lid`. Não aparece nos chunks ao vivo de `call.audio`. **lid** `string` LID da outra ponta (`...@lid`). Presente **apenas quando** `phone` é `null`. Um LID não é um telefone: não use os dígitos dele como número. > [!WARNING] > > Não use `from` nem `callCreator` para identificar o contato. Eles indicam > **quem iniciou** a chamada: numa chamada feita pela sessão, os dois trazem o > número da própria sessão. Continuam no payload por compatibilidade. ## `call.offer` — chamada recebida Disparado quando o número da sessão **recebe** uma chamada. ```json theme={null} { "event": "call.offer", "sessionId": "minha-sessao", "data": { "callId": "ABCD1234", "phone": "5511999999999", "from": "5511999999999", "callCreator": "5511999999999", "isGroup": false, "timestamp": 1716724496789 }, "timestamp": "2026-05-26T12:34:56.789Z", "traceId": "a1b2c3d4-..." } ``` **callId** `string` *required* Identificador da chamada. **phone** `string | null` *required* Telefone de quem está ligando. Ver [`phone`](#quem-e-a-outra-ponta-phone). **from** `string` *required* Quem iniciou a chamada, resolvido para telefone quando possível (ou `...@lid`). Mantido por compatibilidade — prefira `phone`. **callCreator** `string` Quem iniciou a chamada, como informado pelo WhatsApp. Pode vir como `@lid`. Mantido por compatibilidade — prefira `phone`. **isGroup** `boolean` *required* `true` quando a chamada é de grupo. **groupJid** `string` JID do grupo. Presente **apenas quando** `isGroup` é `true`. **timestamp** `number` *required* Momento da chamada em milissegundos (epoch). ## Chamadas de saída — payload base Os eventos de saída (`call.ringing`, `call.connected`, `call.ended`, `call.not_answered`) compartilham o mesmo payload base (`CallEvent`): **callId** `string` Identificador da chamada. **state** `string` Estado da chamada. Varia por evento (ver abaixo). **reason** `string` Motivo do encerramento. Presente **apenas em** `call.ended`. **peerLid** `string` JID do interlocutor em formato `@lid`. Opcional. **peerPn** `string` JID do interlocutor em formato de telefone. Opcional. ### `call.ringing` Estado `"ringing"` — a chamada está tocando. É o **primeiro evento** de uma chamada de saída, emitido assim que a chamada é iniciada (discada) — antes de `call.connected`. ```json theme={null} { "event": "call.ringing", "sessionId": "minha-sessao", "data": { "callId": "ABCD1234", "state": "ringing", "peerPn": "5511999999999@s.whatsapp.net", "phone": "5511999999999" }, "timestamp": "2026-05-26T12:34:57.000Z" } ``` ### `call.connected` Estado `"active"` — a chamada foi atendida e está em andamento. ```json theme={null} { "event": "call.connected", "sessionId": "minha-sessao", "data": { "callId": "ABCD1234", "state": "active", "peerPn": "5511999999999@s.whatsapp.net", "phone": "5511999999999" }, "timestamp": "2026-05-26T12:35:02.000Z" } ``` ### `call.ended` Estado `"idle"` — a chamada foi encerrada. O campo `reason` é preenchido. > [!NOTE] > > Uma chamada gera **exatamente um** `call.ended` (eventos duplicados do bridge > são deduplicados por `callId`). Para chamadas de saída, o `call.ended` cobre > apenas as que foram **atendidas** — uma que tocou e não foi atendida gera > [`call.not_answered`](#call-not-answered) no lugar. ```json theme={null} { "event": "call.ended", "sessionId": "minha-sessao", "data": { "callId": "ABCD1234", "state": "idle", "reason": "hangup", "peerPn": "5511999999999@s.whatsapp.net", "phone": "5511999999999" }, "timestamp": "2026-05-26T12:35:40.000Z" } ``` ### `call.not_answered` Estado `"idle"` — uma chamada de **saída** que **tocou mas nunca foi atendida** (encerrou antes de conectar, incluindo o timeout de não-atendimento). Substitui o `call.ended` nesse caso, para você distinguir "não atendida" de "atendida e encerrada" sem inspecionar o `reason`. Vale **apenas para chamadas de saída**. ```json theme={null} { "event": "call.not_answered", "sessionId": "minha-sessao", "data": { "callId": "ABCD1234", "state": "idle", "reason": "no_answer", "peerPn": "5511999999999@s.whatsapp.net", "phone": "5511999999999" }, "timestamp": "2026-05-26T12:35:40.000Z" } ``` > [!NOTE] > > Chamadas não atendidas **não geram gravação**: não há upload de áudio nem > evento `call.audio`. (A chamada ainda fica registrada na trilha de auditoria > interna, marcada como não atendida.) ## `call.audio` O evento `call.audio` tem **duas variantes**, dependendo de como a chamada de saída foi iniciada. > [!WARNING] > > Na variante de chunks ao vivo, o `call.audio` pode ter **volume alto** — cerca > de **1 evento por segundo por chamada**. Habilite-o **apenas** se você for > consumir o áudio. ### Variante A — chunks de áudio ao vivo Áudio transmitido em pedaços de \~1s cada, **ordenados por `seq`**, com `final: true` no último chunk. ```json theme={null} { "event": "call.audio", "sessionId": "minha-sessao", "data": { "callId": "ABCD1234", "seq": 0, "sampleRate": 16000, "channels": 1, "encoding": "pcm_s16le", "data": "", "final": false }, "timestamp": "2026-05-26T12:35:03.000Z" } ``` **callId** `string` Identificador da chamada. **seq** `number` Número de sequência do chunk. Use para ordenar os pedaços. **sampleRate** `number` Taxa de amostragem (tipicamente `16000`). **channels** `number` Número de canais (tipicamente `1`). **encoding** `string` Codificação do áudio (`pcm_s16le`). **data** `string` Pedaço de áudio PCM em base64. **final** `boolean` `true` no último chunk da chamada. ### Variante B — gravação pronta (modo stream) Um **único evento ao final** da chamada, com as URLs da gravação. Ocorre no modo stream (`POST /calls/stream`) **apenas para chamadas atendidas** — chamadas que não foram atendidas não geram gravação nem este evento. ```json theme={null} { "event": "call.audio", "sessionId": "minha-sessao", "data": { "callId": "ABCD1234", "files": { "full": "https://.../calls/ABCD1234.wav", "sender": "https://.../calls/ABCD1234-sender.wav", "recipient": "https://.../calls/ABCD1234-recipient.wav" }, "url": "https://.../calls/ABCD1234.wav", "durationMs": 12000, "sizeBytes": 384044, "mimetype": "audio/wav" }, "timestamp": "2026-05-26T12:35:40.000Z" } ``` **callId** `string` Identificador da chamada. **files** `object` Faixas de áudio mono 16kHz: **files** **full** `string` Mixagem completa da chamada. **sender** `string | null` Faixa do microfone (lado da sessão). **recipient** `string | null` Faixa do interlocutor (peer). **url** `string` *deprecated* **Depreciado** — alias de `files.full`. **durationMs** `number` Duração da gravação em milissegundos. **sizeBytes** `number | null` Tamanho do arquivo em bytes. **mimetype** `string` Tipo do arquivo (`audio/wav`). **phone** `string | null` Telefone da outra ponta, só dígitos. ## `call.accepted` / `call.rejected` `call.accepted`: chamada **recebida** atendida em outro dispositivo. `call.rejected`: chamada recusada — uma recebida que a sessão recusou, ou uma feita pela sessão que o contato recusou. Nos dois casos, `phone` é o contato. ```json theme={null} { "event": "call.rejected", "sessionId": "minha-sessao", "data": { "callId": "ABCD1234", "phone": "5511999999999", "from": "5500000000000" }, "timestamp": "2026-05-26T12:34:58.000Z" } ``` > [!NOTE] > > O payload destes eventos é **repassado tal como vem do bridge** (relayed > as-is). Os campos garantidos são `callId` e `phone` (o contato). O `from` é > quem iniciou a chamada — no exemplo acima, a própria sessão, que ligou e foi > recusada. Os demais campos espelham os dados de chamada do bridge e não são > documentados aqui para evitar suposições. # Chats, contatos e presença Source: https://docs.d-api.cloud/whatsapp/webhooks/chats-contatos-presenca Atualizações de chats, contatos e presença (online/digitando). Estes eventos mantêm seu sistema sincronizado com o **estado dos chats**, os **dados de contatos** e a **presença** (online, visto por último). Todos seguem o [envelope comum](/whatsapp/webhooks/visao-geral) — o conteúdo específico fica em `data`. ## `chats.update` e `chats.upsert` `chats.upsert` indica um chat **criado ou recebido na sincronização**; `chats.update` indica uma **atualização** de um chat existente. Os dois eventos têm o **mesmo formato** de `data`. ```json theme={null} { "event": "chats.update", "sessionId": "my-session", "timestamp": "2026-01-24T23:05:00.000Z", "data": { "jid": "5511999999999@s.whatsapp.net", "name": "João", "unread_count": 2, "conversation_timestamp": 1769295900, "archived": false, "pinned": 0, "mute_end_time": 0 } } ``` **jid** `string` *required* JID do chat (contato ou grupo). **name** `string` Nome do chat (contato ou nome do grupo). **unread\_count** `number` Quantidade de mensagens não lidas. **conversation\_timestamp** `number` Momento da última atividade da conversa em segundos (epoch). **archived** `boolean` `true` quando o chat está arquivado. **pinned** `number` Indica se o chat está fixado (`0` quando não está). **mute\_end\_time** `number` Momento (epoch) em que o silenciamento termina; `0` quando não está silenciado. > [!NOTE] > > Eventos `chats.upsert` passam por **debounce de 2 segundos** por chat: > múltiplas atualizações do mesmo chat em sequência são agrupadas. ## `contacts.update` e `contacts.upsert` `contacts.upsert` indica um contato **criado ou recebido na sincronização**; `contacts.update` indica uma **atualização** de um contato existente. Os dois eventos têm o **mesmo formato** de `data`. ```json theme={null} { "event": "contacts.update", "sessionId": "my-session", "timestamp": "2026-01-24T23:06:00.000Z", "data": { "jid": "5511999999999@s.whatsapp.net", "push_name": "João", "full_name": "João Silva", "first_name": "João", "business_name": "" } } ``` **jid** `string` *required* JID do contato. **push\_name** `string` Nome de exibição definido pelo próprio contato no WhatsApp. **full\_name** `string` Nome completo do contato (quando salvo na agenda). **first\_name** `string` Primeiro nome do contato. **business\_name** `string` Nome comercial, quando se trata de uma conta business. String vazia (`""`) quando não se aplica. > [!NOTE] > > Eventos `contacts.upsert` passam por **debounce de 2 segundos** por contato: > múltiplas atualizações do mesmo contato em sequência são agrupadas. ## `presence` Disparado quando muda a **presença** de um contato (online/offline, visto por último). ```json theme={null} { "event": "presence", "sessionId": "my-session", "timestamp": "2026-01-24T23:07:00.000Z", "data": { "jid": "5511999999999@s.whatsapp.net", "name": "João", "unavailable": false, "last_seen": 1769296020 } } ``` **jid** `string` *required* JID do contato cuja presença mudou. **name** `string` Nome do contato. **unavailable** `boolean` `true` quando o contato está **offline/indisponível**; `false` quando está online. **last\_seen** `number` Momento do último acesso em segundos (epoch), quando disponível. > [!NOTE] > > O evento `presence` passa por **deduplicação de 5 segundos** por contato e > estado (online/offline): mudanças idênticas dentro dessa janela não geram > webhooks duplicados. # Eventos de conexão Source: https://docs.d-api.cloud/whatsapp/webhooks/conexao QR code, código de pareamento e mudanças de status da sessão. Estes eventos acompanham o **ciclo de conexão** de uma sessão do WhatsApp: a geração do QR code, o código de pareamento, e as mudanças de status (conectado, desconectado, deslogado). Todos seguem o [envelope comum](/whatsapp/webhooks/visao-geral) — o conteúdo específico fica em `data`. ## `session.created` Disparado quando uma conexão da **API Oficial** termina de ser provisionada pelo [connect hospedado](/api-oficial/saas) — o fluxo do SDK `connect.start()`, usado por quem revende a API Oficial para os próprios clientes. Vai para o `webhookUrl` daquela conexão, **sempre**, em paralelo ao resultado que o `connect.start()` devolve no navegador. É o único aviso que chega no **mobile**: lá o popup abre como aba e o `postMessage` de volta para a sua página não acontece, então o `start()` pode rejeitar mesmo com a conexão criada. Use `connect.start({ metadata })` para carregar o seu identificador de cliente e reencontrá-lo aqui em `data.metadata`. ```json theme={null} { "event": "session.created", "sessionId": "cloud-9f2c1e5a-…", "timestamp": "2026-08-02T12:00:00.000Z", "data": { "connectionId": "9f2c1e5a-…", "connectionType": "cloud_api", "status": "connected", "wabaId": "123456789", "phoneNumberId": "987654321", "businessId": "555555555", "phoneNumber": "+5511999999999", "verifiedName": "Acme Ltda", "accessToken": "EAAG…", "accessTokenKind": "long_lived", "accessTokenExpiresAt": "2026-10-01T00:00:00.000Z", "webhookMode": "normalized", "metadata": { "tenantId": "acme-42" } } } ``` **connectionId** `string` *required* Id da conexão — é o `sessionId` nas rotas de envio. **wabaId** `string` *required* WhatsApp Business Account do cliente na Meta. **phoneNumberId** `string` *required* Id do número na Cloud API. **accessToken** `string` *required* Access token da Meta daquela conexão, já descriptografado. **É segredo**: pode enviar mensagens e administrar a WABA. **accessTokenKind** `string` *required* `permanent`, `long_lived`, `short_lived` ou `unknown`. **accessTokenExpiresAt** `string` Expiração em ISO-8601, ou `null` quando o token não expira. **metadata** `object` *required* O JSON livre que você passou em `connect.start({ metadata })`. `{}` quando não foi enviado. > [!WARNING] > > Como o payload carrega o access token, o evento só é entregue no `webhookUrl` > **da própria conexão** e apenas por **HTTPS** — um endpoint `http://` é > recusado, e o disparo fica registrado no log. Nos > [logs de webhook](/api-reference/webhooks/listar-logs) o token aparece como > `[REDACTED]`; ele existe só no corpo entregue ao seu endpoint. ## `connection.qrcode` Disparado quando um **novo QR code** é gerado para autenticar a sessão. Inclui o texto do QR e a imagem já renderizada em base64 (PNG), pronta para exibir. ```json theme={null} { "event": "connection.qrcode", "sessionId": "my-session", "timestamp": "2026-01-24T22:00:00.000Z", "data": { "qr": "2@abc...", "qrImage": "data:image/png;base64,iVBOR..." } } ``` **qr** `string` *required* Conteúdo textual do QR code a ser escaneado pelo WhatsApp. **qrImage** `string` Imagem do QR code como data URL (PNG em base64). Pode vir `null` caso a geração da imagem falhe — nesse caso use o campo `qr` para renderizar. > [!NOTE] > > QR codes idênticos ao último gerado para a sessão são **deduplicados** e não > geram novo webhook. ## `connection.paircode` Disparado quando um **código de pareamento** é gerado (conexão por número de telefone, sem escanear QR). ```json theme={null} { "event": "connection.paircode", "sessionId": "my-session", "timestamp": "2026-01-24T22:00:05.000Z", "data": { "code": "ABCD-1234", "phone": "5511999999999" } } ``` **code** `string` *required* Código de pareamento a ser digitado no aparelho. **phone** `string` *required* Número de telefone para o qual o código foi gerado. ## `connection.status` Disparado a cada **mudança de status** da conexão. O campo `data.status` identifica o estado. Os demais campos variam conforme o estado. ```json theme={null} { "event": "connection.status", "sessionId": "my-session", "timestamp": "2026-01-24T22:00:30.000Z", "data": { "status": "connected", "jid": "558005915338@s.whatsapp.net", "phone": "558005915338", "name": "Minha Empresa", "connected": true } } ``` **status** `string` *required* Estado da conexão. Valores possíveis: `connected`, `disconnected`, `logged_out` e `qrcode_timeout`. **jid** `string` JID da conta conectada. Presente quando o status é `connected`. **phone** `string` Número de telefone da conta conectada. **name** `string` Nome exibido da conta conectada. **profilePictureUrl** `string` URL da foto de perfil da conta, quando disponível. **connected** `boolean` `true` quando a sessão acabou de conectar. **reason** `string` Motivo da desconexão. Presente nos status `disconnected` e `logged_out`. ### `logged_out` (despachado como `connection.status`) Quando a sessão é **deslogada** (ex: o aparelho foi removido pelo usuário), o evento é entregue como `connection.status` com `data.status: "logged_out"`. ```json theme={null} { "event": "connection.status", "sessionId": "my-session", "timestamp": "2026-01-24T22:10:00.000Z", "data": { "status": "logged_out", "reason": "device_removed" } } ``` > [!NOTE] > > Não existe um evento `logged_out` separado no webhook: o logout é sempre > entregue como `connection.status` com `data.status: "logged_out"`. Para > detectar que a sessão precisa ser reconectada, verifique > `data.status === "logged_out"` (e também `"disconnected"`). ### `qrcode_timeout` (despachado como `connection.status`) Quando uma sessão passa **45 minutos gerando QR code** sem que ninguém o escaneie, e sem nenhum pedido de QR nesse período, a D-API **hiberna** a sessão: o processo que gera os QR codes é desligado, os eventos `connection.qrcode` param de chegar e você recebe um único `connection.status` com `data.status: "qrcode_timeout"`. ```json theme={null} { "event": "connection.status", "sessionId": "my-session", "timestamp": "2026-10-28T18:45:00.000Z", "data": { "status": "qrcode_timeout", "timestamp": "2026-10-28T18:45:00.000Z" } } ``` A partir daí a sessão aparece como `disconnected` em `GET /api/v1/sessions/{sessionId}`, com `disconnectReason: "qrcode_timeout"`. Nada é apagado: a sessão, as configurações e o webhook continuam os mesmos. Para voltar a gerar QR, basta pedir um QR como você já faz: * [`GET /api/v1/sessions/{sessionId}/qr`](/api-reference/endpoints/conectar-qr); * `POST /api/v1/sessions/{sessionId}/connect` ou `POST /api/v1/sessions/{sessionId}/restart`; * `GET /api/v1/sessions/{sessionId}/pair-code`; * abrir o link público de QR da sessão. O primeiro pedido acorda a sessão e responde como antes, com o QR anterior marcado como expirado (`expired: true`). O QR novo chega em alguns segundos, pela própria rota de QR (consulte de novo) ou pelo evento `connection.qrcode`. Cada pedido de QR também zera a contagem dos 45 minutos, então uma tela que consulta o QR enquanto o usuário está com ela aberta nunca é hibernada. > [!NOTE] > > `qrcode_timeout` não é um erro e não exige ação se ninguém está tentando > conectar aquele número. Se você mostra o QR para o seu usuário só a partir > do webhook `connection.qrcode`, trate `qrcode_timeout` chamando > `GET /api/v1/sessions/{sessionId}/qr` quando ele voltar à tela de conexão. # Eventos de etiquetas Source: https://docs.d-api.cloud/whatsapp/webhooks/etiquetas Etiquetas (Listas do WhatsApp) criadas, editadas e aplicadas a conversas e mensagens. O WhatsApp organiza conversas em **etiquetas**, que nas versões recentes do app aparecem como **Listas**. Estes webhooks notificam quando uma etiqueta é criada, editada ou excluída, e quando ela é aplicada ou removida de uma conversa ou de uma mensagem. Todos seguem o [envelope comum](/whatsapp/webhooks/visao-geral) — o conteúdo específico fica em `data`. | Evento | Quando | | - | - | | `labels.edit` | Etiqueta criada, editada ou excluída | | `labels.association.chat` | Etiqueta aplicada ou removida de uma conversa | | `labels.association.message` | Etiqueta aplicada ou removida de uma mensagem | > [!NOTE] > > Os webhooks entregam **mudanças**. Ao conectar, a sessão sincroniza todas as > etiquetas e associações da conta, mas essa sincronização não gera webhooks > (seria o mesmo estado reenviado a cada reconexão). Para o estado completo, use > `GET /labels/list` e `GET /labels/contact-labels`. ## `labels.edit` ```json theme={null} { "event": "labels.edit", "sessionId": "minha-sessao", "timestamp": "2026-09-30T16:30:00.000Z", "data": { "label_id": "25", "name": "MQL SaaS", "color": 3, "deleted": false, "list_type": "custom", "predefined_id": 0, "order_index": 12, "is_active": true, "is_immutable": false, "from_full_sync": false, "ts": 1790786186704 } } ``` **label\_id** `string` *required* Identificador da etiqueta. **name** `string` Nome da etiqueta. **color** `number` Código de cor da etiqueta. **deleted** `boolean` `true` quando a etiqueta foi **excluída**. **list\_type** `string` Tipo da lista. `custom` para as criadas pelo usuário; as listas do próprio WhatsApp vêm como `unread` (Não lidas), `favorites` (Favoritos), `groups` (Grupos), `predefined` (sugeridas pelo app, como "Novo pedido"), entre outras. Etiquetas antigas podem vir como `none`. **predefined\_id** `number` Identificador da lista sugerida pelo WhatsApp, quando `list_type` é `predefined`. `0` nas demais. **order\_index** `number` Posição da lista no app. **is\_active** `boolean` Se a lista está ativa no app. **is\_immutable** `boolean` `true` para listas do sistema, que o usuário não pode renomear nem excluir. **ts** `number` Momento do evento em milissegundos (epoch). ## `labels.association.chat` ```json theme={null} { "event": "labels.association.chat", "sessionId": "minha-sessao", "timestamp": "2026-09-30T16:36:26.764Z", "data": { "label_id": "25", "label_name": "MQL SaaS", "label_color": 3, "chat": "558597673993@s.whatsapp.net", "labeled": true, "from_full_sync": false, "ts": 1790786186704 } } ``` **label\_id** `string` *required* Identificador da etiqueta. **label\_name** `string | null` Nome da etiqueta. `null` se ela ainda não foi sincronizada. **label\_color** `number | null` Cor da etiqueta. `null` se ela ainda não foi sincronizada. **chat** `string` *required* JID da conversa (`...@s.whatsapp.net` ou `...@g.us`). Quando o número do contato não é conhecido pela sessão, vem como LID (`...@lid`). **labeled** `boolean` *required* `true` aplica a etiqueta à conversa; `false` remove. ## `labels.association.message` Mesmos campos de [`labels.association.chat`](#labels-association-chat), mais o identificador da mensagem. ```json theme={null} { "event": "labels.association.message", "sessionId": "minha-sessao", "timestamp": "2026-09-30T16:40:00.000Z", "data": { "label_id": "25", "label_name": "MQL SaaS", "label_color": 3, "chat": "558597673993@s.whatsapp.net", "message_id": "3EB0F61B5D1F94FAFCD306", "labeled": true, "from_full_sync": false, "ts": 1790786400000 } } ``` **message\_id** `string` *required* Identificador da mensagem. # Eventos de grupos Source: https://docs.d-api.cloud/whatsapp/webhooks/grupos Entradas, saídas, promoções e solicitações de entrada em grupos. Estes eventos notificam **movimentações em grupos**: participantes que entram, saem, são promovidos ou rebaixados, e o fluxo de **solicitações de entrada**. Todos seguem o [envelope comum](/whatsapp/webhooks/visao-geral) — o conteúdo específico fica em `data`. ## Participantes: join / leave / promote / demote Quatro eventos cobrem as mudanças de participantes e **compartilham o mesmo formato** de `data`: | Evento | Quando ocorre | | - | - | | `groups_participants.join` | Um ou mais participantes **entraram** no grupo | | `groups_participants.leave` | Um ou mais participantes **saíram** do grupo | | `groups_participants.promote` | Participante(s) **promovido(s)** a admin | | `groups_participants.demote` | Participante(s) **rebaixado(s)** de admin | ```json theme={null} { "event": "groups_participants.join", "sessionId": "my-session", "timestamp": "2026-01-24T23:10:00.000Z", "data": { "group_jid": "120363000000000000@g.us", "group_name": "Equipe", "participants": ["5511999999999@s.whatsapp.net"], "timestamp": 1769296200, "sender": "558005915338@s.whatsapp.net" } } ``` **group\_jid** `string` *required* JID do grupo (`@g.us`). **group\_name** `string` Nome do grupo. **participants** `string[]` *required* Lista de JIDs dos participantes afetados pela ação. **timestamp** `number` *required* Momento do evento em segundos (epoch). **sender** `string` JID de quem executou a ação (ex: o admin que adicionou/promoveu). ## Solicitações de entrada Quando um grupo exige **aprovação para entrar**, três eventos cobrem o ciclo da solicitação: | Evento | Quando ocorre | | - | - | | `group_participants.join-request` | Uma solicitação de entrada foi **criada** | | `group_participants.join-request.revoked` | A solicitação foi **revogada** pelo solicitante | | `group_participants.join-request.approved` | A solicitação foi **aprovada** por um admin | > [!NOTE] > > Não existe um evento de solicitação **rejeitada** — o backend emite apenas as > variantes acima. Use `.revoked` para detectar o cancelamento de uma > solicitação. ### `group_participants.join-request` ```json theme={null} { "event": "group_participants.join-request", "sessionId": "my-session", "timestamp": "2026-01-24T23:11:00.000Z", "data": { "group_jid": "120363000000000000@g.us", "group_name": "Equipe", "requester_jid": "5511999999999@s.whatsapp.net", "requester_name": "João", "timestamp": 1769296260 } } ``` **group\_jid** `string` *required* JID do grupo (`@g.us`). **group\_name** `string` Nome do grupo. **requester\_jid** `string` *required* JID de quem solicitou a entrada. **requester\_name** `string` Nome de quem solicitou a entrada. **timestamp** `number` *required* Momento da solicitação em segundos (epoch). ### `group_participants.join-request.revoked` Mesmo formato de `data` de `group_participants.join-request`. Indica que a solicitação foi **cancelada** pelo próprio solicitante. ### `group_participants.join-request.approved` Disparado quando um admin **aprova** a solicitação. Inclui o campo adicional `approved_by`. ```json theme={null} { "event": "group_participants.join-request.approved", "sessionId": "my-session", "timestamp": "2026-01-24T23:12:00.000Z", "data": { "group_jid": "120363000000000000@g.us", "group_name": "Equipe", "requester_jid": "5511999999999@s.whatsapp.net", "requester_name": "João", "approved_by": "558005915338@s.whatsapp.net", "timestamp": 1769296320 } } ``` **group\_jid** `string` *required* JID do grupo (`@g.us`). **group\_name** `string` Nome do grupo. **requester\_jid** `string` *required* JID de quem solicitou a entrada. **requester\_name** `string` Nome de quem solicitou a entrada. **approved\_by** `string` JID do admin que aprovou a solicitação. **timestamp** `number` *required* Momento da aprovação em segundos (epoch). # Histórico e sincronização Source: https://docs.d-api.cloud/whatsapp/webhooks/historico-e-sincronizacao Eventos do backfill de histórico e da sincronização do AppState, e o que é (ou não) entregue no webhook. Ao conectar, a sessão realiza uma **sincronização de histórico** (backfill), trazendo conversas, contatos e mensagens anteriores. Estes eventos refletem esse processo. > [!WARNING] > > A entrega no **webhook** difere bastante da entrega no **RabbitMQ** para estes > eventos. Alguns eventos de histórico são **suprimidos no webhook** para evitar > uma enxurrada de chamadas durante o backfill, e um deles é **convertido** para > outro evento. Leia os detalhes abaixo com atenção. ## Resumo de entrega | Evento | Entregue no webhook? | Entregue no RabbitMQ? | | - | - | - | | `history.message.upsert` | Não (suprimido) | Sim (quando configurado) | | `history.message.received` | Não (suprimido) | Sim (quando configurado) | | `history.messages.sent` | Convertido para `messages.received` com `fromMe: true` (apenas recentes \< 5 min) | Sim (mantém o nome original) | | `history_sync` | Sim | Sim | | `appstate.agent.update` | Sim | Sim | ## `history.message.upsert` e `history.message.received` São os eventos das mensagens trazidas pelo backfill. > [!WARNING] > > Estes eventos **não são entregues no webhook** — eles são **suprimidos** para > evitar uma enxurrada de chamadas durante o backfill. Ficam disponíveis apenas > via **RabbitMQ** (quando configurado). Os dados da mensagem seguem o **mesmo formato de** [`messages.received`](/whatsapp/webhooks/messages-received) (`id`, `from`, `to`, `type`, `timestamp`, etc.), porém: * **sem mídia** — a mídia é filtrada durante a sincronização; * com os **JIDs normalizados**. ## `history.messages.sent` São as mensagens **enviadas de outro dispositivo** identificadas durante o histórico. > [!NOTE] > > No **webhook**, este evento **não chega com o nome `history.messages.sent`**. > As mensagens enviadas de outro dispositivo só são entregues se forem > **recentes (menos de 5 minutos)** e são **convertidas** para o evento > [`messages.received`](/whatsapp/webhooks/messages-received) com `fromMe: true`. > > Via **RabbitMQ**, o evento mantém o nome original `history.messages.sent`. Nos dois canais, `data.isMetaAI` vem sempre `false`: o histórico não traz o sinal de mensagem escrita pela Meta AI. ## `history_sync` Entregue normalmente no webhook. É o **sinal de conclusão/resumo** do backfill, com os agregados sincronizados. ```json theme={null} { "event": "history_sync", "sessionId": "minha-sessao", "data": { "chats": [], "contacts": [], "messages": [] }, "timestamp": "2026-01-24T22:00:40.000Z" } ``` **chats** `array` *required* Conversas sincronizadas. Cada item segue o formato de [`chats.update`](/whatsapp/webhooks/chats-contatos-presenca). **contacts** `array` *required* Contatos sincronizados. Cada item segue o formato de [`contacts.update`](/whatsapp/webhooks/chats-contatos-presenca). **messages** `array` *required* Mensagens sincronizadas. Cada item segue o formato de mensagem do histórico. ## `appstate.agent.update` Entregue no webhook. Representa mudanças de **dispositivos/agentes vinculados** (multi-device) durante a sincronização do AppState. ```json theme={null} { "event": "appstate.agent.update", "sessionId": "minha-sessao", "data": { "index": 0, "name": "Dispositivo Web", "device_id": "...", "is_deleted": false }, "timestamp": "2026-01-24T22:00:41.000Z" } ``` **index** `number` Índice do dispositivo/agente. Opcional. **name** `string` Nome do dispositivo/agente. Opcional. **device\_id** `string` Identificador do dispositivo. Opcional. **is\_deleted** `boolean` `true` quando o dispositivo/agente foi removido. Opcional. # Evento messages.received Source: https://docs.d-api.cloud/whatsapp/webhooks/messages-received Disparado quando uma mensagem é recebida. ## Evento `messages.received` Disparado quando uma mensagem é recebida. > [!NOTE] > > Além de mensagens recebidas de contatos (`fromMe: false`), este evento também > é disparado para mensagens enviadas pelo **próprio número em outro dispositivo > ou celular**, com `fromMe: true`. Mensagens enviadas via API da D-API geram o > evento [`messages.sent`](/whatsapp/webhooks/messages-sent), e **não** > `messages.received`. ### Payload **event** `string` *required* Sempre `"messages.received"` **sessionId** `string` *required* ID da sessão que recebeu a mensagem **timestamp** `string` *required* Timestamp ISO 8601 do recebimento **traceId** `string` *required* ID único para rastreamento **data** `object` *required* **Campos de data** **id** `string` *required* ID único da mensagem **type** `string` *required* `text` | `image` | `video` | `audio` | `document` | `sticker` | `contact` | `location` | `reaction` | `edited_message` | `poll_update` | `list_response` | `template_button_reply` | `list` | `carousel` | `nativeflow` **message** `string` *required* Conteúdo textual da mensagem **timestamp** `number` *required* Unix timestamp em milissegundos **fromMe** `boolean` *required* Se a mensagem foi enviada por você **isMetaAI** `boolean` *required* `true` quando a mensagem foi escrita pelo agente de IA da Meta da conta business do contato (Meta AI do WhatsApp Business), e não por uma pessoa. Vem sempre: `false` em qualquer outro caso, inclusive mensagens de histórico, mensagens enviadas pela sessão e conexões da API Oficial, que não têm esse sinal. Também chega no RabbitMQ. **is\_group** `boolean` *required* Se é mensagem de grupo **group\_name** `string` *required* Nome do grupo (vazio se não for grupo) **from\_name** `string` *required* Nome do remetente **media\_url** `string | null` *required* URL do arquivo no S3 (para mensagens com mídia) **from** `object` *required* **Campos de from** **jid** `string` *required* WhatsApp ID (ex: `5511999999999@s.whatsapp.net`) **lid** `string` *required* ID interno do WhatsApp **name** `string` *required* Nome do contato **to** `object` *required* **Campos de to** **jid** `string` *required* WhatsApp ID do destinatário **name** `string` *required* Nome do destinatário **media\_data** `object` Presente em mensagens de mídia (image, video, audio, document, sticker) **Campos de media\_data** **url** `string` *required* URL original do WhatsApp (temporária) **file\_length** `number` *required* Tamanho em bytes **mimetype** `string` *required* MIME type do arquivo **width** `number` Largura (image/video/sticker) **height** `number` Altura (image/video/sticker) **caption** `string` Legenda (image/video/document) **duration** `number` Duração em segundos (audio/video) **is\_ptt** `boolean` Push-to-talk / mensagem de voz (audio) **filename** `string` Nome do arquivo (document) **is\_animated** `boolean` Se é sticker animado (sticker) **data** `object` Dados específicos para contact, location, reaction e poll\_update **ContactData (type=contact)** **contact\_name** `string` *required* Nome do contato **contact\_phone** `string` *required* Telefone do contato **display\_name** `string` *required* Nome de exibição **vcard** `string` *required* VCard completo **LocationData (type=location)** **degrees\_latitude** `number` *required* Latitude **degrees\_longitude** `number` *required* Longitude **name** `string` *required* Nome do local **address** `string` *required* Endereço **thumbnail** `string` *required* Imagem em Base64 **ReactionData (type=reaction)** **original\_message\_id** `string` *required* ID da mensagem original **reaction\_text** `string` *required* Emoji da reação **reaction\_timestamp** `number` *required* Timestamp da reação **target\_participant** `string` *required* Participante alvo (em grupos) **EditedMessageData (type=edited\_message)** **original\_message\_id** `string` *required* ID da mensagem que foi editada. Use este campo — e não `data.id`, que é o ID do evento de edição — para localizar a mensagem no seu banco. **edited\_text** `string` *required* Novo conteúdo da mensagem. É o mesmo valor que chega em `data.message`. **edit\_timestamp** `number` *required* Unix timestamp em milissegundos de quando a edição foi feita **decryption\_failed** `boolean` Presente e `true` quando não foi possível decifrar o novo conteúdo — acontece quando a mensagem editada é anterior à conexão da sessão. Nesse caso `edited_text` vem vazio. **protocol\_type** `number` Presente apenas em edições vindas de sincronização de histórico (sempre `14`). Edições em tempo real não trazem este campo. **original\_message\_key** `object` Referência bruta à mensagem original, presente apenas em edições vindas de histórico. Prefira `original_message_id`, que existe sempre. **PollUpdateData (type=poll\_update)** **poll\_creation\_message\_key** `object` *required* Referência à enquete original **vote** `object` *required* Dados criptografados do voto **ListResponseData (type=list\_response)** **selected\_row\_id** `string` *required* ID da opção selecionada **selected\_title** `string` *required* Título da opção selecionada **description** `string` Descrição da opção selecionada **list\_type** `number` *required* Tipo da lista **original\_list** `object` **Campos** **title** `string` Título da lista **options** `string[]` Opções disponíveis **TemplateButtonReplyData (type=template\_button\_reply)** **selected\_id** `string` *required* ID do botão selecionado **selected\_display\_text** `string` *required* Texto do botão selecionado **selected\_index** `number` *required* Índice do botão (0-based) **quoted\_message\_id** `string` *required* ID da mensagem com os botões **ListData (type=list)** **title** `string` *required* Título da lista **description** `string` Descrição/corpo da mensagem **button\_text** `string` *required* Texto do botão para abrir a lista **footer\_text** `string` Texto do rodapé **list\_type** `number` *required* Tipo da lista **sections** `array` *required* **Section** **title** `string` Título da seção **rows** `array` **Row** **row\_id** `string` ID da opção **title** `string` Título da opção **description** `string` Descrição da opção **CarouselData (type=carousel)** **type** `string` *required* Sempre `"carousel"` **cards** `array` *required* **Card** **header\_title** `string` Título do card **body** `string` Corpo do card **NativeFlowData (type=nativeflow)** **type** `string` *required* Sempre `"nativeflow"` **header\_title** `string` Título do header **header\_subtitle** `string` Subtítulo do header **header\_has\_media\_attachment** `boolean` Se tem mídia anexada **body** `string` Corpo da mensagem **footer** `string` Texto do rodapé **buttons** `array` *required* **Button** **name** `string` `quick_reply` | `cta_url` **params\_json** `string` JSON com parâmetros do botão **context\_info** `object` Presente em respostas e mensagens CTWA **Campos de context\_info** **stanza\_id** `string` ID da mensagem citada **quoted\_message\_id** `string` ID da mensagem citada **quoted\_message** `object` **Campos** **body** `string` Conteúdo da mensagem citada **type** `string` Tipo da mensagem citada **participant** `string` Autor da mensagem citada **entry\_point\_conversion\_app** `string` App de origem CTWA (ex: `facebook`) **entry\_point\_conversion\_source** `string` Fonte CTWA (ex: `ctwa_ad`) **external\_ad\_reply** `object` Dados do anúncio (ver ExternalAdReply) **external\_ad\_reply** `object` Dados do anúncio CTWA (duplicado no root de data) **Campos de external\_ad\_reply** **body** `string` *required* Texto do anúncio **title** `string` *required* Título do anúncio **ctwa\_clid** `string` *required* Click ID para atribuição **source\_id** `string` *required* ID do anúncio **source\_type** `string` *required* Tipo (ex: `ad`) **source\_url** `string` *required* URL do anúncio **media\_type** `number | string` *required* Tipo de mídia. Na API não oficial vem numérico (`1` = imagem, `2` = vídeo); nas conexões de API Oficial (Cloud API) vem como `"image"` / `"video"`, exatamente como a Meta envia em `referral.media_type`. **media\_url** `string` *required* URL da mídia do anúncio **thumbnail\_url** `string` *required* URL da thumbnail *** ## Exemplos por Tipo > [accordion] text > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T22:51:32.601Z", > "traceId": "c17dee440402792623e3ad6d925cb000", > "data": { > "id": "AC9831DDA691236BA3CE4909A187B703", > "type": "text", > "message": "Olá!", > "timestamp": 1769295092000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "163896103039140@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "media_url": null > } > } > ``` > [accordion] image > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:08:46.618Z", > "traceId": "c303a70535496ac2ef475d1454e5091d", > "data": { > "id": "3EB0F61B5D1F94FAFCD306", > "type": "image", > "message": "", > "timestamp": 1769296125000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "78700997521528@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "width": 1179, > "height": 1127, > "caption": "", > "file_length": 108529, > "mimetype": "image/jpeg" > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/image/3EB0F61B5D1F94FAFCD306.jpg", > "body": "" > } > } > ``` > [accordion] video > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:09:25.997Z", > "traceId": "696a8af1fffc77be1da98883fbf47a18", > "data": { > "id": "3EB0611DADDC69F4FCE999", > "type": "video", > "message": "", > "timestamp": 1769296161000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "78700997521528@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "width": 2160, > "height": 3840, > "caption": "", > "duration": 9, > "file_length": 15033300, > "mimetype": "video/mp4" > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/video/3EB0611DADDC69F4FCE999.mp4", > "body": "" > } > } > ``` > [accordion] audio > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:07:23.963Z", > "traceId": "57b56b9da28101ef39a2bbacb02bf79e", > "data": { > "id": "3EB04F2EA624ED5AE5E994", > "type": "audio", > "message": "Audio message", > "timestamp": 1769296042000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "78700997521528@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "is_ptt": true, > "duration": 1, > "file_length": 3228, > "mimetype": "audio/ogg; codecs=opus" > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/audio/3EB04F2EA624ED5AE5E994.ogg" > } > } > ``` > [accordion] document > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T22:52:36.560Z", > "traceId": "f52c470bc7e83b615fe02f7ae6de99a4", > "data": { > "id": "AC4E4E0D20923933E79133FED55E86FA", > "type": "document", > "message": "", > "timestamp": 1769295155000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "163896103039140@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "caption": "", > "filename": "contrato.pdf", > "file_length": 561909, > "mimetype": "application/pdf" > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/application/AC4E4E0D20923933E79133FED55E86FA.pdf", > "body": "" > } > } > ``` > [accordion] sticker > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:25:41.529Z", > "traceId": "0cc5f31ce4eeba9d93b69c644047d132", > "data": { > "id": "3EB07121F4AA1FECE1EB77", > "type": "sticker", > "message": "Sticker", > "timestamp": 1769297140000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "78700997521528@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "width": 0, > "height": 0, > "file_length": 31670, > "mimetype": "image/webp", > "is_animated": false > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/image/3EB07121F4AA1FECE1EB77.webp" > } > } > ``` > [accordion] contact > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:07:52.683Z", > "traceId": "5e2ce9f64316e43de9f9be26bc883cc6", > "data": { > "id": "3EB0E400D2D23FCC5F62", > "type": "contact", > "message": "Contact: João Silva", > "timestamp": 1769296072000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "78700997521528@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "data": { > "contact_name": "João Silva", > "contact_phone": "5511988887777", > "display_name": "João Silva", > "vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Silva;João;;;\nFN:João Silva\nTEL;type=CELL;waid=5511988887777:+55 11 98888-7777\nEND:VCARD" > }, > "media_url": null > } > } > ``` > [accordion] location > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:14:40.667Z", > "traceId": "9acf700c9a579d390acfaabcd47d813a", > "data": { > "id": "2A3245D5D360B969BC24", > "type": "location", > "message": "Location: -23.550520, -46.633308", > "timestamp": 1769296480000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "78700997521528@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "data": { > "degrees_latitude": -23.550520, > "degrees_longitude": -46.633308, > "name": "", > "address": "", > "thumbnail": "/9j/4AAQSkZJRgABAQAA..." > }, > "media_url": null > } > } > ``` > [accordion] reaction > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:22:59.675Z", > "traceId": "902f8bc16e32af74bca7b23c1696377f", > "data": { > "id": "3EB0798CB87F57E7E8FDEE", > "type": "reaction", > "message": "👍", > "timestamp": 1769296979000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "78700997521528@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "data": { > "original_message_id": "2A3245D5D360B969BC24", > "reaction_text": "👍", > "reaction_timestamp": 1769296978000, > "target_participant": "" > }, > "media_url": null > } > } > ``` > [accordion] edited\_message > > Quando alguém edita uma mensagem já enviada, o WhatsApp não atualiza a mensagem > original: ele envia um novo evento. Por isso a edição chega como um > `messages.received` comum, com `type: "edited_message"`. > > `data.id` é o ID **do evento de edição**. A mensagem que foi editada está em > `data.data.original_message_id` — é por ele que você atualiza o registro no seu > banco. > > Edições de legenda de mídia (imagem, vídeo, documento) também chegam por aqui, > com a legenda nova em `message`. > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:24:11.204Z", > "traceId": "5c1f7b90a4d2ee318f6b0c47d9a1e2f3", > "data": { > "id": "3EB0C7A91F4D2E88B103AA", > "type": "edited_message", > "message": "Reunião às 15h (corrigido)", > "timestamp": 1769297051000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "78700997521528@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "data": { > "edited_text": "Reunião às 15h (corrigido)", > "original_message_id": "2A3245D5D360B969BC24", > "edit_timestamp": 1769297051000 > }, > "media_url": null > } > } > ``` > [accordion] Resposta (quoted message) > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:24:49.030Z", > "traceId": "9cece6b5f07ce817f862c4d5c973081f", > "data": { > "id": "3EB0957D85886312C6D1AF", > "type": "text", > "message": "Sim, confirmo!", > "timestamp": 1769297088000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "78700997521528@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "context_info": { > "participant": "145453781897334@lid", > "stanza_id": "3EB056EB4B9E27BA4AA356", > "quoted_message_id": "3EB056EB4B9E27BA4AA356", > "quoted_message": { > "body": "Você confirma o pedido?", > "type": "text" > } > }, > "media_url": null > } > } > ``` > [accordion] CTWA (Click to WhatsApp Ads) > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T21:58:50.581Z", > "traceId": "c6dd8822b3949cd97d9247775ee779c2", > "data": { > "id": "AC73BAB4948202189805FABAF691A878", > "type": "text", > "message": "Olá, vi o anúncio e gostaria de mais informações.", > "timestamp": 1769255953000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "67237780156470@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "context_info": { > "entry_point_conversion_app": "facebook", > "entry_point_conversion_source": "ctwa_ad", > "external_ad_reply": { > "body": "Texto do anúncio que o usuário viu", > "ctwa_clid": "AffEzn5xEXlKpHmH8uQxUUPR7EIGYRQAt9mGNf6MOUkcOk-Da-5Uej76qNm7vWqEG-zW5otYD_SJ2uGg7nwmeOIGMccQhfsFSryba4VJ6YzxfwYBc0oQwe3f59tjool8tKcmhTx-Ag", > "media_type": 2, > "media_url": "https://www.facebook.com/reel/863712683259771/", > "render_larger_thumbnail": true, > "show_ad_attribution": true, > "source_id": "120237659567410455", > "source_type": "ad", > "source_url": "https://fb.me/6LTWcWnZ8", > "thumbnail_url": "https://scontent.xx.fbcdn.net/...", > "title": "Título do anúncio" > } > }, > "external_ad_reply": { > "body": "Texto do anúncio que o usuário viu", > "ctwa_clid": "AffEzn5xEXlKpHmH8uQxUUPR7EIGYRQAt9mGNf6MOUkcOk-Da-5Uej76qNm7vWqEG-zW5otYD_SJ2uGg7nwmeOIGMccQhfsFSryba4VJ6YzxfwYBc0oQwe3f59tjool8tKcmhTx-Ag", > "media_type": 2, > "media_url": "https://www.facebook.com/reel/863712683259771/", > "render_larger_thumbnail": true, > "show_ad_attribution": true, > "source_id": "120237659567410455", > "source_type": "ad", > "source_url": "https://fb.me/6LTWcWnZ8", > "thumbnail_url": "https://scontent.xx.fbcdn.net/...", > "title": "Título do anúncio" > }, > "media_url": null > } > } > ``` > [accordion] list\_response > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-25T17:13:05.199Z", > "traceId": "c636ed01bbc3b58174997b7379841e31", > "data": { > "id": "3EB00E07AFE6175651FCE9", > "type": "list_response", > "message": "Sim", > "timestamp": 1769361184000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "context_info": { > "participant": "5551920018823@s.whatsapp.net", > "quoted_message": { > "body": "", > "type": "unsupported" > }, > "quoted_message_id": "3EB0180F79608C5E1ACEE7", > "stanza_id": "3EB0180F79608C5E1ACEE7" > }, > "data": { > "selected_row_id": "t1", > "selected_title": "Sim", > "description": "aham", > "list_type": 1, > "original_list": { > "title": "Teste", > "options": ["Sim"] > } > }, > "media_url": null > } > } > ``` > [accordion] template\_button\_reply > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-25T17:11:35.713Z", > "traceId": "f60da86820a5e9a776df323b339ce92b", > "data": { > "id": "3EB00B49BF1006ED22FFE2", > "type": "template_button_reply", > "message": "Confirmar", > "timestamp": 1769361095000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "data": { > "quoted_message_id": "3EB0319B37B762E820E8AC", > "selected_display_text": "Confirmar", > "selected_id": "btn_confirm", > "selected_index": 0 > }, > "media_url": null > } > } > ``` > [accordion] list > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-25T20:15:06.493Z", > "traceId": "5458c3c3605f3d5dee7076349890912d", > "data": { > "id": "3EB0B74CA34A5FC973F4C2", > "type": "list", > "message": "mensagem aqui", > "timestamp": 1769372106000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "224901986312214@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "data": { > "title": "Teste", > "description": "mensagem aqui", > "button_text": "Abrir", > "footer_text": "", > "list_type": 1, > "sections": [ > { > "title": "Teste", > "rows": [ > { > "row_id": "t1", > "title": "Sim", > "description": "aham" > } > ] > } > ] > }, > "media_url": null > } > } > ``` > [accordion] carousel > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-25T20:15:09.153Z", > "traceId": "44663f6360711dc8e6788b6772c2efa9", > "data": { > "id": "3EB024449A497D01E1DB93", > "type": "carousel", > "message": "", > "timestamp": 1769372108000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "224901986312214@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "data": { > "type": "carousel", > "cards": [ > { > "header_title": "", > "body": "Teste" > } > ] > }, > "media_url": null, > "body": "" > } > } > ``` > [accordion] nativeflow (quick\_reply) > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-25T20:15:12.493Z", > "traceId": "e53bbcc4cf1b479082617887d8424343", > "data": { > "id": "3EB0C41EA80CCF889B8E52", > "type": "nativeflow", > "message": "Corpo da mensagem", > "timestamp": 1769372112000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "224901986312214@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "data": { > "type": "nativeflow", > "header_title": "Título", > "header_subtitle": "", > "header_has_media_attachment": false, > "body": "Corpo da mensagem", > "footer": "Rodapé", > "buttons": [ > { > "name": "quick_reply", > "params_json": "{\"display_text\":\"Confirmar\",\"id\":\"btn_confirm\"}" > } > ] > }, > "media_url": null > } > } > ``` > [accordion] nativeflow (cta\_url) > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-25T20:15:10.945Z", > "traceId": "02858caf7cd7f62f347f10f2c1ad13bf", > "data": { > "id": "3EB04C63B7280B8146BC50", > "type": "nativeflow", > "message": "Corpo da mensagem", > "timestamp": 1769372110000, > "fromMe": false, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "lid": "224901986312214@lid", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "data": { > "type": "nativeflow", > "header_title": "Título", > "header_subtitle": "", > "header_has_media_attachment": false, > "body": "Corpo da mensagem", > "footer": "Rodapé", > "buttons": [ > { > "name": "cta_url", > "params_json": "{\"display_text\":\"Abrir site\",\"url\":\"https://exemplo.com\",\"merchant_url\":\"https://exemplo.com\"}" > } > ] > }, > "media_url": null > } > } > ``` > [accordion] Mensagem enviada pelo próprio celular (fromMe: true) > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T22:55:00.000Z", > "traceId": "c17dee440402792623e3ad6d925cb222", > "data": { > "id": "3EB0A1B2C3D4E5F60718", > "type": "text", > "message": "Já estou a caminho!", > "timestamp": 1769295300000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "media_url": null > } > } > ``` > [accordion] Mensagem de grupo (is\_group: true) > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:30:10.120Z", > "traceId": "b91f0a2d6c4e5f7081923a4b5c6d7e8f", > "data": { > "id": "3EB0D2E3F4A5B6C70819", > "type": "text", > "message": "Bom dia, pessoal!", > "timestamp": 1769297410000, > "fromMe": false, > "isMetaAI": false, > "is_group": true, > "group_name": "Equipe de Vendas", > "participant": "5511999999999@s.whatsapp.net", > "from": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "from_name": "João", > "to": { > "jid": "120363012345678901@g.us", > "name": "Equipe de Vendas" > }, > "media_url": null > } > } > ``` > [accordion] Mensagem escrita pela Meta AI do contato (isMetaAI: true) > > ```json theme={null} > { > "event": "messages.received", > "sessionId": "my-session", > "timestamp": "2026-11-05T14:20:05.310Z", > "traceId": "4f2a9c1e7b3d5a6c8e0f1a2b3c4d5e6f", > "data": { > "id": "3EB0CE65A1B2C3D4E5F6", > "type": "text", > "message": "Olá! Sou a assistente virtual da Loja Exemplo. Nosso horário é de segunda a sexta, das 9h às 18h.", > "timestamp": 1793974805000, > "fromMe": false, > "isMetaAI": true, > "is_group": false, > "group_name": "", > "from": { > "jid": "5511988887777@s.whatsapp.net", > "lid": "163896103039141@lid", > "name": "Loja Exemplo" > }, > "from_name": "Loja Exemplo", > "to": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "media_url": null > } > } > ``` *** ## Identificando Tipos | Condição | Tipo | | - | - | | `data.type === "text"` | Mensagem de texto | | `data.type === "image"` | Imagem | | `data.type === "video"` | Vídeo | | `data.type === "audio"` | Áudio/PTT | | `data.type === "document"` | Documento | | `data.type === "sticker"` | Sticker | | `data.type === "contact"` | Contato | | `data.type === "location"` | Localização | | `data.type === "reaction"` | Reação | | `data.type === "poll_update"` | Atualização de enquete | | `data.type === "list_response"` | Resposta de lista interativa | | `data.type === "template_button_reply"` | Clique em botão | | `data.type === "list"` | Mensagem de lista interativa | | `data.type === "carousel"` | Carrossel de cards | | `data.type === "nativeflow"` | Mensagem com botões (quick\_reply/cta\_url) | | `data.context_info?.quoted_message` | É resposta | | `data.context_info?.entry_point_conversion_source === "ctwa_ad"` | Veio de anúncio | | `data.isMetaAI === true` | Escrita pela Meta AI do contato | *** ## Media URLs Arquivos de mídia são automaticamente salvos no S3 e disponibilizados em `data.media_url`. | Tipo | Extensão | Exemplo | | - | - | - | | image | .jpg, .png | `https://s3.../image/{id}.jpg` | | video | .mp4 | `https://s3.../video/{id}.mp4` | | audio | .ogg | `https://s3.../audio/{id}.ogg` | | document | .pdf, .docx | `https://s3.../application/{id}.pdf` | | sticker | .webp | `https://s3.../image/{id}.webp` | # Evento messages.sent Source: https://docs.d-api.cloud/whatsapp/webhooks/messages-sent Disparado quando uma mensagem é enviada via API da D-API. ## Evento `messages.sent` > [!WARNING] > > O `messages.sent` é disparado **exclusivamente** para mensagens enviadas via > **API** da D-API (`/messages/send/*` e `/interactive/send/*`). Mensagens > enviadas pelo **próprio celular** ou por **outros dispositivos conectados** ao > mesmo número **não** geram `messages.sent` — elas chegam em > [`messages.received`](/whatsapp/webhooks/messages-received) com `fromMe: true`. Use este evento para confirmar que uma mensagem disparada pela API foi enviada com sucesso e para registrar o conteúdo final entregue ao WhatsApp. > [!NOTE] > > O payload tem **exatamente a mesma estrutura** do evento `messages.received` > para o mesmo `type` (mesmos campos, `media_data` com `file_length`/`mimetype`, > `context_info` etc.), apenas com `fromMe: true` e `isMetaAI: false`. Para a referência completa de > todos os campos, consulte a página de > [messages.received](/whatsapp/webhooks/messages-received). A diferença está nos papéis: `from` é o **seu** número (a sessão) e `to` é o destinatário. > [!NOTE] > > Quando a mídia é enviada por **URL externa**, o payload pode incluir > `pending_media_url` (a URL original informada na requisição) dentro de > `media_data`. Além disso, o `id` da mensagem pode vir > em **letras maiúsculas**. *** ## Exemplos por Tipo > [accordion] text > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-24T22:55:00.000Z", > "traceId": "c17dee440402792623e3ad6d925cb111", > "data": { > "id": "AC9831DDA691236BA3CE4909A187B703", > "type": "text", > "message": "Olá! Como posso ajudar?", > "timestamp": 1769295300000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "media_url": null > } > } > ``` > [accordion] image > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:08:46.618Z", > "traceId": "c303a70535496ac2ef475d1454e5091d", > "data": { > "id": "3EB0F61B5D1F94FAFCD306", > "type": "image", > "message": "", > "timestamp": 1769296125000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "width": 1179, > "height": 1127, > "caption": "", > "file_length": 108529, > "mimetype": "image/jpeg" > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/image/3EB0F61B5D1F94FAFCD306.jpg", > "body": "" > } > } > ``` > [accordion] video > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:09:25.997Z", > "traceId": "696a8af1fffc77be1da98883fbf47a18", > "data": { > "id": "3EB0611DADDC69F4FCE999", > "type": "video", > "message": "", > "timestamp": 1769296161000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "width": 2160, > "height": 3840, > "caption": "", > "duration": 9, > "file_length": 15033300, > "mimetype": "video/mp4" > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/video/3EB0611DADDC69F4FCE999.mp4", > "body": "" > } > } > ``` > [accordion] audio > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:07:23.963Z", > "traceId": "57b56b9da28101ef39a2bbacb02bf79e", > "data": { > "id": "3EB04F2EA624ED5AE5E994", > "type": "audio", > "message": "Audio message", > "timestamp": 1769296042000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "is_ptt": true, > "duration": 1, > "file_length": 3228, > "mimetype": "audio/ogg; codecs=opus" > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/audio/3EB04F2EA624ED5AE5E994.ogg" > } > } > ``` > [accordion] document > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-24T22:52:36.560Z", > "traceId": "f52c470bc7e83b615fe02f7ae6de99a4", > "data": { > "id": "AC4E4E0D20923933E79133FED55E86FA", > "type": "document", > "message": "", > "timestamp": 1769295155000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "caption": "", > "filename": "contrato.pdf", > "file_length": 561909, > "mimetype": "application/pdf" > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/application/AC4E4E0D20923933E79133FED55E86FA.pdf", > "body": "" > } > } > ``` > [accordion] sticker > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:25:41.529Z", > "traceId": "0cc5f31ce4eeba9d93b69c644047d132", > "data": { > "id": "3EB07121F4AA1FECE1EB77", > "type": "sticker", > "message": "Sticker", > "timestamp": 1769297140000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "media_data": { > "url": "https://mmg.whatsapp.net/...", > "width": 0, > "height": 0, > "file_length": 31670, > "mimetype": "image/webp", > "is_animated": false > }, > "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/image/3EB07121F4AA1FECE1EB77.webp" > } > } > ``` > [accordion] location > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:14:40.667Z", > "traceId": "9acf700c9a579d390acfaabcd47d813a", > "data": { > "id": "2A3245D5D360B969BC24", > "type": "location", > "message": "Location: -23.550520, -46.633308", > "timestamp": 1769296480000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "data": { > "degrees_latitude": -23.550520, > "degrees_longitude": -46.633308, > "name": "", > "address": "", > "thumbnail": "/9j/4AAQSkZJRgABAQAA..." > }, > "media_url": null > } > } > ``` > [accordion] contact > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:07:52.683Z", > "traceId": "5e2ce9f64316e43de9f9be26bc883cc6", > "data": { > "id": "3EB0E400D2D23FCC5F62", > "type": "contact", > "message": "Contact: João Silva", > "timestamp": 1769296072000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "data": { > "contact_name": "João Silva", > "contact_phone": "5511988887777", > "display_name": "João Silva", > "vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Silva;João;;;\nFN:João Silva\nTEL;type=CELL;waid=5511988887777:+55 11 98888-7777\nEND:VCARD" > }, > "media_url": null > } > } > ``` > [accordion] reaction > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-24T23:22:59.675Z", > "traceId": "902f8bc16e32af74bca7b23c1696377f", > "data": { > "id": "3EB0798CB87F57E7E8FDEE", > "type": "reaction", > "message": "👍", > "timestamp": 1769296979000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "data": { > "original_message_id": "2A3245D5D360B969BC24", > "reaction_text": "👍", > "reaction_timestamp": 1769296978000, > "target_participant": "" > }, > "media_url": null > } > } > ``` > [accordion] list > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-25T20:15:06.493Z", > "traceId": "5458c3c3605f3d5dee7076349890912d", > "data": { > "id": "3EB0B74CA34A5FC973F4C2", > "type": "list", > "message": "mensagem aqui", > "timestamp": 1769372106000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "data": { > "title": "Teste", > "description": "mensagem aqui", > "button_text": "Abrir", > "footer_text": "", > "list_type": 1, > "sections": [ > { > "title": "Teste", > "rows": [ > { > "row_id": "t1", > "title": "Sim", > "description": "aham" > } > ] > } > ] > }, > "media_url": null > } > } > ``` > [accordion] carousel > > ```json theme={null} > { > "event": "messages.sent", > "sessionId": "my-session", > "timestamp": "2026-01-25T20:15:09.153Z", > "traceId": "44663f6360711dc8e6788b6772c2efa9", > "data": { > "id": "3EB024449A497D01E1DB93", > "type": "carousel", > "message": "", > "timestamp": 1769372108000, > "fromMe": true, > "isMetaAI": false, > "is_group": false, > "group_name": "", > "from": { > "jid": "558005915338@s.whatsapp.net", > "name": "Minha Empresa" > }, > "from_name": "Minha Empresa", > "to": { > "jid": "5511999999999@s.whatsapp.net", > "name": "João" > }, > "data": { > "type": "carousel", > "cards": [ > { > "header_title": "", > "body": "Teste" > } > ] > }, > "media_url": null, > "body": "" > } > } > ``` *** ## Outros tipos enviáveis Os tipos abaixo também podem ser enviados pela API. O formato exato do payload de `messages.sent` para esses tipos **não está documentado aqui** para evitar exemplos incorretos — quando enviados, o webhook segue a mesma estrutura do [`messages.received`](/whatsapp/webhooks/messages-received) correspondente, com `fromMe: true`. | Tipo | Endpoint | | - | - | | poll | `POST /messages/send/poll` | | album | `POST /messages/send/album` | | nativeflow | `POST /interactive/send/nativeflow` | > [!NOTE] > > Enquetes (`poll`) são reportadas em `messages.received` como `poll_update` > (votos). O **álbum** envia múltiplas mídias e pode gerar mais de um evento de > mídia individual (`image`/`video`). Confirme o formato em ambiente de teste > antes de tratar esses tipos em produção. *** ## Endpoints de envio Cada tipo enviável corresponde a um endpoint da API: | Tipo | Endpoint | | - | - | | text | `POST /messages/send/text` | | image | `POST /messages/send/image` | | video | `POST /messages/send/video` | | audio | `POST /messages/send/audio` | | document | `POST /messages/send/document` | | sticker | `POST /messages/send/sticker` | | location | `POST /messages/send/location` | | contact | `POST /messages/send/contact` | | poll | `POST /messages/send/poll` | | reaction | `POST /messages/send/reaction` | | album | `POST /messages/send/album` | | list | `POST /interactive/send/list` | | carousel | `POST /interactive/send/carousel` | | nativeflow | `POST /interactive/send/nativeflow` | > [!WARNING] > > Evite usar `messages.sent` para acionar automações de resposta automática. > Como ele confirma mensagens que **você mesmo** enviou pela API, tratá-lo como > gatilho de resposta pode gerar loops. # Status de mensagens Source: https://docs.d-api.cloud/whatsapp/webhooks/status-de-mensagens Eventos de leitura, entrega e exclusão de mensagens. Estes eventos notificam mudanças no **ciclo de vida** de uma mensagem após o envio: quando ela é **entregue**, **lida** ou **apagada**. Todos seguem o [envelope comum](/whatsapp/webhooks/visao-geral) — o conteúdo específico fica em `data`. Edição de mensagem **não** aparece aqui: ela chega como uma mensagem normal em [`messages.received`](/whatsapp/webhooks/messages-received), com `type: "edited_message"`. ## `message.delivered` e `message.read` `message.delivered` é disparado quando uma mensagem é **entregue** ao destinatário; `message.read` quando ela é **lida**. Os dois eventos têm exatamente o **mesmo formato** de `data`. ```json theme={null} { "event": "message.read", "sessionId": "my-session", "timestamp": "2026-01-24T23:00:00.000Z", "data": { "message_id": "3EB0F61B5D1F94FAFCD306", "remote_jid": "5511999999999@s.whatsapp.net", "participant": "", "timestamp": 1769295600000 } } ``` **message\_id** `string` *required* ID da mensagem cujo status mudou. **remote\_jid** `string` *required* JID do chat (contato ou grupo) onde a mensagem está. **participant** `string` JID do participante que confirmou a entrega/leitura. Só é preenchido em **grupos**; em conversas individuais vem como string vazia (`""`). **timestamp** `number` *required* Momento do evento em milissegundos (epoch). > [!NOTE] > > `message.delivered` e `message.read` passam por **deduplicação de 30 segundos** > por `message_id`: confirmações repetidas do mesmo status dentro dessa janela > não geram webhooks duplicados. ## `message.deleted` Disparado quando uma mensagem é **apagada** (revogada). ```json theme={null} { "event": "message.deleted", "sessionId": "my-session", "timestamp": "2026-01-24T23:01:00.000Z", "data": { "message_id": "3EB0F61B5D1F94FAFCD306", "chat_jid": "5511999999999@s.whatsapp.net", "sender_jid": "5511999999999@s.whatsapp.net", "is_from_me": false, "timestamp": 1769295660000 } } ``` **message\_id** `string` *required* ID da mensagem apagada. **chat\_jid** `string` *required* JID do chat onde a mensagem estava. **sender\_jid** `string` *required* JID de quem enviou a mensagem original. **is\_from\_me** `boolean` *required* `true` quando a mensagem apagada foi enviada pela própria sessão. **timestamp** `number` *required* Momento da exclusão em milissegundos (epoch). ## `message.update` > [!WARNING] > > **Este evento não é disparado.** Edições de mensagem chegam pelo evento > [`messages.received`](/whatsapp/webhooks/messages-received) com > `type: "edited_message"` — veja o exemplo `edited_message` naquela página. > O formato abaixo permanece documentado apenas para quem já tinha o > `message.update` configurado; ele nunca é enviado. ```json theme={null} { "event": "message.update", "sessionId": "my-session", "timestamp": "2026-01-24T23:02:00.000Z", "data": { "message_id": "3EB0F61B5D1F94FAFCD306", "chat_jid": "5511999999999@s.whatsapp.net", "sender_jid": "5511999999999@s.whatsapp.net", "is_from_me": false, "new_text": "Texto corrigido", "timestamp": 1769295720000, "edit_timestamp": 1769295725000 } } ``` **message\_id** `string` *required* ID da mensagem editada. **chat\_jid** `string` *required* JID do chat onde a mensagem está. **sender\_jid** `string` *required* JID de quem enviou a mensagem. **is\_from\_me** `boolean` *required* `true` quando a mensagem editada foi enviada pela própria sessão. **new\_text** `string` *required* Novo conteúdo da mensagem após a edição. **timestamp** `number` *required* Momento da mensagem original em milissegundos (epoch). **edit\_timestamp** `number` *required* Momento da edição em milissegundos (epoch). # Visão geral dos webhooks Source: https://docs.d-api.cloud/whatsapp/webhooks/visao-geral Como configurar, receber e processar os eventos de uma sessão WhatsApp. Os webhooks notificam seu sistema em tempo real sobre o que acontece em cada **sessão** do WhatsApp não oficial: mensagens recebidas e enviadas, mudanças de status, eventos de conexão, atualizações de chats/contatos e movimentações em grupos. ## Configuração por sessão Cada sessão tem sua própria configuração de webhooks, com dois modos de entrega: > [accordion] single — uma única URL para todos os eventos > > Todos os eventos **habilitados** da sessão são enviados para a mesma URL. > Útil quando um único endpoint concentra o processamento. > [accordion] per\_event — uma URL por evento > > Cada evento tem sua própria `webhookUrl`, permitindo rotear eventos > diferentes para endpoints diferentes. Independente do modo, cada evento possui: **enabled** `boolean` Liga ou desliga o envio do evento. Eventos **desabilitados não são enviados**. **webhookUrl** `string` URL de destino do evento (no modo `per_event`) ou herdada da configuração única (no modo `single`). ## Envelope comum Todo webhook chega com o mesmo envelope. O conteúdo específico de cada evento fica em `data`. ```json theme={null} { "event": "messages.received", "sessionId": "my-session", "data": { "...": "específico do evento" }, "timestamp": "2026-01-24T22:51:32.601Z", "traceId": "c17dee440402792623e3ad6d925cb000" } ``` **event** `string` *required* Nome do evento (ex: `messages.received`). **sessionId** `string` *required* ID da sessão que originou o evento. **data** `object` *required* Conteúdo específico do evento. Veja a página de cada evento. **timestamp** `string` *required* Data e hora do envio em ISO 8601 (UTC). **traceId** `string` Identificador para rastreamento ponta a ponta. Útil em logs e suporte. ## Headers | Header | Valor | | - | - | | `Content-Type` | `application/json` | | `User-Agent` | `Deliverify-Webhook/1.0` | > [!NOTE] > > Este produto **não** envia assinatura HMAC nos webhooks. Para restringir a > origem, recomendamos usar uma URL secreta (com token no path) e/ou validar o > `User-Agent` e o `sessionId` esperado. ## Entrega e confiabilidade > [accordion] Retentativas (7 tentativas, backoff exponencial) > > Em caso de falha, a entrega é repetida até **7 vezes** com backoff > exponencial: aproximadamente **5s, 10s, 20s, 40s, 80s e 160s** entre as > tentativas. > [accordion] Falhas permanentes (404 / 410) > > Respostas HTTP **404** ou **410** são tratadas como **falha permanente**: a > entrega não é mais retentada para aquela URL. > [accordion] Timeout > > Cada tentativa tem timeout de **30 segundos**. Endpoints lentos podem ser > considerados falha e entrar em retentativa. > [accordion] Circuit breaker > > Há um **circuit breaker por URL**: URLs que falham repetidamente são > temporariamente interrompidas para evitar sobrecarga. > [accordion] Deduplicação > > Eventos passam por **deduplicação via Redis** (TTL de 5 minutos), reduzindo > entregas duplicadas do mesmo evento em curto intervalo. > [!WARNING] > > Responda rapidamente com um status **2xx**. Faça o processamento pesado de > forma assíncrona (fila/worker) e confirme o recebimento o quanto antes para > evitar timeouts (30s) e retentativas desnecessárias. ## Eventos disponíveis | Evento | Descrição | Página | | - | - | - | | `messages.received` | Mensagem recebida | [messages.received](/whatsapp/webhooks/messages-received) | | `messages.sent` | Mensagem enviada pela sessão | [messages.sent](/whatsapp/webhooks/messages-sent) | | `message.read` | Mensagem lida | [Status de mensagens](/whatsapp/webhooks/status-de-mensagens) | | `message.delivered` | Mensagem entregue | [Status de mensagens](/whatsapp/webhooks/status-de-mensagens) | | `message.deleted` | Mensagem apagada | [Status de mensagens](/whatsapp/webhooks/status-de-mensagens) | | `message.update` | Não disparado — edições chegam em `messages.received` com `type: "edited_message"` | [Status de mensagens](/whatsapp/webhooks/status-de-mensagens) | | `session.created` | Conexão da API Oficial provisionada pelo connect hospedado | [Conexão](/whatsapp/webhooks/conexao) | | `connection.qrcode` | QR code gerado | [Conexão](/whatsapp/webhooks/conexao) | | `connection.paircode` | Código de pareamento gerado | [Conexão](/whatsapp/webhooks/conexao) | | `connection.status` | Mudança de status da conexão | [Conexão](/whatsapp/webhooks/conexao) | | `logged_out` | Sessão deslogada | [Conexão](/whatsapp/webhooks/conexao) | | `chats.update` | Atualização de chat | [Chats, contatos e presença](/whatsapp/webhooks/chats-contatos-presenca) | | `chats.upsert` | Chat criado/atualizado | [Chats, contatos e presença](/whatsapp/webhooks/chats-contatos-presenca) | | `contacts.update` | Atualização de contato | [Chats, contatos e presença](/whatsapp/webhooks/chats-contatos-presenca) | | `contacts.upsert` | Contato criado/atualizado | [Chats, contatos e presença](/whatsapp/webhooks/chats-contatos-presenca) | | `presence` | Presença (online/digitando) | [Chats, contatos e presença](/whatsapp/webhooks/chats-contatos-presenca) | | `groups_participants.join` | Entrada em grupo | [Grupos](/whatsapp/webhooks/grupos) | | `groups_participants.leave` | Saída de grupo | [Grupos](/whatsapp/webhooks/grupos) | | `groups_participants.promote` | Promoção a admin | [Grupos](/whatsapp/webhooks/grupos) | | `groups_participants.demote` | Rebaixamento de admin | [Grupos](/whatsapp/webhooks/grupos) | | `group_participants.join-request` | Solicitação de entrada | [Grupos](/whatsapp/webhooks/grupos) | | `group_participants.join-request.revoked` | Solicitação revogada | [Grupos](/whatsapp/webhooks/grupos) | | `group_participants.join-request.approved` | Solicitação aprovada | [Grupos](/whatsapp/webhooks/grupos) | | `labels.edit` | Etiqueta criada/editada/excluída | [Etiquetas](/whatsapp/webhooks/etiquetas) | | `labels.association.chat` | Etiqueta aplicada/removida de uma conversa | [Etiquetas](/whatsapp/webhooks/etiquetas) | | `labels.association.message` | Etiqueta aplicada/removida de uma mensagem | [Etiquetas](/whatsapp/webhooks/etiquetas) | | `call.offer` | Chamada de voz recebida | [Chamadas (VoIP)](/whatsapp/webhooks/chamadas) | | `call.accepted` | Chamada de entrada atendida | [Chamadas (VoIP)](/whatsapp/webhooks/chamadas) | | `call.rejected` | Chamada de entrada rejeitada | [Chamadas (VoIP)](/whatsapp/webhooks/chamadas) | | `call.ringing` | Chamada de saída tocando | [Chamadas (VoIP)](/whatsapp/webhooks/chamadas) | | `call.connected` | Chamada de saída conectada | [Chamadas (VoIP)](/whatsapp/webhooks/chamadas) | | `call.ended` | Chamada de saída encerrada | [Chamadas (VoIP)](/whatsapp/webhooks/chamadas) | | `call.audio` | Áudio da chamada (chunks ou gravação) | [Chamadas (VoIP)](/whatsapp/webhooks/chamadas) | | `history.message.upsert` | Mensagem do histórico (apenas RabbitMQ) | [Histórico e sincronização](/whatsapp/webhooks/historico-e-sincronizacao) | | `history.message.received` | Mensagem recebida do histórico (apenas RabbitMQ) | [Histórico e sincronização](/whatsapp/webhooks/historico-e-sincronizacao) | | `history.messages.sent` | Mensagem enviada do histórico (convertida no webhook) | [Histórico e sincronização](/whatsapp/webhooks/historico-e-sincronizacao) | | `history_sync` | Conclusão/resumo do backfill | [Histórico e sincronização](/whatsapp/webhooks/historico-e-sincronizacao) | | `appstate.agent.update` | Dispositivo/agente vinculado atualizado | [Histórico e sincronização](/whatsapp/webhooks/historico-e-sincronizacao) | # Consultar limites da conta Source: https://docs.d-api.cloud/api-reference/account/consultar-limites-da-conta /api-reference/openapi.json get /api/v1/limits/{sessionId} Retorna informações sobre as cotas de mensagens e as restrições da conta (reachout timelock). # Disparar chamada do agente (URL pública do gatilho) Source: https://docs.d-api.cloud/api-reference/agentes-de-voz-—-gatilhos/disparar-chamada-do-agente-url-pública-do-gatilho /api-reference/openapi.json post /api/v1/hooks/va/{token} Público por design: o token da URL é a credencial (sem API key). Crie o gatilho no painel. Corpo JSON (até 16 KB): `phone` (com DDI; número BR sem DDI recebe 55), `sessionId` opcional (padrão do gatilho), `variables` opcional (só as variáveis declaradas no agente; até 30, valores até 500 caracteres). Também aceita chaves planas `"variables.": valor` no topo (o objeto `variables` prevalece em conflito). Assinatura (quando o gatilho exige): `X-DAPI-Signature: t=,v1=`, tolerância de 300 s. `Idempotency-Key` (até 128): repetições em 24 h recebem a mesma resposta. Sem ela, o mesmo telefone + variáveis em 60 s também. Fora da janela de horário do gatilho a chamada é agendada para a próxima abertura (`status: "scheduled"`). Erros: 404 `not_found`, 423 `trigger_paused`, 401 `invalid_signature`, 400 `invalid_input`/`missing_variables`, 403 `session_not_allowed`/`country_not_allowed`, 409 `agent_not_published`/`request_in_progress`, 402 `insufficient_balance`/`daily_cap_reached`, 413 `payload_too_large`, 429 `rate_limited` (com `retryAfterSec` e Retry-After)/`queue_full`. # Detalhar chamada Source: https://docs.d-api.cloud/api-reference/agentes-de-voz/detalhar-chamada /api-reference/openapi.json get /api/v1/voice-agent-calls/{callId} # Transcrição da chamada (paginada) Source: https://docs.d-api.cloud/api-reference/agentes-de-voz/transcrição-da-chamada-paginada /api-reference/openapi.json get /api/v1/voice-agent-calls/{callId}/turns # Atender chamada recebida Source: https://docs.d-api.cloud/api-reference/calls/atender-chamada-recebida /api-reference/openapi.json post /api/v1/calls/accept Atende uma chamada recebida do WhatsApp em modo stream ao vivo e retorna um WebSocket de mídia (wsUrl + token), no mesmo formato de POST /calls/stream. Conecte o WS para transmitir o áudio do microfone, ouvir quem ligou e receber os eventos do ciclo de vida da chamada. Use o `callId` do evento call.offer enquanto a chamada ainda está tocando. Indisponível em conexões cloud_api (API Oficial). # Consultar chamada gravada por id Source: https://docs.d-api.cloud/api-reference/calls/consultar-chamada-gravada-por-id /api-reference/openapi.json get /api/v1/calls/{callId} Retorna uma chamada persistida (metadados de gravação e transcrição, quando disponível) pelo call_id do dapi-go. Restrito aos dados do titular da API Key. # Consultar estado da chamada Source: https://docs.d-api.cloud/api-reference/calls/consultar-estado-da-chamada /api-reference/openapi.json post /api/v1/calls/state Retorna o estado atual da chamada no pod (idle | starting | calling | ringing | active | ending | ...). # Criar link de chamada do WhatsApp Source: https://docs.d-api.cloud/api-reference/calls/criar-link-de-chamada-do-whatsapp /api-reference/openapi.json post /api/v1/calls/create-link Cria um novo link de chamada do WhatsApp que pode ser compartilhado para chamadas de áudio ou vídeo. # Encerrar chamada de voz ativa Source: https://docs.d-api.cloud/api-reference/calls/encerrar-chamada-de-voz-ativa /api-reference/openapi.json post /api/v1/calls/end Desliga a chamada ativa. O evento call.ended é assíncrono; este comando apenas dispara o desligamento. # Enviar mensagem de chamada agendada Source: https://docs.d-api.cloud/api-reference/calls/enviar-mensagem-de-chamada-agendada /api-reference/openapi.json post /api/v1/calls/send-event Envia uma mensagem de chamada ou evento agendado para um destinatário. Pode criar um link de chamada do WhatsApp ou usar uma URL própria (Zoom, Meet, etc.). # Iniciar chamada de voz Source: https://docs.d-api.cloud/api-reference/calls/iniciar-chamada-de-voz /api-reference/openapi.json post /api/v1/calls/place Inicia uma chamada de voz 1:1 de saída. Responde imediatamente com o callId (estado "calling"); toque, atendimento e desligamento chegam como eventos de webhook call.*. # Iniciar chamada de voz ao vivo (stream) Source: https://docs.d-api.cloud/api-reference/calls/iniciar-chamada-de-voz-ao-vivo-stream /api-reference/openapi.json post /api/v1/calls/stream Inicia uma chamada 1:1 de saída em modo stream ao vivo e retorna um WebSocket de mídia (wsUrl + token). Conecte o WS para transmitir o áudio do microfone, ouvir o outro lado e receber os eventos do ciclo de vida da chamada. Toda chamada é sempre gravada: um WAV estéreo (microfone/interlocutor) é enviado ao fim da chamada e a URL chega como evento final {type:'recording'} no WS. O campo legado record é aceito, mas ignorado. # Listar chamadas gravadas Source: https://docs.d-api.cloud/api-reference/calls/listar-chamadas-gravadas /api-reference/openapi.json get /api/v1/calls/ Lista as chamadas ao vivo (stream) persistidas com os metadados de gravação, das mais recentes para as mais antigas. Restrito aos dados do titular da API Key. Suporta paginação (page, limit — máximo 100) e os filtros opcionais sessionId, phone e recordingStatus (uploaded | empty | failed). # Recusar chamada recebida Source: https://docs.d-api.cloud/api-reference/calls/recusar-chamada-recebida /api-reference/openapi.json post /api/v1/calls/reject Recusa uma chamada recebida do WhatsApp. O campo `from` é o JID de quem ligou exatamente como o evento call.offer informou (pode ser um LID). O evento call.rejected resultante é assíncrono. Indisponível em conexões cloud_api (API Oficial). # Silenciar ou reativar o áudio da chamada Source: https://docs.d-api.cloud/api-reference/calls/silenciar-ou-reativar-o-áudio-da-chamada /api-reference/openapi.json post /api/v1/calls/mute Silencia (muted=true) ou reativa (muted=false) o áudio enviado na chamada ativa. # Buscar produto por ID Source: https://docs.d-api.cloud/api-reference/catálogo/buscar-produto-por-id /api-reference/openapi.json post /api/v1/catalog/product/get Busca um produto único do catálogo via catalog_product_get. # Criar coleção Source: https://docs.d-api.cloud/api-reference/catálogo/criar-coleção /api-reference/openapi.json post /api/v1/catalog/collection/create Cria uma coleção no catálogo via catalog_collection_create. product_ids opcionalmente já popula a coleção. # Criar produto Source: https://docs.d-api.cloud/api-reference/catálogo/criar-produto /api-reference/openapi.json post /api/v1/catalog/product/create Cria um produto no catálogo business. price/sale_price são decimais (199.90 = R$ 199,90); o backend converte pra unidades × 1000 antes de enviar ao bridge. is_hidden oculta o produto da vitrine (default false). # Editar coleção Source: https://docs.d-api.cloud/api-reference/catálogo/editar-coleção /api-reference/openapi.json post /api/v1/catalog/collection/edit Edita uma coleção. Quando product_ids é enviado, substitui integralmente os membros da coleção (não é append). # Editar produto Source: https://docs.d-api.cloud/api-reference/catálogo/editar-produto /api-reference/openapi.json post /api/v1/catalog/product/edit Edita campos de um produto existente (patch — campos ausentes mantêm o valor atual). price/sale_price são decimais; envie sale_price=0 para remover a promoção. is_hidden alterna visibilidade. # Excluir coleção Source: https://docs.d-api.cloud/api-reference/catálogo/excluir-coleção /api-reference/openapi.json post /api/v1/catalog/collection/delete Remove uma coleção do catálogo via catalog_collection_delete. Os produtos em si não são removidos. # Excluir produto Source: https://docs.d-api.cloud/api-reference/catálogo/excluir-produto /api-reference/openapi.json post /api/v1/catalog/product/delete Remove um produto do catálogo via catalog_product_delete. # Listar coleções do catálogo Source: https://docs.d-api.cloud/api-reference/catálogo/listar-coleções-do-catálogo /api-reference/openapi.json post /api/v1/catalog/collections/list Lista coleções do catálogo via comando catalog_collections_list. # Listar produtos do catálogo Source: https://docs.d-api.cloud/api-reference/catálogo/listar-produtos-do-catálogo /api-reference/openapi.json post /api/v1/catalog/list Lista produtos do catálogo business via comando catalog_list no bridge. # Atualizar conexão Source: https://docs.d-api.cloud/api-reference/cloud-api/atualizar-conexao api-reference/openapi.json PATCH /api/v1/connections/cloud-api/{id} Atualize o roteamento de webhook ou rotacione o token de acesso da Meta. Atualiza uma conexão **API Oficial (Cloud API)**. Envie ao menos um campo: * `webhookUrl` — URL de destino dos eventos (ou `null` para limpar). * `webhookMode` — `normalized` (eventos canônicos D-API) ou `meta_passthrough` (payloads crus da Meta). * `accessToken` — rotaciona o token da Meta. É re-encriptado com AES-256-GCM na escrita. > [!WARNING] > > Requer pelo menos um campo no corpo. Retorna `404` se a conexão não for > encontrada e `400` se nenhum campo for informado. # Assumir, passar ou soltar uma conversa Source: https://docs.d-api.cloud/api-reference/cloud-api/controlar-conversa api-reference/openapi.json POST /api/v1/connections/cloud-api/{id}/thread-control Troque o dono de uma conversa num número com Conversation Routing: take, pass ou release. Troca o dono de **uma conversa** (um cliente). O `id` aceita o id da conexão ou o id da sessão (`cloud-`). | `action` | Quem pode | O que faz | | - | - | - | | `take` | D-API como parceiro de escalonamento | Assume a conversa de quem for o dono. | | `pass` | D-API como dona da conversa | Entrega a conversa. Sem `targetRole`, vai para o escalonamento. | | `release` | D-API como dona da conversa | Deixa a conversa livre; a próxima mensagem do cliente decide o dono. | Guia completo, com casos de uso e webhooks: [Vários parceiros no mesmo número](/api-oficial/multiplos-parceiros#4-trocar-o-dono-de-uma-conversa). ## Exemplo ```bash theme={null} curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api//thread-control \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "action": "take", "to": "5551999999999" }' ``` ```json theme={null} { "success": true, "data": { "action": "take", "requestId": "abc123" } } ``` ## Erros | HTTP | `code` | Quando | | - | - | - | | 400 | `INVALID_INPUT` | `to` sem telefone, `targetRole` fora de `pass`, `metadata` acima de 2000 caracteres. | | 403 | `NOT_ESCALATION_PARTNER` | `take` sem a D-API ser o parceiro de escalonamento. | | 400 | `THREAD_CONTROL_NOT_ENABLED` | Número sem roteamento ou termos não aceitos pela empresa. | | 400 | `ACTION_NOT_ENABLED` | Ação ou destino não habilitado na conta. | | 400 | `META_GRAPH_ERROR` | Outra recusa da Meta; `data.metaCode` traz o código. | # Criar conexão manualmente Source: https://docs.d-api.cloud/api-reference/cloud-api/criar-conexao-manual api-reference/openapi.json POST /api/v1/connections/cloud-api/manual Conecte um número da API Oficial (Cloud API) informando WABA, número e token da Meta. Cria uma conexão **WhatsApp API Oficial** a partir de credenciais geradas no Meta Business Manager: o id da WhatsApp Business Account (`wabaId`), o id do número (`phoneNumberId`) e um `accessToken`. O backend valida o par (número, token) na Graph API, tenta assinar os webhooks do app (best-effort) e então provisiona a conexão e sincroniza a cobrança do plano Scale. * `webhookMode` — `normalized` (eventos canônicos D-API) ou `meta_passthrough` (payloads crus da Meta). Padrão: `normalized`. * `data.webhookSubscribed` — quando `false`, mostre ao usuário as instruções para assinar o webhook manualmente no painel da Meta. > [!WARNING] > > Requer uma assinatura ativa. Sem assinatura, a resposta é `402` com > `code: "TRIAL_REQUIRED"` — direcione o usuário ao checkout do plano Scale. > [!TIP] > > Para o fluxo guiado via Embedded Signup (SDK), use o assistente de integração > em vez do cadastro manual de token. # Criar template Source: https://docs.d-api.cloud/api-reference/cloud-api/criar-template api-reference/openapi.json POST /api/v1/connections/cloud-api/{id}/templates Envie um novo template de mensagem para revisão da Meta. Submete um novo template de mensagem à Meta para revisão. * `name` — minúsculas, no formato `snake_case` (ex: `boas_vindas_cliente`). * `category` — `MARKETING`, `UTILITY` ou `AUTHENTICATION`. * `language` — código de idioma da Meta (ex: `pt_BR`). * `bodyText` — corpo do template. Use placeholders `{{1}}`, `{{2}}`… para variáveis. * `bodyExample` — um valor de exemplo por placeholder, exigido pela Meta na submissão. * `footerText` — rodapé opcional. ### Header Escolha o tipo de header pelo `headerFormat`: * `TEXT` (padrão) — use `headerText`. * `IMAGE`, `VIDEO` ou `DOCUMENT` — informe a mídia de exemplo em `headerMediaUrl` (URL pública) **ou** `headerMediaBase64`. O backend faz o upload da amostra na API de Resumable Upload da Meta automaticamente — você não precisa gerar o `header_handle` manualmente. ### Botões Passe `buttons[]` (a Meta limita por tipo — ex: 1 telefone, até 2 URLs): * `QUICK_REPLY` — `{ "type": "QUICK_REPLY", "text": "Sim" }` * `URL` — `{ "type": "URL", "text": "Ver pedido", "url": "https://site.com/{{1}}", "urlExample": "https://site.com/42" }` (`urlExample` só é necessário quando a `url` tem `{{1}}`). * `PHONE_NUMBER` — `{ "type": "PHONE_NUMBER", "text": "Ligar", "phoneNumber": "+5511999999999" }` * `COPY_CODE` — `{ "type": "COPY_CODE", "example": "PROMO10" }` A resposta em `data` traz o id do template criado e o status inicial (normalmente `PENDING`). > [!WARNING] > > A aprovação é feita pela Meta e pode levar de minutos a horas. Só templates > `APPROVED` podem ser enviados. # Enviar template Source: https://docs.d-api.cloud/api-reference/cloud-api/enviar-template api-reference/openapi.json POST /api/v1/messages/send/template Envie um template aprovado por uma conexão da API Oficial (Cloud API). Envia um template **aprovado** para um número (`to`) a partir de uma conexão **API Oficial (Cloud API)** (`sessionId`). O número usa o formato internacional sem `+` (ex: `5511999999999`). Dentro de `template`: * `name` e `language` — devem corresponder a um template `APPROVED` (veja [Listar templates aprovados](/api-reference/cloud-api/listar-templates)). * `bodyVariables` — valores para os placeholders `{{1}}`, `{{2}}`… do corpo. * `headerVariable` / `headerMedia` — variável de texto ou mídia de header (por `url` ou `base64`); o backend monta os `components` da Graph API. * `components` — opcional: monte você mesmo os components no formato da Graph API e o backend os envia como estão. > [!WARNING] > > Templates só podem ser enviados por conexões `cloud_api`. Em conexões não > oficiais a resposta é `400` com `code: "NOT_CLOUD_API"`. # Excluir template Source: https://docs.d-api.cloud/api-reference/cloud-api/excluir-template api-reference/openapi.json DELETE /api/v1/connections/cloud-api/{id}/templates/{name} Exclua um template da WABA pelo nome (todas as línguas). Exclui um template de mensagem da WABA da conexão pelo `name`. A exclusão remove **todas as variantes de idioma** daquele nome de template. Retorna `{ "success": true }` na conclusão. > [!WARNING] > > A operação é irreversível na Meta. Um template excluído precisa ser recriado e > passar por nova revisão. # Listar templates aprovados Source: https://docs.d-api.cloud/api-reference/cloud-api/listar-templates api-reference/openapi.json GET /api/v1/connections/cloud-api/{id}/templates Liste os templates de mensagem APROVADOS da WABA da conexão. Lista os templates de mensagem **aprovados** da WhatsApp Business Account vinculada à conexão. Cada item em `data` traz `name`, `language`, `category`, `status` e os `components` conforme retornados pela Meta. Use os valores de `name` e `language` ao enviar via [Enviar template](/api-reference/cloud-api/enviar-template). > [!TIP] > > Para ver templates em qualquer status (inclusive `PENDING`/`REJECTED`), use > [Listar todos os templates](/api-reference/cloud-api/listar-templates-todos). # Listar todos os templates Source: https://docs.d-api.cloud/api-reference/cloud-api/listar-templates-todos api-reference/openapi.json GET /api/v1/connections/cloud-api/{id}/templates/all Liste TODOS os templates da WABA, em qualquer status de revisão. Lista **todos** os templates da WABA da conexão, independentemente do status de revisão (`APPROVED`, `PENDING`, `REJECTED`, etc.). Indicado para telas de gestão, onde você precisa acompanhar templates ainda em análise. Cada item em `data` inclui o `status` atual do template na Meta. > [!TIP] > > Para o envio, prefira [Listar templates aprovados](/api-reference/cloud-api/listar-templates): > só templates `APPROVED` podem ser enviados. # Obter access token da Meta Source: https://docs.d-api.cloud/api-reference/cloud-api/obter-access-token api-reference/openapi.json GET /api/v1/connections/cloud-api/{id}/access-token Recupere, já descriptografado, o access token da Meta guardado numa conexão da API Oficial — e descubra de que tipo ele é. Devolve o **access token da Meta** que a D-API guarda para a conexão, já **descriptografado**, junto com a classificação do token. O `id` aceita o id da conexão ou o id da sessão (`cloud-`). ## Tipos de token (`kind`) | `kind` | O que é | `expiresAt` | | - | - | - | | `permanent` | Não expira — token de System User / integração de negócio. É o que o Embedded Signup emite. | `null` | | `long_lived` | Token de \~60 dias (troca de token de longa duração). | data ISO-8601 | | `short_lived` | Token de \~1h, vindo direto da troca do `code`. | data ISO-8601 | | `unknown` | O `/debug_token` da Meta não respondeu — o token vai mesmo assim, sem classificação. | `null` | Além de `kind`, `data` traz `label` (resumo em português, pronto para exibir), `expiresInDays`, `isValid`, `scopes`, `type` (o rótulo da própria Meta: `USER`, `SYSTEM_USER`…), `wabaId`, `phoneNumberId` e `businessId`. ## Exemplo ```bash theme={null} curl https://api.d-api.cloud/api/v1/connections/cloud-api//access-token \ -H "Authorization: " ``` ```json theme={null} { "success": true, "data": { "accessToken": "EAAG…", "wabaId": "102290129340398", "phoneNumberId": "106540352242922", "businessId": "1049837394389", "kind": "permanent", "label": "Permanente (System User) — não expira", "expiresAt": null, "expiresInDays": null, "isValid": true, "type": "SYSTEM_USER", "scopes": ["whatsapp_business_management", "whatsapp_business_messaging"] } } ``` > [!WARNING] > > O `accessToken` é **segredo**: com ele é possível enviar mensagens e administrar a > WABA. Chame esta rota só do seu backend, com a API key secreta, e não registre o > token em logs. Cada leitura é auditada. > [!NOTE] > > Para **trocar** o token guardado (rotação), use > [Atualizar conexão](/api-reference/cloud-api/atualizar-conexao) com o campo > `accessToken`. # Obter conexão Source: https://docs.d-api.cloud/api-reference/cloud-api/obter-conexao api-reference/openapi.json GET /api/v1/connections/cloud-api/{id} Consulte os detalhes de uma conexão da API Oficial (Cloud API) pelo id. Retorna os detalhes de uma única conexão **API Oficial (Cloud API)** pelo `id`. O objeto em `data` traz o id da WABA, o id e o número exibido, o nome verificado, o roteamento de webhook (`webhookUrl`, `webhookMode`) e os indicadores de saúde (qualidade e tier de mensagens) sincronizados da Meta. > [!WARNING] > > Retorna `404` quando a conexão não pertence ao usuário autenticado. # Ver parceiros e roteamento Source: https://docs.d-api.cloud/api-reference/cloud-api/ver-roteamento api-reference/openapi.json GET /api/v1/connections/cloud-api/{id}/routing Descubra se outros parceiros estão no número e qual é o papel da D-API no Conversation Routing da Meta. Mostra se outros apps (parceiros) estão conectados à mesma conta do WhatsApp e qual papel a D-API recebeu no **Conversation Routing**. O `id` aceita o id da conexão ou o id da sessão (`cloud-`). Para entender os papéis e quando usar cada um, veja [Vários parceiros no mesmo número](/api-oficial/multiplos-parceiros). ## Exemplo ```bash theme={null} curl https://api.d-api.cloud/api/v1/connections/cloud-api//routing \ -H "Authorization: " ``` ```json theme={null} { "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 } } ``` | `situation` | Significado | | - | - | | `exclusive` | Só a D-API na conta. | | `shared_without_routing` | Há outro parceiro e nenhum roteamento: todos recebem tudo e todos respondem. | | `routed` | Roteamento ativo. Veja `roles`, `isStandby` e `isEscalation`. | > [!WARNING] > > Consulta a Meta ao vivo, e a Meta limita a frequência. Chame sob demanda, > nunca antes de cada envio. # Baixar mídia Source: https://docs.d-api.cloud/api-reference/endpoints/baixar-midia api-reference/openapi.json POST /api/v1/media/download Baixe mídia recebida de forma unificada. Baixa a mídia de uma mensagem recebida. O WhatsApp entrega mídias criptografadas; este endpoint descriptografa usando os metadados que chegam no webhook (`media_key`, `mimetype`, `direct_path` ou `url`, e os hashes). Defina `base64: true` para receber o conteúdo embutido na resposta, ou use `async` para downloads grandes em segundo plano. > [!TIP] > > Os campos necessários (`media_key`, `mimetype`, `file_sha256` etc.) vêm no > payload do webhook de mensagem recebida — repasse-os diretamente para cá. ## API Oficial (Cloud API) Nas conexões da API Oficial a mídia fica na Meta e é identificada pelo `media_id`, que chega no webhook em `media_data.media_id`. Envie `media_id` e `mimetype` no lugar de `media_key`, `direct_path` e hashes. A resposta é sempre síncrona — `async` não é aceito nessas conexões. ```json theme={null} { "sessionId": "cloud-...", "media_id": "1234567890", "mimetype": "image/jpeg", "base64": true } ``` ## Conta com "Não armazenar mídias" Com a opção **Não armazenar mídias** ativa em **Minha Conta → Privacidade**, a D-API não guarda nenhuma mídia da conta: nada vai para o storage, Redis, filas ou banco. Os webhooks de mensagem recebida trazem só os metadados (`media_key`, `direct_path`, hashes ou `media_id`), sem `media_url` e sem base64, e o arquivo é obtido por este endpoint. Nessas contas: * a resposta é sempre base64, mesmo sem `base64: true`; * `async` é recusado — o download é somente síncrono; * envios de mídia em base64 com `async` também são recusados; use o envio síncrono ou uma URL. > [!WARNING] > > Ativar ou desativar a opção reinicia as conexões não oficiais da conta, > que ficam alguns segundos offline. # Consultar comando assíncrono Source: https://docs.d-api.cloud/api-reference/endpoints/consultar-comando api-reference/openapi.json GET /api/v1/commands/{commandId} Acompanhe o resultado de um comando enviado com async. Quando você envia um comando com `async: true`, a API responde na hora com um `commandId` e executa o comando em segundo plano. Este endpoint diz o que aconteceu com ele. ```json theme={null} { "success": true, "commandId": "9f1c8f2e-4b7a-4f10-9c3d-2e1a8b5d7c40", "sessionId": "minha-sessao", "commandType": "send_text", "status": "completed", "result": { "commandId": "9f1c8f2e-4b7a-4f10-9c3d-2e1a8b5d7c40", "sessionId": "minha-sessao", "commandType": "send_text", "success": true, "data": { "messageId": "3EB0C767D26B8CA3F7A1" }, "error": null, "timestamp": "2026-09-03T04:15:22.318Z" }, "error": null, "queuedAt": "2026-09-03T04:15:21.902Z", "startedAt": "2026-09-03T04:15:22.104Z", "finishedAt": "2026-09-03T04:15:22.318Z" } ``` ## Status | `status` | Significado | | - | - | | `queued` | Na fila, ainda não começou | | `processing` | Executando agora | | `completed` | Executou — veja `result.success` | | `failed` | O worker falhou antes de concluir; o motivo vem em `error` | > [!WARNING] > > `status` não é o sucesso do comando. Um comando que rodou e falhou (número > inválido, sessão desconectada) fica `completed` com `result.success: false` e > o motivo em `result.error`. O `status: "failed"` cobre só a falha do worker. O campo `result` traz o mesmo payload do webhook `command.result` e só é preenchido quando o comando termina. Antes disso ele vem `null`. ## Escopo e retenção Você só enxerga comandos das suas próprias sessões. Uma API Key restrita a uma sessão consulta apenas os comandos daquela sessão. Comando de terceiros responde `404`, igual a um `commandId` inexistente. > [!NOTE] > > O resultado fica disponível por uma janela limitada — cerca de 1 hora após a > execução (24 horas em caso de falha do worker). Passado esse prazo a resposta > é `404`. Para entrega garantida, use o webhook > [`command.result`](/whatsapp/comandos-assincronos) em > vez de polling. # Envio assíncrono em ordem (sequential) Source: https://docs.d-api.cloud/api-reference/endpoints/envio-sequencial Garanta que mensagens assíncronas para o mesmo contato cheguem na ordem em que foram enviadas. Com `async: true`, a API enfileira o envio e responde na hora com um `commandId`. Os comandos da fila rodam em paralelo, então dois envios seguidos para o mesmo contato podem chegar fora de ordem — uma imagem pesada sai depois do texto que foi enviado logo em seguida. Adicione `sequential: true` para que os envios para **o mesmo destinatário** saiam um de cada vez, na ordem em que a API os recebeu. ```json theme={null} { "sessionId": "minha-sessao", "to": "5511999999999", "text": "Primeira mensagem", "async": true, "sequential": true } ``` A resposta é a mesma de qualquer envio assíncrono: o `commandId` para [consultar o comando](/api-reference/endpoints/consultar-comando) ou correlacionar com o webhook [`command.result`](/whatsapp/comandos-assincronos). ## Como funciona * A ordem é por conversa: sessão (`sessionId`) + destinatário (`to`). Envios para outros destinatários continuam em paralelo, sem esperar. * O próximo envio só começa quando o anterior termina, com sucesso ou com falha. Uma falha **não interrompe** a sequência: ela é reportada no `command.result` daquele comando e o seguinte sai normalmente. * Sem `sequential`, o envio assíncrono funciona exatamente como antes. > [!WARNING] > > A ordem preservada é a de **chegada na API**. Requests disparados em paralelo > pelo seu sistema não têm ordem definida. Para garantir a sequência, envie em > série: aguarde a resposta de um request antes de disparar o próximo. A > resposta chega na hora, porque o envio em si acontece em segundo plano. ## Rotas compatíveis | Rota | Tipo | | - | - | | `POST /api/v1/messages/send/text` | Texto | | `POST /api/v1/messages/send/image` | Imagem | | `POST /api/v1/messages/send/video` | Vídeo | | `POST /api/v1/messages/send/audio` | Áudio | | `POST /api/v1/messages/send/document` | Documento | | `POST /api/v1/messages/send/sticker` | Figurinha | | `POST /api/v1/messages/send/location` | Localização | | `POST /api/v1/messages/send/contact` | Contato | O campo aceita booleano (`true`) ou string (`"true"`). Ele é ignorado quando: * o envio não tem `async: true`; * a sessão é da API Oficial (`cloud_api`), em que o envio é sempre síncrono. ## Limite de envios pendentes Cada destinatário aceita até 100 envios pendentes na sequência. Acima disso a API responde `429` e o envio **não** é enfileirado: ```json theme={null} { "success": false, "error": "Too many sequential commands pending for this recipient (100). Wait for the queue to drain before sending more." } ``` O cabeçalho `Retry-After` indica quantos segundos esperar (de 1 a 60) antes de tentar de novo. # Associar etiqueta a chat Source: https://docs.d-api.cloud/api-reference/etiquetas/associar-etiqueta-a-chat /api-reference/openapi.json post /api/v1/labels/attach Associa ou desassocia uma etiqueta a um chat via PodWorker # Criar/editar etiqueta Source: https://docs.d-api.cloud/api-reference/etiquetas/criareditar-etiqueta /api-reference/openapi.json post /api/v1/labels/upsert Cria ou edita uma etiqueta via PodWorker # Listar etiquetas Source: https://docs.d-api.cloud/api-reference/etiquetas/listar-etiquetas /api-reference/openapi.json get /api/v1/labels/list Lista etiquetas armazenadas para a sessão informada. Parâmetro includeDeleted aceita 'true' ou 'false' (padrão: false). # Listar etiquetas de contato Source: https://docs.d-api.cloud/api-reference/etiquetas/listar-etiquetas-de-contato /api-reference/openapi.json get /api/v1/labels/contact-labels Lista etiquetas associadas a um contato específico (por telefone). Parâmetro includeDeleted aceita 'true' ou 'false' (padrão: false). # Sincronizar etiquetas Source: https://docs.d-api.cloud/api-reference/etiquetas/sincronizar-etiquetas /api-reference/openapi.json post /api/v1/labels/sync Dispara um full sync das etiquetas via PodWorker # Aprovar solicitações de entrada no grupo Source: https://docs.d-api.cloud/api-reference/grupos/aprovar-solicitações-de-entrada-no-grupo /api-reference/openapi.json post /api/v1/groups/{groupId}/join-requests/approve Aprova solicitações de entrada de participantes em um grupo # Definir configurações de privacidade do grupo Source: https://docs.d-api.cloud/api-reference/grupos/definir-configurações-de-privacidade-do-grupo /api-reference/openapi.json put /api/v1/groups/{groupId}/settings Altera as configurações de privacidade do grupo: - **announce**: true = apenas admins podem enviar mensagens - **locked**: true = apenas admins podem editar informações do grupo - **joinApproval**: true = requer aprovação de admin para entrar - **memberAddMode**: "admin" = apenas admins podem adicionar membros, "all" = todos podem adicionar # Reprovar solicitações de entrada no grupo Source: https://docs.d-api.cloud/api-reference/grupos/reprovar-solicitações-de-entrada-no-grupo /api-reference/openapi.json post /api/v1/groups/{groupId}/join-requests/reject Reprova solicitações de entrada de participantes em um grupo # Revogar link de convite do grupo Source: https://docs.d-api.cloud/api-reference/grupos/revogar-link-de-convite-do-grupo /api-reference/openapi.json post /api/v1/groups/{groupId}/invite/revoke Revoga o link de convite atual e gera um novo. O link antigo deixará de funcionar # Sincronizar histórico (bulk) via webhook no formato D-API Source: https://docs.d-api.cloud/api-reference/histórico/sincronizar-histórico-bulk-via-webhook-no-formato-d-api /api-reference/openapi.json post /api/v1/history/sync Reenvia em massa o histórico armazenado da instância para o webhook (formato messages.received da D-API). Webhook padrão: o configurado na session (per_event usa o do evento message received); pode sobrescrever com `webhookUrl` (obrigatório se a instância não tem webhook). Inclui mídia quando a mensagem tem media_url. # Solicitar FULL HISTORY SYNC Source: https://docs.d-api.cloud/api-reference/histórico/solicitar-full-history-sync /api-reference/openapi.json post /api/v1/history/full-sync Dispara um FULL_HISTORY_SYNC_ON_DEMAND via PodWorker # Solicitar HISTORY SYNC ON DEMAND Source: https://docs.d-api.cloud/api-reference/histórico/solicitar-history-sync-on-demand /api-reference/openapi.json post /api/v1/history/on-demand Dispara um HISTORY_SYNC_ON_DEMAND via PodWorker; parâmetro 'count' via query define quantas mensagens buscar (default 50) # Status do history sync (D-API) da instância Source: https://docs.d-api.cloud/api-reference/histórico/status-do-history-sync-d-api-da-instância /api-reference/openapi.json get /api/v1/history/sync/{sessionId}/status Retorna o progresso do último job de history sync (formato D-API) da instância. # Disparar ligações URA em massa (áudio ou fluxo IVR) Source: https://docs.d-api.cloud/api-reference/ligações-ura/disparar-ligações-ura-em-massa-áudio-ou-fluxo-ivr /api-reference/openapi.json post /api/v1/voice/bulk # Disparar uma ligação URA (áudio ou fluxo IVR) Source: https://docs.d-api.cloud/api-reference/ligações-ura/disparar-uma-ligação-ura-áudio-ou-fluxo-ivr /api-reference/openapi.json post /api/v1/voice/call # Iniciar uma ligação URA ao vivo (Bina Inteligente, cobrança 30/6) Source: https://docs.d-api.cloud/api-reference/ligações-ura/iniciar-uma-ligação-ura-ao-vivo-bina-inteligente-cobrança-306 /api-reference/openapi.json post /api/v1/voice/live/start # Criar newsletter Source: https://docs.d-api.cloud/api-reference/newsletters/criar-newsletter /api-reference/openapi.json post /api/v1/newsletters/create Cria uma nova newsletter/canal. picture pode ser URL ou base64. # Listar newsletters Source: https://docs.d-api.cloud/api-reference/newsletters/listar-newsletters /api-reference/openapi.json get /api/v1/newsletters/list Lista todas as newsletters/canais que o usuário está inscrito # Enviar SMS em massa (mesma mensagem para vários números) Source: https://docs.d-api.cloud/api-reference/sms/enviar-sms-em-massa-mesma-mensagem-para-vários-números /api-reference/openapi.json post /api/v1/sms/bulk # Enviar um SMS Source: https://docs.d-api.cloud/api-reference/sms/enviar-um-sms /api-reference/openapi.json post /api/v1/sms/send