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

integração · python

API WhatsApp Python com requests ou httpx, direto na REST

Integre a API WhatsApp Python do seu SaaS direto na REST da D-API: um cliente httpx de 30 linhas cria a conexão do cliente, envia mensagens e trata erros, e um endpoint FastAPI recebe os eventos.

SaaS testa 14 dias com o time técnico ajudando na integração.

conexões na D-API
1.875
de uptime garantido em contrato
99,9%
datacenters no Brasil
4
por ligação de WhatsApp na API não-oficial
R$ 0
  • Sem SDK, sem dependência extra

    Não há SDK Python. A API REST com OpenAPI 3 é a mesma que o SDK Node chama, e requests ou httpx bastam.

  • Contrato previsível

    Envio síncrono devolve success e messageId. Falha volta com HTTP 400 e o motivo no corpo.

  • Webhook em qualquer framework

    Os eventos chegam como POST JSON com envelope fixo. FastAPI, Flask ou Django recebem do mesmo jeito.

A API WhatsApp Python da D-API é a própria API REST. Não existe SDK Python oficial, e para a maioria dos backends isso simplifica: a API é descrita em OpenAPI 3, usa JSON e um header de autenticação, e qualquer cliente HTTP conversa com ela. O SDK oficial existe para Node, e ele chama exatamente os mesmos endpoints que você vai chamar daqui.

Esta página mostra o caminho completo em Python, com o exemplo de uma plataforma de cobrança escrita em Django ou FastAPI que precisa mandar lembretes pelo WhatsApp do credor e ler as respostas dos devedores.

Um cliente httpx para a API de WhatsApp

O resultado que você quer é um módulo pequeno, com timeout explícito e erro claro, que o resto do código importa. Com httpx:

import os
import httpx

class DApiError(Exception):
    def __init__(self, status: int, body: dict):
        super().__init__(body.get("error") or body.get("message") or f"HTTP {status}")
        self.status = status
        self.body = body

class DApi:
    def __init__(self, api_key: str, timeout: float = 15.0):
        self._http = httpx.Client(
            base_url="https://api.d-api.cloud",
            headers={"Authorization": api_key},
            timeout=timeout,
        )

    def _call(self, method: str, path: str, **kwargs) -> dict:
        resp = self._http.request(method, path, **kwargs)
        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        if resp.is_error or body.get("success") is False:
            raise DApiError(resp.status_code, body)
        return body

    def create_session(self, session_id: str, webhook_url: str) -> dict:
        return self._call("POST", "/api/v1/sessions", json={
            "sessionId": session_id, "type": "unofficial", "webhookUrl": webhook_url,
        })

    def qr(self, session_id: str) -> dict:
        return self._call("GET", f"/api/v1/sessions/{session_id}/qr")

    def send_text(self, session_id: str, to: str, text: str, **extra) -> dict:
        return self._call("POST", "/api/v1/messages/send/text", json={
            "sessionId": session_id, "to": to, "text": text, **extra,
        })

dapi = DApi(os.environ["DAPI_API_KEY"])

A checagem dupla em _call importa. A maioria das falhas vem com status HTTP de erro, como o 400 de um envio que não saiu. Algumas rotas, porém, respondem com success: false no corpo, por exemplo quando a sessão ainda não está conectada. Olhar os dois evita tratar falha como sucesso. Com requests, o desenho é o mesmo trocando httpx.Client por requests.Session e passando o timeout em cada chamada.

Conectar o número do credor

Cada credor do seu SaaS conecta o próprio número, e cada número é uma sessão com o sessionId que você escolhe. Use um valor estável ligado ao tenant, como credor-1042.

dapi.create_session("credor-1042", "https://cobranca.seu-saas.com/hooks/whatsapp/TOKEN")
qr = dapi.qr("credor-1042")

O campo qrCodeImage vem como data URL PNG em base64, pronta para um <img> na tela do seu produto. Se o QR ainda não foi gerado, a rota responde 404 com QR code not available; tente de novo em alguns segundos ou espere o evento connection.qrcode no webhook. Para conexão pelo número de telefone, crie a sessão com "connectionMode": "pair" e "pairPhone" e leia o código em GET /api/v1/sessions/{sessionId}/pair-code.

Enviar mensagens de WhatsApp em Python

resp = dapi.send_text(
    "credor-1042",
    "5511999999999",
    "Olá, Carlos. A parcela 3 vence amanhã. Quer receber o boleto por aqui?",
)
message_id = resp["messageId"]

No modo síncrono, a resposta traz success, sessionId, to, messageId, messageType e timestamp. Guarde o messageId: é com ele que os eventos message.delivered e message.read atualizam o status da cobrança.

As outras rotas de envio seguem a mesma forma em /api/v1/messages/send/*: document com fileName e mimetype para o boleto, image, audio, video, location, contact, poll e reaction. Antes da primeira régua, POST /api/v1/contacts/check com uma lista em numbers informa quais telefones da carteira estão no WhatsApp.

Envio em lote sem prender o worker

Uma régua de cobrança dispara centenas de mensagens num horário. No modo síncrono, cada chamada espera o WhatsApp executar. Com async: True, a API enfileira e responde na hora:

resp = dapi.send_text("credor-1042", "5511999999999", texto, **{"async": True, "sequential": True})
pendentes.salvar(command_id=resp["commandId"], parcela_id=parcela.id)

A resposta traz commandId e status: "queued", e o resultado definitivo chega no webhook de conta command.result. O sequential garante que as mensagens para o mesmo devedor saiam na ordem de chegada, com até 100 pendentes por destinatário; acima disso a API devolve 429 com Retry-After. O guia de comandos assíncronos detalha esse fluxo.

Receber o webhook com FastAPI

As respostas dos devedores chegam pelo webhook da sessão, um POST JSON com event, sessionId, data, timestamp e traceId. O handler confirma rápido e manda o trabalho para a fila:

from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.post("/hooks/whatsapp/{token}")
async def whatsapp_hook(token: str, request: Request):
    if token != os.environ["WA_HOOK_TOKEN"]:
        raise HTTPException(status_code=401)
    payload = await request.json()
    if payload["event"] == "messages.received" and not payload["data"].get("fromMe"):
        processar_resposta.delay(payload)  # sua fila: Celery, RQ, Dramatiq
    return {"ok": True}

Dois detalhes vêm da política de entrega. Cada tentativa espera até 30 segundos, e a entrega é repetida até 7 vezes com backoff exponencial, então o mesmo evento pode chegar mais de uma vez: use data["id"] como chave de idempotência no worker. E evite responder 404 ou 410 por erro interno de roteamento, porque esses códigos encerram as tentativas para aquela URL. Os campos de cada evento estão no catálogo de eventos de webhook.

Mídia recebida: comprovante, foto e áudio

Devedor que responde com o comprovante em PDF ou foto gera um messages.received com type igual a document ou image. O campo media_url já aponta para o arquivo armazenado, e media_data traz mimetype, file_length e, em documentos, o filename. No worker, um httpx.get(media_url) baixa o arquivo para anexar ao título.

Se a conta do seu SaaS ativou a opção de não armazenar mídias, o evento chega sem media_url, só com os metadados. Nesse caso, POST /api/v1/media/download recebe sessionId, mimetype, media_key e direct_path ou url do próprio evento e devolve o conteúdo em base64, sempre de forma síncrona. Esses campos vêm no próprio payload da mensagem recebida, então o worker só repassa o que recebeu.

Validar a assinatura do command.result

O webhook de comandos, configurado com secret, envia X-DAPI-Signature com o HMAC-SHA256 em hexadecimal do corpo bruto. Em Python, compare com hmac.compare_digest, sobre os bytes recebidos e não sobre o JSON re-serializado:

import hmac, hashlib

@app.post("/hooks/dapi-comandos")
async def comandos_hook(request: Request):
    raw = await request.body()
    expected = hmac.new(os.environ["DAPI_CMD_SECRET"].encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-DAPI-Signature", "")):
        raise HTTPException(status_code=401)
    data = (await request.json())["data"]
    pendentes.concluir(data["commandId"], sucesso=data["success"], erro=data["error"])
    return {"ok": True}

O mesmo commandId pode chegar duas vezes por causa da retentativa de entrega, então concluir precisa ignorar repetição.

Retentativa do lado do seu código

Repetir uma chamada de envio é decisão de negócio: se a mensagem saiu e a resposta se perdeu, repetir manda o lembrete duas vezes. Uma regra que funciona é repetir automaticamente só erro de rede antes da resposta, 5xx e 429 respeitando Retry-After, e tratar 400 como erro de dado. Para envios em que a duplicidade custa caro, o modo assíncrono é mais seguro, porque a D-API nunca reexecuta um comando que falhou e o command.result dá a resposta definitiva.

Mesmo contrato em outras linguagens

O que vale aqui vale para qualquer stack: o contrato é a REST. Se outro serviço do seu produto roda em Node, o SDK para Node.js cobre as mesmas rotas com tipos, e o guia de PHP mostra o mesmo fluxo com curl e Guzzle. A referência de cada endpoint está na documentação da D-API.

Time D-API. Atualizado em .

Perguntas frequentes

Existe SDK oficial da D-API para Python?

Não. O SDK oficial é para Node.js. Em Python, a integração é feita direto na API REST, que é a mesma usada pelo SDK, com qualquer cliente HTTP.

Posso gerar um cliente Python a partir da OpenAPI?

Pode. A API é descrita em OpenAPI 3, então um gerador de cliente produz as chamadas tipadas. Para a maioria dos SaaS, um wrapper pequeno sobre httpx com os endpoints que você usa é mais simples de manter.

Como envio sem bloquear o worker em Python?

Mande async true no corpo. A API responde na hora com um commandId e o resultado chega depois no webhook command.result. Isso combina bem com Celery, RQ ou qualquer fila que o seu backend já usa.

O webhook tem assinatura que eu possa validar em Python?

O webhook de eventos da sessão não tem HMAC; a recomendação é URL secreta com token no path. O webhook de comandos assíncronos, configurado com secret, envia X-DAPI-Signature com HMAC-SHA256 do corpo bruto.

A gente também é SaaS

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

Continue por aqui

Liberar seu teste grátis

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

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