Pular para o conteúdo
apiwpp
Integração

API de WhatsApp para Python: envio com requests e webhook com Flask ou FastAPI

Envie mensagens de WhatsApp com requests no Python, trate 429 com Retry-After e receba webhooks no Flask ou FastAPI com hmac.compare_digest.

Atualizado em

A apiwpp é uma API REST com JSON, então no Python basta uma biblioteca HTTP para enviar mensagens de WhatsApp: o exemplo usa requests. Para receber mensagens e confirmações de entrega, o seu sistema expõe um endpoint HTTP, e esta página mostra o mesmo endpoint em Flask e em FastAPI, com a verificação da assinatura que uma integração em produção precisa.

O que você precisa

Nunca coloque a chave no código nem no repositório: ela aparece uma única vez no painel e deve ficar num cofre de segredos ou nas variáveis de ambiente do servidor.

Enviar uma mensagem com requests

POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 na hora, com o jobId, o horário previsto do envio (scheduledAt, em milissegundos unix) e a posição na fila (position):

import os

import requests

API = "https://api.apiwpp.com"
API_KEY = os.environ["APIWPP_KEY"]

class RetryLater(Exception):
    """The API asked to wait: retry after `seconds`."""

    def __init__(self, seconds: int):
        super().__init__(f"retry in {seconds}s")
        self.seconds = seconds

def send_whatsapp(connection_id: str, to: str, message: str, client_ref: str) -> dict:
    response = requests.post(
        f"{API}/connections/{connection_id}/send",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"to": to, "message": message, "clientRef": client_ref},
        timeout=15,
    )
    if response.status_code == 429:
        raise RetryLater(int(response.headers.get("Retry-After", "60")))
    response.raise_for_status()
    return response.json()  # {"jobId", "scheduledAt", "position"}, plus "duplicate": True on a repeat

job = send_whatsapp(connection_id, "5511988887777", "Olá! Seu pedido saiu para entrega.", "pedido-1234")
print(job["jobId"], job["position"])

O campo to leva só dígitos, com o código do país e o DDD. Antes de enviar, a API pergunta ao WhatsApp em qual endereço o número está registrado, então contas antigas sem o nono dígito recebem normalmente. Um número que não está no WhatsApp falha na hora.

Além de message, o corpo aceita media (imagem, vídeo, áudio, documento ou figurinha por URL https pública), location ou template com variáveis. Um PDF, por exemplo:

payload = {
    "to": "5511988887777",
    "media": {
        "type": "document",
        "url": "https://cdn.example.com/boletos/1234.pdf",
        "mimetype": "application/pdf",
        "fileName": "boleto-1234.pdf",
        "caption": "Segue o seu boleto.",
    },
    "clientRef": "boleto-1234",
}

Repetir sem duplicar e tratar 400 e 429

Uma requisição pode dar timeout depois de a API já ter aceitado o envio. Com o mesmo clientRef, a repetição responde 200 com o job original e "duplicate": true, sem colocar nada na fila de novo. O clientRef fica reservado por 7 dias e volta nos eventos message.delivery e message.send_failed. Use um identificador do seu domínio, como o id do pedido, e nunca um uuid4() novo a cada tentativa.

Os erros vêm em JSON com o campo error. Decida pelo status HTTP, não pelo texto:

StatusO que significaO que fazer
400Corpo inválido ou conexão fora do status openCorrigir o corpo ou esperar a reconexão (evento connection.status)
401 / 403Chave ausente, revogada ou sem o escopoConferir a chave; repetir não adianta
429Limite atingido, como o teto de destinatários novos do número (new_recipient_cap_reached)Esperar os segundos do cabeçalho Retry-After
5xxFalha do lado da APIRepetir com espera crescente e o mesmo clientRef

No teto de destinatários novos, nada entra na fila: é o seu sistema que agenda a nova tentativa. Com Celery, por exemplo, a tarefa pode se reagendar com o tempo pedido:

@celery_app.task(bind=True, max_retries=5)
def notify_order(self, order_id: str):
    order = Order.objects.get(pk=order_id)
    try:
        send_whatsapp(order.connection_id, order.phone, order.message, f"pedido-{order.pk}")
    except RetryLater as wait:
        raise self.retry(countdown=wait.seconds)

Como o clientRef é o id do pedido, uma tarefa executada duas vezes não manda a mensagem duas vezes.

Receber webhooks com Flask

Cada evento chega como um POST no endereço de webhook do projeto, assinado com HMAC-SHA256 quando o projeto tem um segredo. O cabeçalho X-Sales-Signature traz sha256= seguido do HMAC, em hexadecimal, de timestamp + "." + corpo bruto, e o X-Sales-Timestamp traz o momento da tentativa. A verificação usa o corpo bruto, os bytes exatamente como chegaram:

import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

SECRET = os.environ.get("APIWPP_WEBHOOK_SECRET", "").encode()
if not SECRET:
    raise RuntimeError("APIWPP_WEBHOOK_SECRET is not set")

app = Flask(__name__)

def is_signed(raw_body: bytes, timestamp: str, signature: str) -> bool:
    if not (timestamp.isascii() and timestamp.isdigit()) or not signature:
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    mac = hmac.new(SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={mac}".encode(), signature.encode())

@app.post("/webhooks/whatsapp")
def whatsapp_webhook():
    raw = request.get_data()
    if not is_signed(raw, request.headers.get("X-Sales-Timestamp", ""), request.headers.get("X-Sales-Signature", "")):
        abort(401)
    event = json.loads(raw)
    enqueue(event)  # your background worker: Celery, RQ, a table
    return "", 204

O hmac.compare_digest compara em tempo constante, o que impede descobrir a assinatura medindo o tempo de resposta. A janela de 300 segundos recusa a repetição de entregas antigas. Se o segredo não chegou ao processo, o servidor nem sobe: um HMAC com chave vazia qualquer pessoa consegue calcular.

O mesmo endpoint em FastAPI

No FastAPI, leia o corpo com await request.body() antes de qualquer conversão, e deixe o trabalho pesado para depois da resposta:

from fastapi import BackgroundTasks, FastAPI, Header, HTTPException, Request, Response

app = FastAPI()

@app.post("/webhooks/whatsapp", status_code=204)
async def whatsapp_webhook(
    request: Request,
    background: BackgroundTasks,
    x_sales_timestamp: str = Header(""),
    x_sales_signature: str = Header(""),
):
    raw = await request.body()
    if not is_signed(raw, x_sales_timestamp, x_sales_signature):
        raise HTTPException(status_code=401)
    background.add_task(handle_event, json.loads(raw))
    return Response(status_code=204)

A função is_signed é a mesma do exemplo em Flask. O envelope de todo evento é { type, connectionId, tenantId, externalId, timestamp, data }, e o type diz o que aconteceu: message.incoming, message.delivery, connection.status e outros listados em webhooks assinados.

Processar sem duplicar

Responda com um status 2xx em até 10 segundos. Uma entrega que falha é tentada de novo até 6 vezes, e a entrega é pelo menos uma vez: o mesmo evento pode chegar de novo. Por isso:

Entregas que esgotaram as tentativas ficam registradas e podem ser reenviadas depois que o seu endpoint voltar.

Gerar um cliente a partir da OpenAPI

A especificação da API é OpenAPI 3.1, pública, em português e inglês. A apiwpp gera clientes TypeScript e PHP a partir dela; para Python, você mesmo pode gerar um cliente com o OpenAPI Generator. Tire antes a seção de webhooks, que o gerador transformaria em chamadas que não existem:

curl -s https://docs.apiwpp.com/openapi.json | jq 'del(.webhooks)' > openapi.api.json
docker run --rm -v "$PWD:/local" openapitools/openapi-generator-cli:v7.25.0 generate \
  -i /local/openapi.api.json -g python -o /local/apiwpp-python \
  --additional-properties=packageName=apiwpp_client

Esse cliente é gerado e mantido por você, não é um pacote publicado pela apiwpp. Para poucas rotas, o requests com as funções acima costuma ser mais simples. Veja OpenAPI e clientes gerados e o tutorial enviar mensagem de WhatsApp com Python, com um passo a passo mais longo.

Perguntas frequentes

Existe uma biblioteca Python oficial da apiwpp?

Não há um pacote Python publicado. A API é HTTP com JSON, então o requests (ou o httpx) basta. Se quiser chamadas tipadas, gere um cliente com o OpenAPI Generator a partir da especificação OpenAPI 3.1 pública.

Por que a verificação da assinatura falha no meu Flask?

Quase sempre porque a assinatura foi calculada sobre request.json convertido de volta em texto. A serialização muda e o HMAC não confere. Use request.get_data() no Flask ou await request.body() no FastAPI, e só converta o JSON depois de verificar.

O que fazer quando a API responde 429?

Leia o cabeçalho Retry-After e agende uma nova tentativa depois desse tempo, com o mesmo clientRef. No teto de destinatários novos, mensagens para contatos que já conversaram com o número continuam sendo aceitas.

A resposta 202 significa que a mensagem foi entregue?

Não. O 202 diz que a mensagem entrou na fila do número, que respeita um ritmo de envio para proteger o número. O resultado chega depois pelo webhook message.delivery, com os status sent, delivered, read ou failed.

Todos: Integrações →

Envie mensagens com o fetch nativo do Node.js, sem dependências, e receba os eventos num endpoint Express que verifica a assinatura HMAC-SHA256 de cada entrega.

Envie mensagens com curl ou Guzzle, use o cliente PHP gerado da especificação OpenAPI 3.1 e receba os eventos num script que confere a assinatura HMAC-SHA256 com hash_hmac e hash_equals.

Não há nó nativo da apiwpp no n8n: o envio usa o nó HTTP Request com uma credencial Header Auth, e os eventos chegam num nó Webhook, filtrados pelo campo type e com a assinatura conferida.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.