Integração WhatsApp eAgenda

O serviço de WhatsApp Web é um programa conectado a um número de WhatsApp. Ele envia as mensagens que o eAgenda pedir e avisa o eAgenda sobre o que acontece com elas. Também repassa ao eAgenda as mensagens que os pacientes escreverem.

O serviço só transporta. Quem decide o que enviar e como responder ao paciente é sempre o eAgenda.

Quem é quem

eAgenda

O sistema de vocês. Chama a API do serviço e recebe os eventos no webhook.

Serviço

O serviço de WhatsApp Web descrito aqui.

Operador

Quem mantém o serviço. Liga e reinicia o serviço, lê o QR code para conectar o número e acompanha mensagens e eventos num painel próprio, que só ele acessa.

Número do serviço

O número de WhatsApp de teste conectado ao serviço pelo WhatsApp Web. É ele que aparece para o paciente.

Celular de teste

O aparelho que faz o papel de paciente nos testes: recebe as mensagens e responde.

Webhook

Um endereço do eAgenda que o serviço chama (POST) para avisar que algo aconteceu.

Este é um ambiente de testes, com um número de teste. Use só celulares de teste e dados fictícios.

O fluxo

chamada à API do serviçowebhook para o eAgendaWhatsAppresposta HTTP

O passo 6 é uma decisão do eAgenda. Se o paciente mandou um áudio, por exemplo, o serviço repassa o evento, com a transcrição, e não faz mais nada. Se o eAgenda quiser responder, faz um novo POST /messages.

As três chamadas

Regras que valem para as três: corpo em JSON UTF-8 com Content-Type: application/json; datas em ISO 8601, em UTC, terminando em Z (2026-11-17T12:31:40Z); telefones só com dígitos, com o DDI, sem + e sem espaço (5538999991234). Campos desconhecidos no JSON são ignorados pelos dois lados, para que campos novos possam ser adicionados sem quebrar nada.

A versão 1.1 do contrato acrescenta áudio nos dois sentidos. O eAgenda pode pedir que uma mensagem saia como mensagem de voz: o serviço gera a fala a partir do texto. E quando o paciente manda um áudio, o serviço transcreve e entrega ao eAgenda só o texto, com um índice de confiança. O arquivo de áudio nunca vai para o eAgenda.

Tudo é compatível com o v1. Os campos novos são opcionais na ida e adicionais na volta. Um eAgenda que segue o v1 e ignora campos desconhecidos continua funcionando sem mudar nada.

Fornecedores: a voz é gerada pelo Google Gemini (modelo gemini-3.8-flash-tts, voz Kore); o operador pode trocar pela OpenAI (gpt-4o-mini-tts). A transcrição é feita pelo OpenAI Whisper (whisper-1). Cada recurso pode estar desligado neste serviço, e o GET /health informa.

A especificação desta extensão, no formato do contrato, está no arquivo EXTENSAO_v1.1_AUDIO.md, entregue junto com o contrato.

Antes do primeiro teste, o operador passa três informações ao eAgenda, e o eAgenda passa uma ao operador.

• Enquanto a URL do webhook não estiver configurada no serviço, os eventos ficam guardados nele, aguardando. Para testar antes de ter o webhook pronto, veja Testar sem o webhook.
• Se o servidor do eAgenda só aceita conexões de endereços conhecidos, peça ao operador o endereço IP de saída do serviço.
• O webhook precisa de um certificado HTTPS válido. Com certificado autoassinado, a entrega falha como erro de rede.
• A referência interativa (Swagger) permite chamar a API pelo navegador: clique em Authorize e cole o token. Cuidado: o envio é de verdade.

Os exemplos usam curl num terminal bash (Linux, macOS ou WSL). Primeiro, guarde o token numa variável. O comando abaixo espera você colar o token e teclar Enter; ele não aparece na tela nem fica no histórico.

read -rs SERVICO_API_TOKEN && export SERVICO_API_TOKEN

Substitua https://SEU-SERVIDOR pelo endereço que o operador do serviço informar.

1. A sessão está conectada?

curl -sS https://SEU-SERVIDOR/health \
  -H "Authorization: Bearer $SERVICO_API_TOKEN" \
  -w '\nHTTP %{http_code}\n'

Resposta esperada:

{"status": "ok", "session": "connected", "phone": "5538988887777", "queue_size": 0, "capabilities": {"send_audio": true, "transcription": true}}

Se session não for connected, avise o operador antes de seguir (veja Estado da sessão). O campo capabilities é da v1.1 e diz se os recursos de áudio estão ligados.

2. Primeira mensagem

Antes de rodar, troque 5538999991234 pelo número do celular de teste e o message_id por um UUID novo. Um message_id já usado neste ambiente recebe 202, mas a mensagem não é enviada de novo. Para gerar um: python3 -c "import uuid; print(uuid.uuid4())".

curl -sS -X POST https://SEU-SERVIDOR/messages \
  -H "Authorization: Bearer $SERVICO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -w '\nHTTP %{http_code}\n' \
  -d '{"message_id":"8d3f6c1e-2b7a-4c59-9e41-0f6a2d9b7c13","to":"5538999991234","text":"Olá Julia Andrade, há uma vaga de atendimento em 20/11/2026 às 14:30 na Policlínica Municipal. Responda SIM para confirmar ou NÃO para cancelar."}'

{"message_id":"8d3f6c1e-2b7a-4c59-9e41-0f6a2d9b7c13","status":"queued"}

3. Os eventos chegam no webhook

Em poucos segundos a mensagem chega no celular de teste. O serviço então avisa o webhook do eAgenda: primeiro sent, depois delivered.

{"event":"message.status","event_id":"0b6f2a1c-3d4e-4f5a-9b8c-7d6e5f4a3b21","message_id":"8d3f6c1e-2b7a-4c59-9e41-0f6a2d9b7c13","status":"sent","error":null,"timestamp":"2026-11-17T12:20:03Z"}
{"event":"message.status","event_id":"5a0c8f3e-91d2-4b7c-a6e5-3f2b1c0d9e81","message_id":"8d3f6c1e-2b7a-4c59-9e41-0f6a2d9b7c13","status":"delivered","error":null,"timestamp":"2026-11-17T12:20:05Z"}

Quando a paciente abre a conversa, chega read. Quando ela responde, chega um message.received:

{"event":"message.received","event_id":"e7b1d0a4-5c2f-4e8a-b3a9-6f1c2d4e5a70","inbound_id":"3EB0C431D5A2F98E6B11","from":"5538999991234","type":"text","text":"Sério? Justo agora, nossa vai ser difícil ir nesse dia, vou ter outra consulta","reply_to_message_id":null,"timestamp":"2026-11-17T12:31:40Z","transcription":null}

O serviço não responde nada. Para responder à paciente, o eAgenda faz outro POST /messages, com um message_id novo:

{"message_id":"1c9e4b2a-7d3f-4f1a-8c6e-2b5d9a0e7f44","to":"5538999991234","text":"Entendo, Julia. Essa outra consulta é no mesmo dia e horário, 20/11/2026 às 14:30? Me confirme se você vai conseguir comparecer à Policlínica Municipal."}

Se ela responder citando essa mensagem (tocar e segurar, depois Responder), o evento traz o message_id dela em reply_to_message_id:

{"event":"message.received","event_id":"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a","inbound_id":"3EB0F7A19C2D4E5B6A70","from":"5538999991234","type":"text","text":"A outra é de manhã, então consigo ir sim","reply_to_message_id":"1c9e4b2a-7d3f-4f1a-8c6e-2b5d9a0e7f44","timestamp":"2026-11-17T12:36:12Z","transcription":null}

Na v1.1, todo message.received termina com o campo transcription: null para texto, preenchido para áudio.

4. Mensagem de voz (v1.1)

Se o GET /health mostrar "send_audio": true, o mesmo pedido com "type": "audio" faz o texto chegar como mensagem de voz. Use outro message_id novo. Antes, confirme que o eAgenda aceitou a mudança de dados pessoais.

curl -sS -X POST https://SEU-SERVIDOR/messages \
  -H "Authorization: Bearer $SERVICO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -w '\nHTTP %{http_code}\n' \
  -d '{"message_id":"b4e2a7c9-0f1d-4e3b-9a6c-5d8e7f2a1b30","to":"5538999991234","type":"audio","text":"Olá Julia Andrade, sua vaga foi confirmada para 20 de novembro às 14 horas e 30 minutos."}'

A resposta é o mesmo 202. A voz é gerada na fila, em alguns segundos, e a paciente recebe só o áudio. Os status chegam como antes.

Recebe um pedido de envio, grava numa fila em disco e responde em menos de 2 segundos. O envio pelo WhatsApp acontece depois, em segundo plano, uma mensagem por vez. O resultado chega pelo webhook message.status.

Requisição

POST https://SEU-SERVIDOR/messages
Authorization: Bearer <SERVICO_API_TOKEN>
Content-Type: application/json

{
  "message_id": "8d3f6c1e-2b7a-4c59-9e41-0f6a2d9b7c13",
  "to": "5538999991234",
  "text": "Olá Julia Andrade, há uma vaga de atendimento em 20/11/2026 às 14:30 na Policlínica Municipal. Responda SIM para confirmar ou NÃO para cancelar."
}

Validação e mensagens de erro

O serviço confere nesta ordem: primeiro o token, depois se o corpo é JSON, depois os campos. Sem token, a resposta é 401 mesmo que o JSON esteja quebrado. Os campos são conferidos na ordem message_id, to, text e type, e a resposta aponta o primeiro problema. As mensagens seguem o formato "<campo>: <motivo>".

Decida pelo error.code. O error.message é para pessoas lerem nos logs. O aviso de áudio desligado só vem para um message_id novo: um message_id já aceito recebe 202, como no v1.

Respostas

Quando tentar de novo

Repita o pedido só em 429, 500, 502, 503, 504, timeout ou erro de rede. No máximo 5 tentativas no total, sempre com o mesmo message_id. O intervalo entre elas fica a critério do eAgenda; esperas crescentes (2, 4, 8 e 16 s) funcionam bem. Corte cada chamada em 10 segundos.

Por que repetir o mesmo message_id é seguro

O serviço guarda cada message_id recebido por 7 dias. Se o mesmo message_id chegar de novo, ele responde 202 com o mesmo corpo e não enfileira outra vez. O paciente recebe a mensagem no máximo uma vez.

Isso resolve o caso mais comum: o serviço aceitou o pedido, mas a resposta se perdeu no caminho. O eAgenda não sabe se deu certo e repete. Com o mesmo message_id, não sai mensagem dobrada.

O 503, explicado

O 503 session_unavailable quer dizer que nenhuma mensagem consegue sair agora e que o pedido não foi aceito. Acontece quando a sessão do WhatsApp está em qr_required ou disconnected. Só o operador resolve, lendo o QR code no painel dele.

• Em connecting (serviço iniciando ou reconectando), o pedido é aceito. Se a mensagem ficar mais de 30 minutos na fila sem conseguir sair, o serviço desiste e manda message.status failed com error.code session_unavailable.
• Um message_id que já foi aceito recebe 202 com o mesmo corpo, mesmo com a sessão fora do ar.

Enviar em áudio (v1.1)

Com "type": "audio", o text é o que será falado. O serviço gera a voz, converte para o formato de mensagem de voz do WhatsApp e envia. O paciente recebe só o áudio, sem o texto escrito.

{
  "message_id": "b4e2a7c9-0f1d-4e3b-9a6c-5d8e7f2a1b30",
  "to": "5538999991234",
  "type": "audio",
  "text": "Olá Julia Andrade, sua vaga foi confirmada para 20 de novembro às 14 horas e 30 minutos."
}

• Confira antes capabilities.send_audio no GET /health. Com o envio em áudio desligado, a resposta é 400 com type: envio de áudio não está habilitado neste serviço. Nesse caso, envie como texto, com um message_id novo.
• O text segue as mesmas regras: de 1 a 4096 caracteres. Texto longo vira áudio longo; prefira frases curtas.
• A resposta 202 continua imediata. A voz é gerada na fila e leva alguns segundos (em teste, cerca de 5 s para uma frase), além do intervalo de 3 s entre envios.
• Idempotência igual à do v1: o mesmo message_id gera no máximo um envio.
• Status iguais: sent, delivered, read e failed. Aqui, read sai quando o paciente abre a conversa ou ouve o áudio, o que vier primeiro.
• Se a voz não puder ser gerada depois de 3 tentativas, chega failed com error.code tts_failed, e nada é enviado. Um número sem WhatsApp é detectado antes de gerar a voz e recebe not_on_whatsapp, como no v1.
• Se o paciente responder citando a mensagem de voz, reply_to_message_id traz o message_id dela, como no v1.

Escreva como se fala

Exemplo em Python

Um cliente com as regras acima, usando requests. O parâmetro tipo é da v1.1; um serviço v1 ignora o campo type. Rode numa tarefa em segundo plano (Celery, RQ ou similar), e não dentro da requisição de um usuário: com as esperas, pode levar cerca de 30 segundos para desistir.

import os
import time

import requests

SERVICO_BASE_URL = os.environ["SERVICO_BASE_URL"]  # ex.: https://SEU-SERVIDOR
SERVICO_API_TOKEN = os.environ["SERVICO_API_TOKEN"]
REPETIR_EM = {429, 500, 502, 503, 504}  # 400 e 401 são definitivos


class EnvioRecusado(Exception):
    """400 ou 401: repetir o mesmo pedido não adianta."""


class ServicoIndisponivel(Exception):
    """5 tentativas sem 202. Tentar mais tarde com o MESMO message_id é seguro."""


def enviar_mensagem(message_id, to, text, tipo="text"):
    """message_id: UUID v4 novo por mensagem, já gravado junto do agendamento.
    tipo: "text" ou "audio" (v1.1; confira capabilities.send_audio no /health)."""
    corpo = {"message_id": message_id, "to": to, "text": text, "type": tipo}
    cabecalhos = {"Authorization": f"Bearer {SERVICO_API_TOKEN}"}
    for tentativa in range(1, 6):  # até 5 tentativas no total
        try:
            r = requests.post(f"{SERVICO_BASE_URL}/messages", json=corpo,
                              headers=cabecalhos, timeout=10)
        except requests.RequestException:  # timeout ou erro de rede
            r = None
        if r is not None and r.status_code == 202:
            return r.json()  # {"message_id": "...", "status": "queued"}
        if r is not None and r.status_code not in REPETIR_EM:
            raise EnvioRecusado(f"HTTP {r.status_code}: {r.text}")
        if tentativa < 5:
            time.sleep(2 ** tentativa)  # 2, 4, 8 e 16 s
    raise ServicoIndisponivel(message_id)

Informa se o serviço consegue enviar mensagens agora. Exige o mesmo token (sem ele, 401). Responde 200 sempre que o serviço estiver no ar, mesmo com o WhatsApp desconectado.

GET https://SEU-SERVIDOR/health
Authorization: Bearer <SERVICO_API_TOKEN>

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok",
  "session": "connected",
  "phone": "5538988887777",
  "queue_size": 0,
  "capabilities": { "send_audio": true, "transcription": true }
}

O que cada session significa na prática

• Não é preciso chamar /health antes de cada envio: o POST /messages já responde 503 quando não dá para aceitar. Use /health para mostrar o estado numa tela de administração do eAgenda ou antes de um lote de envios.
• Antes de usar áudio, confira capabilities. Com send_audio: false, um POST /messages com "type": "audio" recebe 400. Com transcription: false, os áudios dos pacientes chegam com transcription.status: "disabled".
• queue_size alto quer dizer espera. Com 3 segundos entre envios, 20 mensagens na fila levam cerca de 1 minuto para sair.
• Fora do contrato, o serviço também tem GET /livez, sem token, que responde {"status":"ok"} enquanto o processo está no ar. Serve para monitoramento.

O serviço avisa o eAgenda fazendo POST na URL do webhook. Cada requisição leva um único evento. O campo event diz o tipo: message.status ou message.received. Quem implementa este endereço é o eAgenda.

POST https://<host-do-eagenda>/api/v1/whatsapp/bot/webhook/
Content-Type: application/json
X-Bot-Timestamp: 1794918701
X-Bot-Signature: sha256=d59dad4a2d1ae928440d0131e40041488424773bf3775df19222b5540389f5d3

{"event":"message.received","event_id":"e7b1d0a4-5c2f-4e8a-b3a9-6f1c2d4e5a70","inbound_id":"3EB0C431D5A2F98E6B11","from":"5538999991234","type":"text","text":"Sério? Justo agora, nossa vai ser difícil ir nesse dia, vou ter outra consulta","reply_to_message_id":null,"timestamp":"2026-11-17T12:31:40Z"}

Na v1.1, o corpo de message.received traz também o campo transcription, no fim. O exemplo acima é o corpo do vetor de teste do v1, que continua valendo: a assinatura funciona do mesmo jeito para qualquer corpo.

Como verificar a assinatura

A assinatura prova que o evento veio do serviço e não foi alterado no caminho. É um HMAC-SHA256: um código calculado com o WEBHOOK_SECRET sobre o timestamp e o corpo. Só quem tem o segredo consegue produzir a assinatura certa.

mensagem  = X-Bot-Timestamp + "." + corpo da requisição (bytes exatos)
esperado  = "sha256=" + hex( HMAC_SHA256(chave = WEBHOOK_SECRET, mensagem) )

1. Leia o corpo bruto, em bytes, antes de qualquer conversão. No Django é request.body.
2. Confira o X-Bot-Timestamp: só dígitos e no máximo 300 segundos de diferença do seu relógio, para mais ou para menos. Fora disso, responda 401. Isso impede que alguém reaproveite um evento antigo capturado.
3. Calcule a assinatura esperada e compare com o X-Bot-Signature usando comparação de tempo constante (hmac.compare_digest no Python). Diferente, 401.
4. Só então leia o JSON. JSON inválido ou campo obrigatório faltando, 400.
5. Se o event_id (ou, em message.received, o inbound_id) já foi recebido, responda 200 e não processe de novo.
6. Guarde o evento e responda 200 {"status": "ok"} em menos de 10 segundos. Processe depois, fora da requisição.

Como o eAgenda responde

Responda 400 só quando o corpo estiver de fato malformado. Para qualquer problema passageiro do lado do eAgenda (banco fora do ar, deploy em andamento), responda 5xx: o serviço tenta de novo. Um 400 encerra a entrega daquele evento.

Vetor de teste

Use estes valores fixos num teste automatizado. Se a sua verificação aceita este corpo com esta assinatura, e recusa o mesmo corpo com um único byte trocado, ela está certa.

WEBHOOK_SECRET  = segredo-de-exemplo
X-Bot-Timestamp = 1794918701
corpo           = {"event":"message.received","event_id":"e7b1d0a4-5c2f-4e8a-b3a9-6f1c2d4e5a70","inbound_id":"3EB0C431D5A2F98E6B11","from":"5538999991234","type":"text","text":"Sério? Justo agora, nossa vai ser difícil ir nesse dia, vou ter outra consulta","reply_to_message_id":null,"timestamp":"2026-11-17T12:31:40Z"}
X-Bot-Signature = sha256=d59dad4a2d1ae928440d0131e40041488424773bf3775df19222b5540389f5d3

Para conferir o cálculo, rode este trecho. Ele deve imprimir exatamente o X-Bot-Signature acima. O corpo é uma linha só, sem espaços entre os campos, com os acentos em UTF-8.

import hashlib, hmac
segredo = b"segredo-de-exemplo"
ts = b"1794918701"
corpo = '{"event":"message.received","event_id":"e7b1d0a4-5c2f-4e8a-b3a9-6f1c2d4e5a70","inbound_id":"3EB0C431D5A2F98E6B11","from":"5538999991234","type":"text","text":"Sério? Justo agora, nossa vai ser difícil ir nesse dia, vou ter outra consulta","reply_to_message_id":null,"timestamp":"2026-11-17T12:31:40Z"}'.encode("utf-8")
print("sha256=" + hmac.new(segredo, ts + b"." + corpo, hashlib.sha256).hexdigest())

Exemplo completo em Django

Um app whatsapp com quatro partes: o modelo que guarda cada evento uma vez, a view que verifica e responde, a rota e o teste com o vetor. A view só guarda o evento; o processamento (atualizar o agendamento, decidir a resposta ao paciente) roda depois, fora da requisição.

import os

WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]  # combinado com o operador; não é o SERVICO_API_TOKEN

from django.db import models


class EventoWhatsApp(models.Model):
    """Caixa de entrada do webhook. Cada evento é guardado uma única vez."""

    event_id = models.CharField(max_length=64, unique=True)
    inbound_id = models.CharField(max_length=128, unique=True, null=True, blank=True)
    tipo = models.CharField(max_length=32)  # message.status | message.received
    payload = models.JSONField()
    recebido_em = models.DateTimeField(auto_now_add=True)
    processado_em = models.DateTimeField(null=True, blank=True)

import hashlib
import hmac
import json
import logging
from time import time as agora

from django.conf import settings
from django.db import IntegrityError, transaction
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST

from .models import EventoWhatsApp

log = logging.getLogger(__name__)

JANELA_SEGUNDOS = 300  # timestamps com mais de 300 s de diferença são recusados

CAMPOS_OBRIGATORIOS = {
    "message.status": ("event_id", "message_id", "status", "timestamp"),
    "message.received": ("event_id", "inbound_id", "from", "type", "timestamp"),
}


def assinatura_valida(segredo, timestamp, corpo, recebida):
    mensagem = timestamp.encode("ascii") + b"." + corpo
    esperada = "sha256=" + hmac.new(segredo.encode("utf-8"), mensagem, hashlib.sha256).hexdigest()
    # Compara em tempo constante. Em bytes, para não quebrar com cabeçalho não ASCII.
    return hmac.compare_digest(esperada.encode("ascii"), recebida.encode("utf-8"))


def erro(status, code, message=None):
    corpo = {"code": code}
    if message:
        corpo["message"] = message
    return JsonResponse({"error": corpo}, status=status)


@csrf_exempt  # o serviço não tem sessão nem token CSRF; a assinatura faz esse papel
@require_POST
def webhook_whatsapp(request):
    timestamp = request.headers.get("X-Bot-Timestamp", "")
    assinatura = request.headers.get("X-Bot-Signature", "")
    corpo = request.body  # bytes exatos. Não use json.dumps(...) para verificar.

    # 1. Timestamp: só dígitos e no máximo 300 s de diferença do relógio local
    if not (timestamp.isascii() and timestamp.isdigit()):
        return erro(401, "invalid_signature")
    if abs(agora() - int(timestamp)) > JANELA_SEGUNDOS:
        return erro(401, "invalid_signature")

    # 2. Assinatura
    if not assinatura_valida(settings.WEBHOOK_SECRET, timestamp, corpo, assinatura):
        return erro(401, "invalid_signature")

    # 3. JSON e campos obrigatórios. Atenção: com 400 o serviço NÃO reenvia.
    try:
        evento = json.loads(corpo)
    except ValueError:
        return erro(400, "invalid_payload", "corpo: JSON inválido")
    if not isinstance(evento, dict) or not evento.get("event"):
        return erro(400, "invalid_payload", "event: obrigatório")
    tipo = evento["event"]
    if tipo not in CAMPOS_OBRIGATORIOS:
        log.warning("webhook: tipo de evento desconhecido %r, ignorado", tipo)
        return JsonResponse({"status": "ok"})  # tipos novos podem surgir em versões futuras
    faltando = [campo for campo in CAMPOS_OBRIGATORIOS[tipo] if not evento.get(campo)]
    if faltando:
        return erro(400, "invalid_payload", f"{faltando[0]}: obrigatório")

    # 4. Guarda uma vez só: event_id e inbound_id são UNIQUE no banco
    try:
        with transaction.atomic():
            EventoWhatsApp.objects.create(
                event_id=evento["event_id"],
                inbound_id=evento["inbound_id"] if tipo == "message.received" else None,
                tipo=tipo,
                payload=evento,
            )
    except IntegrityError:
        pass  # repetido: já estava guardado; responda 200 de novo
    except Exception:
        log.exception("webhook: falha ao gravar event_id=%s", evento["event_id"])
        return erro(500, "internal_error")  # o serviço vai reenviar

    # 5. Responda rápido (limite de 10 s). Processe os eventos fora da requisição.
    return JsonResponse({"status": "ok"})

from django.urls import path

from whatsapp.views import webhook_whatsapp

urlpatterns = [
    # Com a barra final. Sem ela, o Django redireciona (301) e o serviço não segue.
    path("api/v1/whatsapp/bot/webhook/", webhook_whatsapp, name="whatsapp-webhook"),
]

from unittest import mock

from django.test import TestCase, override_settings

from .models import EventoWhatsApp

URL = "/api/v1/whatsapp/bot/webhook/"
TS = "1794918701"
ASSINATURA = "sha256=d59dad4a2d1ae928440d0131e40041488424773bf3775df19222b5540389f5d3"
CORPO = '{"event":"message.received","event_id":"e7b1d0a4-5c2f-4e8a-b3a9-6f1c2d4e5a70","inbound_id":"3EB0C431D5A2F98E6B11","from":"5538999991234","type":"text","text":"Sério? Justo agora, nossa vai ser difícil ir nesse dia, vou ter outra consulta","reply_to_message_id":null,"timestamp":"2026-11-17T12:31:40Z"}'.encode("utf-8")


@override_settings(WEBHOOK_SECRET="segredo-de-exemplo")
@mock.patch("whatsapp.views.agora", return_value=1794918701)
class VetorDeTesteDoContrato(TestCase):
    def enviar(self, corpo=CORPO, ts=TS, assinatura=ASSINATURA):
        return self.client.post(
            URL, data=corpo, content_type="application/json",
            HTTP_X_BOT_TIMESTAMP=ts, HTTP_X_BOT_SIGNATURE=assinatura,
        )

    def test_vetor_e_aceito(self, relogio):
        resposta = self.enviar()
        self.assertEqual(resposta.status_code, 200)
        self.assertEqual(resposta.json(), {"status": "ok"})

    def test_repetido_responde_200_e_guarda_uma_vez(self, relogio):
        self.enviar()
        self.assertEqual(self.enviar().status_code, 200)
        self.assertEqual(EventoWhatsApp.objects.count(), 1)

    def test_um_byte_diferente_da_401(self, relogio):
        resposta = self.enviar(corpo=CORPO.replace(b"Justo", b"justo"))
        self.assertEqual(resposta.status_code, 401)

    def test_timestamp_fora_da_janela_da_401(self, relogio):
        relogio.return_value = 1794918701 + 301
        self.assertEqual(self.enviar().status_code, 401)

python manage.py makemigrations whatsapp && python manage.py migrate
python manage.py test whatsapp

• csrf_exempt: o serviço não tem sessão nem token CSRF do Django. A assinatura HMAC cumpre esse papel.
• Deduplicação: as restrições UNIQUE no banco garantem que duas entregas simultâneas do mesmo evento não gravem duas linhas. Checar antes e inserir depois não garante isso.
• Processamento: leia as linhas com processado_em vazio numa tarefa (Celery, RQ ou um comando agendado), em ordem de id. Assim a resposta sai rápido e um erro na regra de negócio não vira reentrega.
• Django REST Framework: se usar, leia request.body antes de tocar em request.data (depois dele, request.body dá erro) e não use SessionAuthentication nesta rota. A view simples acima evita os dois problemas.
• Tipo de evento desconhecido: o exemplo responde 200 e ignora, para não travar a entrega se uma versão futura trouxer um tipo novo. Esse comportamento é uma sugestão deste guia; o contrato não define o caso.
• Extensão de áudio (v1.1): a view não muda. O campo transcription fica guardado no payload e é lido no processamento; veja ler_resposta.

Exemplo em Node.js (Express)

Se o receptor for em Node.js, use express.raw nesta rota: ele entrega o corpo como Buffer, com os bytes exatos. O express.json() descarta os bytes originais e a assinatura deixa de bater. O exemplo só lê os ids do evento, então funciona igual na v1.1.

import crypto from "node:crypto";
import express from "express";

const app = express();
const JANELA_SEGUNDOS = 300;
const vistos = new Set(); // só para o exemplo; em produção, UNIQUE no banco

function assinaturaValida(segredo, timestamp, corpo, recebida) {
  const esperada = "sha256=" + crypto
    .createHmac("sha256", segredo)
    .update(`${timestamp}.`)
    .update(corpo) // Buffer: os bytes exatos recebidos
    .digest("hex");
  const a = Buffer.from(esperada);
  const b = Buffer.from(String(recebida));
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw, não express.json: a assinatura é sobre os bytes originais
app.post("/api/v1/whatsapp/bot/webhook/", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-Bot-Timestamp") ?? "";
  const assinatura = req.get("X-Bot-Signature") ?? "";
  const corpo = req.body;

  const relogioOk = /^\d+$/.test(timestamp)
    && Math.abs(Date.now() / 1000 - Number(timestamp)) <= JANELA_SEGUNDOS;
  if (!relogioOk || !Buffer.isBuffer(corpo)
      || !assinaturaValida(process.env.WEBHOOK_SECRET, timestamp, corpo, assinatura)) {
    return res.status(401).json({ error: { code: "invalid_signature" } });
  }

  let evento;
  try {
    evento = JSON.parse(corpo.toString("utf8"));
  } catch {
    return res.status(400).json({ error: { code: "invalid_payload", message: "corpo: JSON inválido" } });
  }
  if (!evento?.event || !evento.event_id) {
    return res.status(400).json({ error: { code: "invalid_payload", message: "event_id: obrigatório" } });
  }

  const chaves = [evento.event_id, evento.inbound_id].filter(Boolean);
  if (!chaves.some((k) => vistos.has(k))) {
    chaves.forEach((k) => vistos.add(k));
    // guarde o evento para processar fora da requisição
  }
  res.json({ status: "ok" }); // repetido também recebe 200
});

app.listen(process.env.PORT ?? 8000);

Evento message.status

Chega quando o status de uma mensagem enviada a pedido do eAgenda muda.

{
  "event": "message.status",
  "event_id": "5a0c8f3e-91d2-4b7c-a6e5-3f2b1c0d9e81",
  "message_id": "8d3f6c1e-2b7a-4c59-9e41-0f6a2d9b7c13",
  "status": "delivered",
  "error": null,
  "timestamp": "2026-11-17T12:20:05Z"
}

Os tiques do WhatsApp, em status

Cada status corresponde ao que se vê na bolha da mensagem, do lado de quem envia.

• 12:20

  queued

  Relógio. Na fila do serviço. É a resposta do POST /messages, não um evento.

• 12:20

  sent

  Um tique cinza. Saiu para o servidor do WhatsApp (ACK_SERVER, 1).

• 12:20

  delivered

  Dois tiques cinza. Chegou no aparelho do paciente (ACK_DEVICE, 2).

• 12:20

  read

  Dois tiques azuis. O paciente abriu a conversa (ACK_READ, 3) ou ouviu a mensagem de voz (ACK_PLAYED, 4).

• 12:20

  failed

  Erro (ACK_ERROR, -1), ou o serviço desistiu. Vem com error.code.

Regras

• Cada status chega no máximo uma vez por mensagem. Os status de uma mesma mensagem chegam em ordem.
• Se o WhatsApp pular etapas (por exemplo, a confirmação de leitura chega antes da de entrega), o serviço emite as que faltaram, em ordem (sent → delivered → read), todas com o mesmo timestamp.
• Depois de failed, nada mais chega para aquele message_id.
• Mensagem de voz (v1.1): read sai quando o paciente abre a conversa ou ouve o áudio, o que vier primeiro.
• Falha passageira (sessão reconectando, timeout) não vira failed. O serviço mantém a mensagem na fila e tenta de novo. Só manda failed quando desiste.
• read pode nunca chegar: se o paciente desligou as confirmações de leitura no WhatsApp, a leitura não é informada. delivered demora se o celular do paciente estiver desligado ou sem internet. Não trate a falta deles como erro.
• O eAgenda pode receber status de um message_id que não conhece, como o de uma mensagem de teste que o operador mandou pelo painel. Responda 200 e ignore.

Códigos de erro

{
  "event": "message.status",
  "event_id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
  "message_id": "8d3f6c1e-2b7a-4c59-9e41-0f6a2d9b7c13",
  "status": "failed",
  "error": { "code": "not_on_whatsapp", "message": "número não registrado no WhatsApp" },
  "timestamp": "2026-11-17T12:20:02Z"
}

Evento message.received

Chega para cada mensagem que alguém mandar ao número do serviço numa conversa individual. O conteúdo vem como chegou, sem interpretação.

{
  "event": "message.received",
  "event_id": "e7b1d0a4-5c2f-4e8a-b3a9-6f1c2d4e5a70",
  "inbound_id": "3EB0C431D5A2F98E6B11",
  "from": "5538999991234",
  "type": "text",
  "text": "Sério? Justo agora, nossa vai ser difícil ir nesse dia, vou ter outra consulta",
  "reply_to_message_id": null,
  "timestamp": "2026-11-17T12:31:40Z",
  "transcription": null
}

Tipos

O serviço não repassa arquivos. De uma mídia, o eAgenda recebe só o tipo e a legenda, se houver. De um áudio, recebe a transcrição: veja Transcrição de áudio.

Respostas citadas

Quando o paciente toca e segura uma mensagem e escolhe Responder, a mensagem dele “cita” a original. Se a citada foi enviada a pedido do eAgenda, reply_to_message_id traz o message_id dela. É a ligação mais segura entre a resposta e o agendamento. Sem citação, ou citando outra mensagem, vem null.

O telefone em from e o nono dígito

O WhatsApp às vezes registra celulares brasileiros sem o 9 depois do DDD. Por isso from pode vir como 553899991234, mesmo que o eAgenda tenha enviado para 5538999991234. Compare telefones depois de normalizar os dois lados:

def normalizar_celular(numero):
    """Põe um celular brasileiro na forma com 13 dígitos (com o nono dígito)."""
    d = "".join(c for c in numero if c in "0123456789")
    if len(d) == 12 and d.startswith("55") and d[4] in "6789":
        return d[:4] + "9" + d[4:]  # 553899991234 -> 5538999991234
    return d


assert normalizar_celular("553899991234") == "5538999991234"
assert normalizar_celular("5538999991234") == "5538999991234"

Quando o WhatsApp entrega só um identificador interno no lugar do telefone, o serviço converte para o telefone. Se não conseguir, o evento não é enviado e o caso fica registrado no log do serviço.

Qualquer pessoa pode escrever para o número do serviço. Um from que não corresponde a nenhum paciente deve ser tratado (por exemplo, ignorado e registrado), nunca respondido com erro.

O que não gera evento

• Mensagens enviadas pelo próprio serviço.
• Grupos, status, canais e listas de transmissão.
• Mensagens de sistema, chamadas de voz ou vídeo, reações, edições e mensagens apagadas.

Transcrição de áudio (v1.1)

Quando o paciente manda um áudio, o serviço baixa o arquivo para a memória, envia ao OpenAI Whisper e põe o resultado no campo transcription. O arquivo de áudio nunca vai para o eAgenda. Como no v1, type continua "audio" e text continua null; o que foi falado vem em transcription.text.

{
  "event": "message.received",
  "event_id": "4c3b2a19-8f7e-4d6c-9b5a-0e1f2d3c4b5a",
  "inbound_id": "3EB01D2E3F4A5B6C7D80",
  "from": "5538999991234",
  "type": "audio",
  "text": null,
  "reply_to_message_id": null,
  "timestamp": "2026-11-17T12:33:05Z",
  "transcription": {
    "status": "ok",
    "text": "A outra consulta é de manhã, então consigo ir sim.",
    "confidence": 0.91,
    "language": "pt",
    "duration_seconds": 6.4,
    "provider": "openai/whisper-1"
  }
}

Uma falha na transcrição não segura nada: o evento sai assim mesmo, com status: "failed". O evento de um áudio espera a transcrição antes de sair, o que leva alguns segundos. As mensagens seguintes do mesmo paciente esperam junto, para manter a ordem; as de outros pacientes, não.

Como a confiança é calculada

O Whisper divide o áudio em trechos e informa, para cada um, quão seguro estava. A confiança junta esses números num só, de 0 a 1:

para cada trecho:
  p = (avg_logprob + 1,0) / 0,85, limitado entre 0 e 1
      (−0,15 ou mais → 1;  −1,0 ou menos → 0;  linear entre os dois)
  se no_speech_prob > 0,5:     p = p × (1 − no_speech_prob)
  se compression_ratio > 2,4:  p = p × 0,5

confiança = média de p, ponderada pela duração de cada trecho
            (duas casas decimais; sem nenhum trecho, 0)

• avg_logprob: a média do logaritmo da probabilidade que o modelo deu às palavras do trecho. Quanto mais perto de 0, mais seguro. A escala leva −0,15 ou mais a 1 e −1,0 ou menos a 0; abaixo de −1,0, o próprio Whisper considera a transcrição ruim.
• no_speech_prob: a chance de o trecho ser só silêncio ou ruído. Só desconta acima de 0,5, o mesmo critério que o Whisper usa para silêncio; abaixo disso, não pesa.
• compression_ratio > 2,4: o texto do trecho se repete de forma anormal, sinal de que o modelo “alucinou”. A probabilidade cai pela metade.
• Trechos mais longos pesam mais na média.

A escala existe porque o Whisper raramente passa de 0,8 de probabilidade média, mesmo acertando tudo, e porque a chance de “não ter fala” sai alta em áudios curtos de celular, mesmo com fala clara. Medido com voz real: fala limpa, transcrita sem erro (avg_logprob −0,26), deu 0,87, margem alta; a mesma voz sob ruído forte, transcrita errado (avg_logprob −0,66, no_speech_prob 0,28), deu 0,40, margem baixa.

A confiança mede a segurança do modelo e não garante o acerto. Um áudio claro pode ter confiança alta e ainda trocar um nome próprio.

Margem de confiança para o atendimento

Faixas sugeridas para decidir o que fazer com uma resposta em áudio. A decisão final é do eAgenda.

Sem transcrição útil (failed, too_long, disabled ou áudio sem fala), faça o mesmo que na margem baixa: peça a resposta por escrito ou encaminhe para atendimento humano.

No código do eAgenda

A view do webhook não muda: transcription fica guardado no payload. No processamento, esta função lê a resposta do paciente nos dois formatos, v1 e v1.1, e devolve a margem. Ela tem testes para as três faixas e para os casos sem transcrição.

"""Lê o que o paciente respondeu, com ou sem a extensão de áudio (v1.1)."""

ALTA = 0.80  # faixas da margem de confiança para o atendimento
MEDIA = 0.60


def ler_resposta(evento):
    """Devolve (texto, margem) de um message.received.

    margem:
      "escrito"                  o paciente digitou (texto, ou legenda de uma mídia)
      "alta" / "media" / "baixa" áudio transcrito, conforme a confiança
      None                       nada para ler (mídia sem legenda, áudio sem transcrição útil)
    Funciona com eventos do v1 (sem o campo transcription) e do v1.1.
    """
    if evento["type"] != "audio":
        texto = evento.get("text")
        return (texto, "escrito") if texto else (None, None)

    t = evento.get("transcription")  # ausente no v1
    if not t or t.get("status") != "ok" or not (t.get("text") or "").strip():
        return None, None  # failed, too_long, disabled, ou áudio sem fala
    if t["confidence"] >= ALTA:
        return t["text"], "alta"
    if t["confidence"] >= MEDIA:
        return t["text"], "media"
    return t["text"], "baixa"

O serviço insiste até o evento ser entregue. A fila de reenvio fica em disco: nada se perde se ele reiniciar.

Redirecionamentos (301, 302, 308) não são seguidos: contam como falha. O caso típico é a URL do Django sem a barra final.

Intervalos entre as tentativas

1. 1ªna hora0 s
2. 2ª+10 s10 s
3. 3ª+1 min1 min 10 s
4. 4ª+5 min6 min 10 s
5. 5ª+15 min21 min 10 s
6. 6ª, a última+1 h1 h 21 min 10 s

A linha de baixo soma os intervalos desde a primeira tentativa (sem contar o tempo de cada chamada). Se a 6ª tentativa falhar, o serviço desiste e registra no log. Um evento abandonado não volta a ser enviado. Se o webhook do eAgenda ficar fora do ar por mais tempo que isso, os eventos que esgotarem as 6 tentativas se perdem para o eAgenda.

Ordem

• As mensagens de um mesmo paciente (message.received) chegam na ordem em que ele escreveu.
• Os status de uma mesma mensagem chegam em ordem.
• Um áudio do paciente espera a transcrição (alguns segundos) antes de sair. As mensagens seguintes do mesmo paciente esperam junto; as de outros pacientes, não.
• Um evento aguardando reenvio segura os seguintes da mesma fila. Se o eAgenda responde 500 à primeira mensagem de um paciente, a segunda só é enviada depois que a primeira for entregue (ou abandonada).
• Entre filas diferentes não há ordem garantida. Um message.received pode chegar antes do delivered da mensagem que ele cita. Não dependa disso.

Consequência: um erro persistente no processamento de um evento atrasa todos os seguintes daquele paciente por até cerca de 1 h 21 min. Por isso o exemplo em Django guarda primeiro e processa depois.

Idempotência do lado do eAgenda

• Um evento pode chegar mais de uma vez. Isso acontece quando o eAgenda processou, mas a resposta 200 se perdeu ou demorou mais de 10 s.
• Processe cada event_id uma vez e cada inbound_id uma vez. A um evento repetido, responda 200 de novo.
• Garanta isso com restrições UNIQUE no banco, como no exemplo em Django.
• Ao aplicar status, só avance: sent → delivered → read. failed é final.

O serviço tem um eAgenda simulado: a rota POST /sandbox/webhook. Ela verifica assinatura e timestamp como o eAgenda faria e responde exatamente como na tabela de respostas do webhook. Para usar, o operador aponta a URL do webhook para ela:

EAGENDA_WEBHOOK_URL=https://SEU-SERVIDOR/sandbox/webhook

Com isso, o eAgenda já pode chamar POST /messages de verdade e o celular de teste já pode responder. No painel, o operador vê cada evento que o serviço gerou: o JSON completo, se a assinatura bateu, a diferença de relógio, se era repetido e o que foi respondido. Na v1.1, esse corpo inclui a transcrição dos áudios, que no sandbox fica só em memória. Peça ao operador cópias desses corpos para usar nos testes do lado do eAgenda.

Modos de falha

O operador escolhe no painel como o sandbox responde. Cada modo exercita um caminho da reentrega.

Testar o webhook do eAgenda sem o serviço

Para testar o lado do eAgenda sozinho, este script faz o papel do serviço. Ele assina um message.received com o seu WEBHOOK_SECRET e o envia duas vezes, com timestamp e assinatura novos, como num reenvio. O esperado: 200 nas duas e uma única linha no banco. Ele não segue redirecionamentos, como o serviço. Só usa a biblioteca padrão do Python. Com audio como segundo argumento, ele manda um áudio já transcrito, no formato da v1.1.

"""Faz o papel do serviço: assina um message.received e envia ao seu webhook.

Uso: WEBHOOK_SECRET='...' python3 enviar_evento_teste.py URL_DO_WEBHOOK [texto|audio]
"""
import hashlib
import hmac
import json
import os
import sys
import time
import urllib.error
import urllib.request
import uuid

URL = sys.argv[1]
TIPO = sys.argv[2] if len(sys.argv) > 2 else "texto"
SEGREDO = os.environ["WEBHOOK_SECRET"]


class SemRedirecionar(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, *args, **kwargs):
        return None  # o serviço também não segue redirecionamentos


abrir = urllib.request.build_opener(SemRedirecionar).open

evento = {
    "event": "message.received",
    "event_id": str(uuid.uuid4()),
    "inbound_id": "TESTE" + uuid.uuid4().hex[:15].upper(),
    "from": "5538999991234",
    "type": "text",
    "text": "Sério? Justo agora, nossa vai ser difícil ir nesse dia",
    "reply_to_message_id": None,
    "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
    "transcription": None,  # v1.1: sempre presente; null quando não é áudio
}
if TIPO == "audio":
    evento.update(type="audio", text=None, transcription={
        "status": "ok",
        "text": "A outra consulta é de manhã, então consigo ir sim.",
        "confidence": 0.91,
        "language": "pt",
        "duration_seconds": 6.4,
        "provider": "openai/whisper-1",
    })
corpo = json.dumps(evento, ensure_ascii=False, separators=(",", ":")).encode("utf-8")  # UMA vez

for tentativa in (1, 2):  # a 2ª simula um reenvio: mesmo corpo, timestamp e assinatura novos
    ts = str(int(time.time()))
    assinatura = "sha256=" + hmac.new(SEGREDO.encode("utf-8"), ts.encode() + b"." + corpo, hashlib.sha256).hexdigest()
    pedido = urllib.request.Request(URL, data=corpo, method="POST", headers={
        "Content-Type": "application/json",
        "X-Bot-Timestamp": ts,
        "X-Bot-Signature": assinatura,
    })
    try:
        with abrir(pedido, timeout=10) as resposta:
            print(f"tentativa {tentativa}: HTTP {resposta.status} {resposta.read().decode()}")
    except urllib.error.HTTPError as e:
        print(f"tentativa {tentativa}: HTTP {e.code} {e.read().decode()[:200]}")
    time.sleep(1)

read -rs WEBHOOK_SECRET && export WEBHOOK_SECRET
python3 enviar_evento_teste.py http://localhost:8000/api/v1/whatsapp/bot/webhook/
python3 enviar_evento_teste.py http://localhost:8000/api/v1/whatsapp/bot/webhook/ audio

Os testes 1 a 15 são os do contrato v1; os testes 16 a 18 são da extensão de áudio (v1.1). A integração está pronta quando todos passam. Façam juntos, numa chamada: o eAgenda chama a API e acompanha o webhook, o operador acompanha o painel e alguém fica com o celular de teste na mão.

Quem faz:eAgendaOperadorCelular de teste

1. Teste 1POST /messages sem token responde 401. Com token errado, 401.

   eAgenda

   Chame sem o cabeçalho Authorization e depois com Bearer errado. As duas respostas: 401 com {"error": {"code": "unauthorized", "message": "token inválido"}}.

2. Teste 2POST /messages com to de 10 dígitos responde 400 invalid_payload.

   eAgenda

   Envie "to": "3899991234". Resposta 400, error.code igual a invalid_payload e error.message começando com to:. Nada chega ao celular.

3. Teste 3Pedido válido responde 202, e a mensagem chega com o texto idêntico, inclusive acentos e quebras de linha.

   eAgendaCelular de teste

   Envie um texto com acentos, emoji, uma quebra de linha e uma linha em branco, por exemplo "Confirmação às 14:30\nSegunda linha\n\nÚltima linha 😀". Quem está com o celular compara letra por letra.

4. Teste 4O mesmo message_id enviado 3 vezes gera uma única mensagem no celular, e as três respostas são 202 com o mesmo corpo.

   eAgendaCelular de teste

   Repita o mesmo pedido três vezes seguidas. Três respostas 202 idênticas. Uma mensagem no celular. Um único sent e um único delivered no webhook.

5. Teste 5Envio para número sem WhatsApp gera message.status failed com not_on_whatsapp.

   eAgendaOperador

   Envie para o número sem WhatsApp separado pelo operador. A resposta é 202; logo depois chega status: "failed" com error.code: "not_on_whatsapp", sem sent antes.

6. Teste 6Envio para o celular de teste gera sent e delivered; ao abrir a mensagem, gera read.

   eAgendaCelular de teste

   Com o celular online e a conversa fechada, envie. Chegam sent e delivered em segundos. Abra a conversa: chega read. Os três com o mesmo message_id, nessa ordem.

7. Teste 7Resposta em texto do paciente gera message.received com type: "text".

   Celular de testeeAgenda

   Responda “SIM” sem citar. Chega type: "text", text: "SIM" e reply_to_message_id: null. Confira que from é o celular de teste (pode vir sem o nono dígito). O serviço não responde nada.

8. Teste 8Resposta citando uma mensagem enviada a pedido do eAgenda gera reply_to_message_id igual ao message_id dela.

   Celular de testeeAgenda

   No celular, toque e segure a mensagem recebida, escolha Responder e escreva. O evento traz reply_to_message_id igual ao message_id usado no POST /messages daquela mensagem.

9. Teste 9Áudio do paciente gera message.received com type: "audio" e text: null.

   Celular de testeeAgenda

   Grave e envie uma mensagem de voz. Chega type: "audio" e text: null. O serviço não responde nada ao paciente. Na v1.1, o mesmo evento traz transcription (teste 17).

10. Teste 10Mensagem em grupo ou enviada pelo próprio serviço não gera webhook.

    OperadorCelular de testeeAgenda

    Crie um grupo com o celular de teste e o número do serviço e mande uma mensagem no grupo: nenhum message.received. As mensagens que o serviço envia também não geram message.received, só message.status. O operador confirma no painel que nenhum evento foi criado.

11. Teste 11A assinatura do vetor de teste bate.

    eAgendaOperador

    Do lado do eAgenda, o teste com o vetor passa: o corpo do vetor é aceito com 200 e o mesmo corpo com um byte trocado recebe 401. Do lado do serviço, o operador mostra o teste equivalente passando.

12. Teste 12Com o eAgenda fora do ar, o evento é reenviado com o mesmo event_id e chega quando ele volta.

    eAgendaOperadorCelular de teste

    Desligue o webhook do eAgenda (ou faça-o responder 503). Mande uma mensagem do celular de teste. No painel, o operador vê o evento pendente e as tentativas. Religue em menos de 1 hora. O evento chega com o mesmo event_id e é processado uma vez só.

13. Teste 13Reiniciar o serviço com mensagens na fila não perde nem duplica mensagens.

    eAgendaOperadorCelular de teste

    Envie 10 mensagens numeradas de uma vez, cada uma com seu message_id. Com 3 s entre envios, elas ficam na fila (queue_size no /health). O operador reinicia o serviço no meio. As 10 chegam ao celular, uma vez cada, e cada uma recebe seus status.

14. Teste 14Os logs do serviço não têm texto de mensagem nem telefone completo.

    Operador

    Depois dos testes, o operador procura nos logs do serviço (painel e saída do contêiner) um trecho de texto enviado e o telefone completo do celular de teste. Nenhum dos dois pode aparecer: só ids e telefones mascarados, como ****1234.

15. Teste 15GET /health mostra session: "disconnected" com o celular desconectado.

    OperadoreAgenda

    O operador desconecta a sessão do número do serviço. O eAgenda chama GET /health: session: "disconnected", e um POST /messages novo responde 503. Ao final, o operador reconecta lendo o QR code.

16. Teste 16 · v1.1Envio em áudio chega como mensagem de voz e gera sent, delivered e read.

    eAgendaCelular de teste

    Envie com "type": "audio" (exemplo no início rápido). A resposta é 202 na hora. Em alguns segundos chega ao celular uma mensagem de voz, sem texto escrito, que fala o texto enviado. Chegam sent e delivered; ao abrir a conversa ou ouvir o áudio, chega read. Os três com o mesmo message_id, nessa ordem.

17. Teste 17 · v1.1Áudio do paciente gera transcription.status: "ok" com texto e confiança.

    Celular de testeeAgenda

    Grave uma mensagem de voz com uma frase conhecida, como “A outra consulta é de manhã, então consigo ir sim”. Chega type: "audio", text: null e transcription com status: "ok", text igual ou muito próximo do que foi dito, confidence entre 0 e 1, language: "pt" e provider: "openai/whisper-1". O evento não traz o arquivo de áudio.

18. Teste 18 · v1.1type inválido dá 400.

    eAgenda

    Envie um pedido válido, mas com "type": "video". Resposta 400, error.code igual a invalid_payload e error.message igual a type: use text ou audio. Nada chega ao celular.

Reações, edições e mensagens apagadas não chegam ao eAgenda. Se o paciente editar “SIM” para “NÃO”, o eAgenda só vê o “SIM”. Se ele reagir com um emoji em vez de escrever, o eAgenda não fica sabendo.

Dados pessoais (LGPD)

O serviço trafega telefone e conversa de pacientes do SUS. Ele segue estas regras:

• Os logs têm só ids e os 4 últimos dígitos do telefone (****1234). Nunca o texto, a transcrição ou o telefone completo.
• O texto de uma mensagem enviada é apagado do banco do serviço assim que o WhatsApp aceita o envio, ou quando ela falha.
• Sem o texto, ficam só ids, telefone e status. Os ids são guardados por 7 dias.
• Fora a extensão de áudio (abaixo), nada vai para terceiros: nem analytics, nem monitoramento externo.

• O serviço não guarda o áudio: ele fica só em memória durante a operação. A transcrição sai no webhook e é apagada do banco do serviço depois da entrega, como os demais corpos. Os logs não têm texto nem transcrição. Na lista de eventos do painel, o operador vê só o status e a confiança da transcrição.
• Recomendações: usar conta paga nos dois fornecedores (a API da OpenAI não usa os dados recebidos pela API para treinar modelos, por padrão; no Gemini, o nível gratuito pode usar os dados para melhorar produtos, o pago não) e registrar os dois como operadores no inventário de dados da LGPD.
• Cada recurso pode ser desligado no serviço: sem chave de voz configurada, não há envio em áudio; sem a chave da OpenAI, a transcrição fica disabled. O GET /health mostra o que está ligado.

Do lado do eAgenda, o recomendado é o mesmo: não registrar em log o texto das mensagens nem o telefone completo. Neste ambiente, usem só celulares de teste e dados fictícios.

Risco de bloqueio do número

A automação do WhatsApp Web não é um canal oficial do WhatsApp. O WhatsApp pode restringir ou banir o número do serviço sem aviso. O risco cresce com muitas mensagens para quem não tem o número salvo, textos repetidos e denúncias de spam.

• Mantenham o volume baixo e enviem só para celulares de teste.
• O intervalo de 3 s entre envios existe para reduzir esse risco. Não tentem contorná-lo com vários pedidos em paralelo: a fila é uma só.
• A sessão pode cair quando o WhatsApp Web muda de versão. O operador reconecta; enquanto isso, /health mostra o estado.
• Para atender pacientes reais em produção, o caminho oficial é a API do WhatsApp Business, que tem regras e custos próprios.