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
- Uma conta na apiwpp: o teste grátis de 7 dias libera 1 número com os recursos do plano PRO, sem cartão.
- Um número conectado ao projeto, por QR code ou código de pareamento de 8 caracteres.
- Uma chave de API do projeto com o escopo
messages:send, numa variável de ambiente (APIWPP_KEY). A chave vai no cabeçalhoAuthorization: Bearer. - Python 3.9 ou mais recente e o pacote
requests(pip install requests).
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:
| Status | O que significa | O que fazer |
|---|---|---|
400 | Corpo inválido ou conexão fora do status open | Corrigir o corpo ou esperar a reconexão (evento connection.status) |
401 / 403 | Chave ausente, revogada ou sem o escopo | Conferir a chave; repetir não adianta |
429 | Limite atingido, como o teto de destinatários novos do número (new_recipient_cap_reached) | Esperar os segundos do cabeçalho Retry-After |
5xx | Falha do lado da API | Repetir 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:
- guarde o
data.messageIddos eventos já processados (uma tabela com chave única resolve) e ignore os repetidos; - ignore os tipos de evento que o seu código não conhece, em vez de responder erro: a lista de tipos só cresce;
- baixe a mídia recebida assim que o evento chegar, porque
data.media.urlé uma URL assinada e temporária.
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.
Outras integrações
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.