--- title: "Como funciona a API de WhatsApp, passo a passo | D-API" description: "Veja como funciona a API de WhatsApp de ponta a ponta: criar a sessão, ler o QR, enviar a primeira mensagem, receber webhook e acompanhar o status da conexão." url: https://d-api.cloud/como-funciona-api-de-whatsapp --- Guia da API de WhatsApp # Como funciona a API de WhatsApp, da conta ao webhook A API de WhatsApp funciona em seis etapas: você cria uma conta, cria uma sessão para o número, conecta lendo um QR, envia mensagens por HTTP, recebe eventos por webhook e acompanha se a conexão está de pé. Abaixo, cada etapa com a chamada real. Por Time de engenharia D-APIAtualizado em 24 de set de 20266 min de leitura ## O fluxo inteiro em uma lista Antes de entrar no detalhe, vale ver o caminho completo. Cada item depende do anterior, e é nessa ordem que o time de desenvolvimento vai implementar: 1. **Conta e API Key.** Você se cadastra no painel e copia a chave. Ela vai no header `Authorization` de toda requisição, sem o prefixo Bearer. 2. **Criar a sessão.** Uma sessão é uma conexão com um número. Você escolhe o `sessionId` e, opcionalmente, já informa a URL do webhook. 3. **Ler o QR code.** A API devolve o QR, o dono do número escaneia pelo celular e a sessão passa a ficar conectada. 4. **Enviar.** Texto, mídia, listas e grupos são chamadas POST com o `sessionId` e o número de destino. 5. **Receber por webhook.** Mensagens que chegam, confirmações de leitura e mudanças de estado viram requisições para a sua URL. 6. **Monitorar a conexão.** Seu sistema precisa saber quando um número caiu, para avisar o cliente antes que ele perceba sozinho. Esse é o desenho de qualquer [API de WhatsApp](https://d-api.cloud/) que conecta por QR. Nos exemplos, a base é `https://api.d-api.cloud` e todos os caminhos começam com `/api/v1`. ## Etapas 1 e 2: autenticar e criar a sessão Com a chave copiada do painel, a primeira chamada cria a conexão. O campo `type` define se ela é não oficial (`unofficial`, conectada por QR) ou oficial (`cloud_api`). Aqui usamos a não oficial e já apontamos o webhook: ``` curl -X POST https://api.d-api.cloud/api/v1/sessions \ -H "Authorization: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sessionId": "cliente-42", "type": "unofficial", "webhookUrl": "https://seu-app.com/webhooks/whatsapp" }' ``` Escolha um `sessionId` que já faça sentido no seu banco, como o ID do cliente ou da unidade. Isso evita uma tabela de tradução depois: quando o webhook chegar, o próprio identificador diz de quem é o evento. ## Etapa 3: conectar o número pelo QR A sessão nasce aguardando pareamento. Para exibir o QR na sua tela, busque a imagem pronta com `?image=1`, que devolve um PNG: ``` curl "https://api.d-api.cloud/api/v1/sessions/cliente-42/qr?image=1" \ -H "Authorization: SUA_API_KEY" \ --output qr.png ``` Sem o parâmetro, a resposta vem em JSON, com o texto do QR, a versão em base64 e o horário da última atualização. O QR expira em poucos segundos e é renovado sozinho, então a interface do seu produto deve buscar de novo enquanto o status for `connecting`. Quem prefere não usar câmera pode parear por código numérico; os detalhes estão em [conectar pela API com QR code](https://d-api.cloud/api-whatsapp-qr-code). ## Etapa 4: enviar a primeira mensagem Com o número conectado, enviar é uma requisição com três campos obrigatórios: `sessionId`, `to` e `text`. O destino vai no formato internacional, sem o sinal de mais: ``` 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": "cliente-42", "to": "5511999999999", "text": "Sua consulta de amanhã às 14h está confirmada." }' ``` Imagem, áudio, vídeo e documento seguem o mesmo padrão em rotas próprias, trocando `text` pelo campo do arquivo. Se o seu sistema dispara muitos envios de uma vez, o campo opcional `async` devolve um `commandId` na hora, e o resultado pode ser consultado depois, sem segurar a requisição. Em Node, o mesmo trecho fica mais curto com o SDK oficial, que tem `sessions.create`, `sessions.getQRCode` e `messages.sendText`. Veja a página do [SDK de Node.js](https://d-api.cloud/integrations/nodejs-sdk). ## Etapa 5: receber eventos por webhook Tudo o que acontece no número chega à URL configurada como um POST em JSON. O envelope é sempre o mesmo: nome do evento, `sessionId`, os dados e um `traceId` para rastrear o caminho da mensagem nos seus logs. ``` { "event": "messages.received", "sessionId": "cliente-42", "data": { "id": "3EB0...", "type": "text", "fromMe": false, "is_group": false, "from_name": "Maria" }, "timestamp": "2026-01-24T22:51:32.601Z", "traceId": "c17dee..." } ``` Três cuidados no seu endpoint: responda rápido com status 200 e processe depois, numa fila sua; trate o mesmo evento chegando duas vezes sem duplicar efeito; e proteja a URL, já que o webhook de WhatsApp não vem assinado. A documentação recomenda URL secreta e checagem do `sessionId`. Se o seu servidor falhar, a D-API tenta de novo até sete vezes, com intervalo crescente. Os eventos disponíveis e a configuração por evento estão em [webhook da API de WhatsApp](https://d-api.cloud/webhook-api-whatsapp). ## Etapa 6: saber quando a conexão cai Um número pode desconectar porque o dono removeu o aparelho vinculado, porque o WhatsApp encerrou a sessão ou por instabilidade. Há duas formas de acompanhar: - **Pelo evento `connection.status`:** o campo `data.status` chega como `connected`, `disconnected` ou `logged_out`. É o jeito recomendado, porque o aviso chega no momento da mudança. - **Consultando a sessão:** `GET /api/v1/sessions/cliente-42` retorna os dados da sessão, incluindo o status. Serve para uma tela de diagnóstico ou para conferir o estado depois de um deploy. A diferença entre os dois estados de queda importa: `disconnected` costuma se resolver com reconexão, que a infraestrutura tenta sozinha, enquanto `logged_out` significa que o número foi desvinculado e alguém precisa ler um QR novo. Quando esse segundo caso acontece, o ideal é o seu produto mostrar o aviso na tela do cliente, e não ele descobrir porque as mensagens pararam. ## Onde a implementação costuma travar As chamadas em si são simples. O trabalho de verdade aparece na borda do seu sistema: guardar a relação entre sessão e cliente, montar a tela de pareamento, processar webhook sem perder evento e decidir o que fazer quando um número cai. Quem precisa de uma conexão por cliente, como um SaaS, gasta a maior parte do esforço aí, e por isso vale olhar a [API de WhatsApp para SaaS](https://d-api.cloud/api-whatsapp-para-saas) antes de desenhar a arquitetura. ## Perguntas frequentes ### Quanto tempo leva para enviar a primeira mensagem pela API? Com a API Key em mãos, o caminho é curto: uma chamada cria a sessão, você lê o QR com o celular e a próxima chamada já envia texto. O que leva mais tempo costuma ser preparar o endpoint que vai receber os webhooks no seu sistema. ### O celular precisa ficar ligado depois de conectar? Não para a sessão funcionar. Depois do pareamento, a conexão roda no servidor como um aparelho vinculado, igual ao WhatsApp Web. O número continua ativo no celular e as mensagens aparecem nos dois lados. ### O que é o sessionId? É o nome que você dá para cada conexão ao criá-la, por exemplo o identificador do cliente no seu sistema. Todo envio, consulta e webhook carrega esse valor, e é por ele que você sabe de qual número a mensagem saiu ou chegou. ### Preciso consultar a API o tempo todo para saber se chegou mensagem? Não. Esse é o papel do webhook: a D-API faz um POST na sua URL a cada evento, como mensagem recebida ou mudança de status. Ficar consultando em loop gasta recurso e ainda chega atrasado. ### O fluxo muda se eu usar a API oficial da Meta? A conexão muda: em vez de QR, você informa os dados da conta da Meta ao criar a sessão com type cloud\_api. Depois disso, as rotas de envio e o formato normalizado do webhook são os mesmos da conexão não oficial. Teste a API de WhatsApp da D-API3 dias grátis, sem cartão.[Começar trial grátis](https://app.d-api.cloud/register) ## Continue lendo - [Guia da API de WhatsAppQuanto custa a API de WhatsApp](https://d-api.cloud/quanto-custa-api-de-whatsapp) - [Guia da API de WhatsAppAPI de WhatsApp grátis](https://d-api.cloud/api-de-whatsapp-gratis) - [Guia da API de WhatsAppAPI oficial vs não oficial](https://d-api.cloud/api-whatsapp-oficial-vs-nao-oficial) - [Guia da API de WhatsAppComo evitar banimento](https://d-api.cloud/como-evitar-banimento-api-whatsapp) ## Teste a API de WhatsApp da D-API Trial de 3 dias com acesso completo. Sem cartão, sem fidelidade. [Começar trial grátis](https://app.d-api.cloud/register)[Ver documentação](https://docs.d-api.cloud/)