Pular para o conteúdo
apiwpp

Enviar mensagem de WhatsApp com Python: requests, webhook e Flask

Envie mensagens de WhatsApp com Python e requests, trate 202, 400 e 429 com Retry-After e receba webhooks no Flask ou FastAPI com HMAC verificado.

Equipe apiwpp · 15 min de leitura

Você tem um sistema em Python (um Django, um Flask, um script agendado no cron, um worker que processa pedidos) e precisa que ele mande uma mensagem de WhatsApp: a confirmação de uma compra, o lembrete de uma consulta, o aviso de que o boleto vence amanhã. Chamar uma API HTTP com requests é trivial. O que dá trabalho é o resto: entender o que a resposta quer dizer, repetir sem mandar duas vezes, esperar quando a API pede para esperar e receber de volta a resposta do cliente com segurança.

Este tutorial cobre as duas pontas com a apiwpp. Primeiro, o envio com requests, o mesmo código da aba Python da página inicial, transformado numa função pronta para produção. Depois, um receptor de webhook em Flask (com a variação em FastAPI) que verifica a assinatura HMAC com hmac.compare_digest, responde rápido e processa cada evento uma única vez.

Se o número ainda não está conectado, comece pelo guia de conexão por QR code ou código de pareamento: o envio só funciona com a conexão aberta.

O que você precisa antes do primeiro envio

São quatro itens, e três deles se resolvem no painel:

  1. Uma conta na apiwpp. O teste grátis dura 7 dias, libera 1 número com os recursos do plano PRO e não pede cartão.
  2. Um projeto. Ele representa um sistema seu, com o próprio endereço de webhook e as próprias chaves de API. Cada número de WhatsApp é uma conexão dentro do projeto.
  3. Uma chave de API com o escopo messages:send. A chave começa com wag_live_ e aparece uma única vez. Guarde num cofre de segredos ou numa variável de ambiente, nunca no repositório.
  4. Um número conectado, com a conexão no status open. O id da conexão vai na URL do envio.

Do lado do Python, os exemplos usam Python 3.10 ou mais recente e três pacotes, todos opcionais além do primeiro:

python -m venv .venv && source .venv/bin/activate
pip install requests flask
# opcional, para a variação com FastAPI
pip install fastapi uvicorn

Deixe a chave e o id da conexão no ambiente do terminal:

export APIWPP_KEY="wag_live_…"
export APIWPP_CONNECTION_ID="8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f"

A chave vai no cabeçalho Authorization: Bearer em toda requisição (o cabeçalho X-Api-Key também é aceito). Para conferir se ela funciona antes de enviar qualquer coisa, a rota GET /me responde a organização, os escopos e os projetos que a chave alcança:

curl -s https://api.apiwpp.com/me -H "Authorization: Bearer $APIWPP_KEY"

Enviar a primeira mensagem com requests

Crie um arquivo send.py. O envio é um único POST /connections/{id}/send com o destinatário, o texto e um clientRef:

# send.py
import os

import requests

API = "https://api.apiwpp.com"
conn_id = os.environ["APIWPP_CONNECTION_ID"]

response = requests.post(
    f"{API}/connections/{conn_id}/send",
    headers={"Authorization": f"Bearer {os.environ['APIWPP_KEY']}"},
    json={
        "to": "5511988887777",
        "message": "Olá! Seu pedido saiu para entrega.",
        "clientRef": "pedido-1234",
    },
    timeout=10,
)

print(response.status_code, response.json())
python send.py

Com tudo certo, a saída mostra o status 202 e um corpo como este:

{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }

Repare no timeout=10. Sem ele, o requests espera para sempre por uma resposta que não vem, e um worker travado é pior que um erro. O parâmetro json= já serializa o corpo e define o Content-Type: application/json.

O formato do campo to

O destinatário vai em to só com dígitos, com o código do país e o DDD: 5511988887777, sem +, espaços ou traços. Se a sua base guarda números formatados, limpe antes de enviar com re.sub(r"\D", "", telefone). A apiwpp pergunta ao WhatsApp em qual endereço o número está registrado antes de enviar, então contas antigas, criadas antes do nono dígito, recebem a mensagem mesmo que você mande o número com o 9. Ela nunca inclui nem remove o dígito por conta própria; o motivo está no guia sobre o nono dígito.

Um número que não tem WhatsApp falha na hora, sem novas tentativas. Para limpar uma base antes, a rota POST /connections/{id}/contacts/check verifica até 100 números de uma vez.

Outros tipos de conteúdo

O texto vai em message. No lugar dele, o mesmo endpoint aceita media (imagem, vídeo, áudio, documento ou figurinha a partir de uma URL https pública), location ou template com variáveis. Antes de cada texto, a apiwpp mostra "digitando…" por 1,5 segundo; o campo typingDelay, em milissegundos, muda esse tempo. O envio de arquivos tem um guia próprio: como enviar PDF, imagem, áudio e vídeo.

O que a resposta 202 quer dizer

A chamada de envio não espera a mensagem sair. Ela coloca o envio na fila do número e responde 202 Accepted na hora:

CampoO que é
jobIdO identificador do envio na fila
scheduledAtQuando o envio está previsto, em milissegundos unix
positionO lugar do envio na fila do número

Em Python, scheduledAt vira data com datetime.fromtimestamp(body["scheduledAt"] / 1000, tz=timezone.utc). A fila existe para proteger o número: por padrão, cada número envia no máximo 3 mensagens por minuto, 60 por hora e 200 por dia, com um intervalo aleatório de 3 a 8 segundos entre dois envios e pelo menos 30 segundos entre duas mensagens para a mesma pessoa. Nos primeiros 14 dias depois de conectar, os limites são menores e sobem por etapas. Os detalhes estão na página da fila com ritmo anti-bloqueio.

A consequência para o seu código: 202 quer dizer "aceito", não "entregue". Se o sistema precisa saber que a mensagem chegou ou foi lida, ele escuta o evento message.delivery no webhook, como mostra a segunda metade deste tutorial. Para ver o estado da fila de um número (limites em vigor, uso atual e etapa do aquecimento), use GET /connections/{id}/queue; para cancelar um envio que ainda não saiu, DELETE /connections/{id}/queue/{jobId}.

Do requests.post ao evento message.delivery: o 202 chega na hora, a entrega chega depois pelo webhook no Flask.

Tratar 202, 400 e 429 com Retry-After

Todo erro responde um status HTTP e um JSON com pelo menos o campo error. Esse texto é para pessoas e pode mudar, então o seu código decide pelo status:

StatusQuando aconteceO que fazer
202Envio aceito e colocado na filaGuardar o jobId
200Repetição de um clientRef já aceito, com "duplicate": trueTratar como sucesso; nada novo entrou na fila
400Corpo inválido, conteúdo faltando, destinatário inválido ou conexão fora do status openCorrigir a requisição ou esperar a reconexão; repetir igual não adianta
401Chave ausente, desconhecida, revogada ou expiradaConferir a chave; não repetir
403A chave não tem o escopo da operaçãoUsar uma chave com messages:send
429Limite de requisições ou teto de destinatários novos do númeroEsperar os segundos do cabeçalho Retry-After
5xxFalha do lado da APIRepetir com espera crescente e o mesmo clientRef

O 400 mais comum no começo é a conexão fora do ar:

{ "error": "Connection not ready (status: close)" }

Ele não se resolve repetindo a chamada. Quando a conexão volta, o evento connection.status com open chega no webhook, e aí faz sentido liberar os envios que ficaram parados.

O 429 do envio merece atenção. Cada número alcança, por padrão, até 100 destinatários novos a cada 24 horas: pessoas que não trocaram mensagem com o número nos últimos 28 dias. Passado esse teto, a resposta traz "error": "new_recipient_cap_reached" e o cabeçalho Retry-After, e nada entra na fila. Mensagens para contatos conhecidos continuam sendo aceitas. O mesmo cabeçalho aparece quando o limite de requisições por IP é atingido.

Juntando tudo numa função reaproveitável:

# whatsapp.py
import os
import time

import requests

API = "https://api.apiwpp.com"

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['APIWPP_KEY']}"


class RetryLater(Exception):
    """429: the caller reschedules the send after `retry_after` seconds."""

    def __init__(self, error: str, retry_after: int):
        super().__init__(error)
        self.retry_after = retry_after


class SendRejected(Exception):
    """4xx other than 429: repeating the same request will not help."""

    def __init__(self, status: int, error: str):
        super().__init__(f"{status}: {error}")
        self.status = status


def _error_of(response: requests.Response) -> str:
    try:
        return response.json().get("error", response.reason)
    except ValueError:
        return response.reason


def send_whatsapp(connection_id: str, to: str, message: str, client_ref: str, attempts: int = 4) -> dict:
    for attempt in range(attempts):
        try:
            response = session.post(
                f"{API}/connections/{connection_id}/send",
                json={"to": to, "message": message, "clientRef": client_ref},
                timeout=10,
            )
        except requests.RequestException:
            time.sleep(2**attempt)  # network error or timeout: same clientRef, no duplicate
            continue

        if response.status_code in (200, 202):
            return response.json()  # 202 queued, or 200 with "duplicate": true

        if response.status_code == 429:
            header = response.headers.get("Retry-After", "")
            raise RetryLater(_error_of(response), int(header) if header.isdigit() else 60)

        if response.status_code >= 500:
            time.sleep(2**attempt)
            continue

        raise SendRejected(response.status_code, _error_of(response))

    raise RuntimeError(f"send {client_ref} failed after {attempts} attempts")

Três decisões estão nesse código. Timeouts, erros de rede e 5xx são repetidos com espera crescente (1, 2, 4 e 8 segundos) e o mesmo clientRef, então nenhuma retentativa duplica a mensagem. O 429 não é repetido dentro da função: ele sobe como RetryLater, com os segundos de espera, para que a sua fila de tarefas agende para depois em vez de prender um processo dormindo. E os outros 4xx falham de vez, porque repetir não muda o resultado.

Num worker do Celery, por exemplo, isso vira raise self.retry(countdown=exc.retry_after) dentro de um except RetryLater as exc. No RQ ou numa tabela de envios com cron, o raciocínio é o mesmo: grave o próximo horário e siga para o próximo item.

clientRef: repetir sem mandar duas vezes

O clientRef é o seu identificador do envio, com até 200 caracteres. A primeira requisição com ele numa conexão coloca a mensagem na fila e responde 202. Uma repetição com o mesmo valor, na mesma conexão, responde 200 com o job original e "duplicate": true, sem colocar nada na fila. Ele fica reservado por 7 dias e volta nos eventos message.outgoing, message.delivery e message.send_failed.

Use um valor que já existe no seu domínio e descreve aquele aviso, como pedido-1234-entrega ou consulta-987-lembrete-vespera. Nunca use uuid.uuid4() a cada tentativa: cada retentativa vira um envio novo, e a proteção some. Para reenviar de propósito um aviso que falhou, use um clientRef novo, como pedido-1234-entrega-2. O assunto tem um guia inteiro sobre mensagens duplicadas e idempotência.

Receber webhooks com Flask e verificar o HMAC

O que acontece depois do 202 chega por webhook: a apiwpp faz um POST no endereço do projeto para cada evento, sempre no mesmo envelope type, connectionId, tenantId, externalId, timestamp e data. Para quem envia e recebe mensagens, quatro tipos importam no começo:

EventoQuando chega
message.incomingAlguém escreveu para o número; o texto está em data.body
message.deliveryUma mensagem enviada mudou para sent, delivered, read ou failed, com o messageId e o seu clientRef
message.send_failedUm envio com clientRef não vai acontecer, com o motivo em reason (por exemplo, not_on_whatsapp)
connection.statusA conexão abriu ou fechou, com o motivo em reason

Com um segredo definido no projeto, cada tentativa de entrega vem assinada. O cabeçalho X-Sales-Timestamp traz os segundos unix da tentativa, e X-Sales-Signature traz sha256= seguido do hex do HMAC-SHA256 de timestamp + "." + corpo bruto, com o segredo como chave. Três regras para aceitar um evento:

  1. Assine o corpo bruto, os bytes exatamente como chegaram. Nunca serialize de novo um dicionário já convertido: a ordem e os espaços mudam, e a assinatura não confere.
  2. Recuse um timestamp a mais de 300 segundos do seu relógio. Isso barra a repetição de entregas antigas capturadas por alguém.
  3. Compare em tempo constante, com hmac.compare_digest, nunca com ==.
# webhook_common.py
import hashlib
import hmac
import os
import re
import time

SECRET = os.environ.get("APIWPP_WEBHOOK_SECRET", "")
if not SECRET:
    raise RuntimeError("APIWPP_WEBHOOK_SECRET is not set")  # never verify with an empty key

TOLERANCE_SECONDS = 300


def is_signed(raw_body: bytes, timestamp: str | None, signature: str | None) -> bool:
    if not timestamp or not signature or not re.fullmatch(r"[0-9]+", timestamp):
        return False
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    mac = hmac.new(SECRET.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={mac}".encode(), signature.encode())
# webhook.py
import json

from flask import Flask, abort, request

from webhook_common import enqueue, is_signed  # enqueue is shown in the next section

app = Flask(__name__)


@app.post("/webhooks/whatsapp")
def whatsapp_webhook():
    raw_body = request.get_data()  # the bytes exactly as received
    timestamp = request.headers.get("X-Sales-Timestamp")
    signature = request.headers.get("X-Sales-Signature")
    if not is_signed(raw_body, timestamp, signature):
        abort(401)

    enqueue(json.loads(raw_body), raw_body)  # work happens outside the request
    return "", 204

Alguns detalhes que evitam dor de cabeça. O request.get_data() precisa vir antes de qualquer acesso a request.form ou request.json, senão o Flask pode consumir o corpo. As duas pontas do compare_digest são bytes, porque com texto a função recusa caracteres fora do ASCII com uma exceção, e um cabeçalho forjado viraria um erro 500 em vez de um 401. E o segredo vazio derruba o processo na subida: um HMAC com chave vazia pode ser calculado por qualquer pessoa, então um verificador sem segredo precisa recusar tudo.

Se o projeto não tiver segredo, as entregas chegam sem assinatura. Nesse caso, confira pelo menos o cabeçalho X-Webhook-Token, que vem sempre, também com hmac.compare_digest. A página sobre HMAC e assinatura de webhook explica o conceito com mais calma.

A mesma rota em FastAPI

Em FastAPI, o corpo bruto vem de await request.body() e as BackgroundTasks rodam o trabalho depois de a resposta sair. A função is_signed é a mesma do webhook_common.py:

# webhook_fastapi.py
import json

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

from webhook_common import is_signed, process  # process is shown in the next section

app = FastAPI()


@app.post("/webhooks/whatsapp", status_code=204)
async def whatsapp_webhook(request: Request, background: BackgroundTasks) -> Response:
    raw_body = await request.body()
    if not is_signed(raw_body, request.headers.get("x-sales-timestamp"), request.headers.get("x-sales-signature")):
        raise HTTPException(status_code=401)
    background.add_task(process, json.loads(raw_body), raw_body)
    return Response(status_code=204)

Para testar localmente, rode flask --app webhook run --port 8000 ou uvicorn webhook_fastapi:app --port 8000 e exponha a porta com um túnel https: o endereço do webhook precisa ser uma URL https pública, que responde direto, sem redirecionamentos.

Processar em background, uma vez só

A apiwpp espera uma resposta 2xx em até 10 segundos. Qualquer outra coisa (erro, status diferente, tempo esgotado) conta como falha, e a entrega é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos, até 6 tentativas. Duas consequências para o seu código:

  • Responda antes de trabalhar. Gravar no banco, chamar outro serviço ou responder o cliente fica para depois da resposta 204.
  • Aceite o mesmo evento duas vezes. A entrega é pelo menos uma vez (at-least-once): uma resposta que se perdeu na rede, um tempo esgotado ou um reenvio feito por você no painel repetem o evento. O processamento precisa ser idempotente.

O jeito mais simples é derivar uma chave de cada evento e gravá-la numa tabela com restrição de unicidade. Se a chave já existe, o evento já foi processado. O exemplo abaixo usa uma fila em memória e o SQLite para caber num arquivo:

# webhook_common.py (continued)
import queue
import sqlite3
import threading

events: "queue.Queue[tuple[dict, bytes]]" = queue.Queue()


def enqueue(event: dict, raw_body: bytes) -> None:
    events.put((event, raw_body))


def event_key(event: dict, raw_body: bytes) -> str:
    data = event.get("data") or {}
    conn = event.get("connectionId")
    kind = event.get("type")
    wa_id = ((data.get("raw") or {}).get("key") or {}).get("id")
    if kind == "message.incoming" and wa_id:
        return f"in:{conn}:{wa_id}"
    if kind == "message.outgoing":
        return f"out:{conn}:{data.get('messageId')}"
    if kind == "message.delivery":
        return f"dlv:{conn}:{data.get('messageId')}:{data.get('status')}"
    if kind == "message.send_failed":
        return f"fail:{conn}:{data.get('jobId')}"
    return "body:" + hashlib.sha256(raw_body).hexdigest()  # same event resent = same body


def handle(event: dict) -> None:
    data = event.get("data") or {}
    kind = event.get("type")
    if kind == "message.incoming":
        print("received from", data.get("phone"), data.get("body"))
    elif kind == "message.delivery":
        print("status", data.get("clientRef") or data.get("messageId"), data.get("status"))
    elif kind == "message.send_failed":
        print("will not send", data.get("clientRef"), data.get("reason"))
    # unknown types are ignored: the contract only grows


def process(event: dict, raw_body: bytes, db: sqlite3.Connection | None = None) -> None:
    own = db is None
    db = db or sqlite3.connect("events.db")
    try:
        db.execute("CREATE TABLE IF NOT EXISTS whatsapp_events (event_key TEXT PRIMARY KEY)")
        with db:  # one transaction: the key is only kept if handle() succeeds
            inserted = db.execute(
                "INSERT OR IGNORE INTO whatsapp_events (event_key) VALUES (?)", (event_key(event, raw_body),)
            ).rowcount
            if inserted:
                handle(event)
    finally:
        if own:
            db.close()


def worker() -> None:
    db = sqlite3.connect("events.db")
    while True:
        event, raw_body = events.get()
        try:
            process(event, raw_body, db)
        except Exception as exc:  # log and keep the worker alive
            print("failed to process event:", exc)


threading.Thread(target=worker, daemon=True).start()

Algumas observações sobre a chave:

  • Em message.delivery, o mesmo messageId chega várias vezes, uma para cada status. Por isso o status entra na chave. Trate o status como uma progressão: uma mensagem marcada como read no seu sistema não volta para delivered.
  • Em message.incoming, o identificador da mensagem no WhatsApp está em data.raw.key.id. O campo raw segue o formato do WhatsApp, não o contrato da API: leia dele só o que os outros campos não trazem.
  • Ignore os tipos e campos que você não conhece. O contrato só cresce, com tipos e campos novos, e nunca renomeia nem remove.

A fila em memória serve para aprender, não para produção: um reinício do processo perde o que estava nela, e com vários processos do Gunicorn cada um tem a sua. Em produção, grave o evento numa tabela ou mande para o Celery, o RQ ou o Dramatiq antes de responder o 204, e processe num worker separado com a mesma chave. Se algo der errado mesmo assim, as entregas que esgotaram as tentativas ficam no registro do painel e podem ser reenviadas, uma a uma ou todas de uma vez; com a chave de idempotência, reenviar é seguro. O passo a passo completo está no guia de webhooks do WhatsApp.

O Flask verifica a assinatura e responde 204; o worker grava a chave do evento e só então processa.

Gerar um cliente a partir da OpenAPI 3.1

Para a maioria dos projetos, requests e uma função como send_whatsapp bastam. Se você prefere modelos tipados e autocompletar no editor, a apiwpp publica a especificação OpenAPI 3.1 da API, em português e inglês, e dela dá para gerar um cliente. A apiwpp gera clientes TypeScript e PHP a partir dessa especificação; para Python não há pacote pronto, então você gera o seu com uma ferramenta da comunidade, como o openapi-python-client.

Antes de gerar, remova a seção de webhooks da especificação. Ela descreve os eventos que chegam no seu servidor, e o gerador a transformaria em chamadas que não existem:

curl -s https://docs.apiwpp.com/openapi.json -o openapi.json
jq 'del(.webhooks)' openapi.json > openapi.api.json
pipx run openapi-python-client generate --path openapi.api.json

O resultado é um pacote com uma função por operação e um modelo por corpo de requisição e resposta. Os schemas dos eventos continuam úteis mesmo sem gerar nada: eles documentam cada campo de data, e você pode usá-los para validar os eventos do webhook nos seus testes. A página de OpenAPI e clientes gerados e a referência interativa trazem os detalhes. Para um resumo de envio e recebimento lado a lado, veja a integração com Python.

Como começar hoje

  1. Crie sua conta na apiwpp e conecte o número pelo QR code: o teste de 7 dias não pede cartão.
  2. Crie uma chave de API com o escopo messages:send e guarde em APIWPP_KEY, junto com o id da conexão em APIWPP_CONNECTION_ID.
  3. Rode o send.py para o seu próprio número e confira a resposta 202.
  4. Troque o script pela função send_whatsapp, escolha um clientRef estável para cada tipo de aviso e trate RetryLater na sua fila de tarefas.
  5. Suba o receptor em Flask ou FastAPI atrás de uma URL https, defina o segredo do projeto e atualize seus registros com message.delivery e message.incoming. Quando for hora de mais números, os valores por número estão em preços.

Perguntas frequentes

Qual biblioteca Python uso para enviar mensagem de WhatsApp?

O requests resolve: o envio é um POST com JSON e um cabeçalho de autorização. O httpx funciona igual e tem versão assíncrona, se o seu código já usa asyncio. Não é preciso nenhum SDK específico; um cliente tipado pode ser gerado da especificação OpenAPI 3.1, se você quiser.

Por que a API responde 202 e a mensagem não sai no mesmo segundo?

Porque cada número tem uma fila com ritmo que reduz o risco de bloqueio: por padrão, até 3 mensagens por minuto, com 3 a 8 segundos entre dois envios. O 202 confirma que o envio entrou na fila e traz o horário previsto em scheduledAt. Por isso a API não serve para códigos de verificação que precisam chegar na hora.

Como trato o erro 429 em Python?

Leia o cabeçalho Retry-After, que traz os segundos de espera, e agende o envio para depois em vez de repetir na hora. Com new_recipient_cap_reached, o número atingiu o teto de destinatários novos das últimas 24 horas, e nada entrou na fila. Mensagens para contatos conhecidos continuam sendo aceitas nesse meio tempo.

Como verifico a assinatura do webhook em Python?

Calcule hmac.new(segredo, timestamp + b"." + corpo_bruto, hashlib.sha256).hexdigest(), prefixe com sha256= e compare com o cabeçalho X-Sales-Signature usando hmac.compare_digest. Use os bytes exatos do corpo, recuse timestamps a mais de 300 segundos do seu relógio e recuse tudo se o segredo estiver vazio.

Flask ou FastAPI para receber os webhooks?

Tanto faz para a apiwpp: os dois leem o corpo bruto e respondem rápido. O Flask é mais simples se o seu projeto já é síncrono; o FastAPI tem as BackgroundTasks prontas para processar depois da resposta. Em ambos, o que importa é responder 2xx em até 10 segundos e processar cada evento uma única vez.

Posso usar a apiwpp dentro de um projeto Django?

Sim. A função send_whatsapp funciona igual numa view, num comando de gerenciamento ou numa tarefa do Celery. Para o webhook, crie uma view com csrf_exempt, leia request.body (os bytes brutos) e aplique a mesma função is_signed antes de enfileirar o evento.


Leia também:

Conecte seu primeiro número hoje.

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