Status de Entrega

A Antonnia rastreia o status de entrega de cada mensagem. Sua integração de canal atualiza esse status conforme as mensagens passam pelo pipeline de entrega do seu canal.

Fluxo de status

pending → sent → delivered → read
                               ↓
                             failed (with error_code + error_message)
                               ↓
                            rejected

Status	Significado
`pending`	Mensagem criada na Antonnia, ainda não enviada pelo canal
`sent`	Enviada com sucesso para a API do canal
`delivered`	Confirmada a entrega no dispositivo do usuário final
`read`	Usuário final leu a mensagem
`failed`	A API do canal retornou um erro
`rejected`	Mensagem permanentemente rejeitada (ex.: número bloqueado, template inválido)

Atualizando o status de entrega

Após entregar uma mensagem pelo seu canal, atualize o status:

# On successful send
httpx.patch(
    f"{BASE_URL}/sessions/{session_id}/messages/{message_id}",
    headers=HEADERS,
    json={
        "provider_message_id": channel_msg_id,
        "delivery_status": "sent",
    },
)

Lidando com callbacks de entrega

Muitos canais fornecem confirmações de entrega. Mapeie-as para atualizações de status na Antonnia:

@app.post("/webhook/delivery-status")
async def handle_delivery_status(request: Request):
    event = await request.json()
    channel_msg_id = event["message_id"]
    status = event["status"]  # "delivered", "read", "failed"

    # Find the Antonnia message by provider_message_id
    messages = httpx.post(
        f"{BASE_URL}/sessions/{session_id}/messages/search",
        headers=HEADERS,
        json={"provider_message_id": channel_msg_id},
    ).json()

    if not messages:
        return  # Message not yet in Antonnia (race condition — expected)

    message = messages[0]

    # Map channel status to Antonnia status
    status_map = {
        "delivered": "delivered",
        "read": "read",
        "failed": "failed",
    }

    update = {"delivery_status": status_map.get(status, status)}

    if status == "failed":
        update["delivery_error_code"] = event.get("error_code")
        update["delivery_error_message"] = event.get("error_message")

    httpx.patch(
        f"{BASE_URL}/sessions/{session_id}/messages/{message['id']}",
        headers=HEADERS,
        json=update,
    )

Tratamento de condição de corrida: Confirmações de entrega podem chegar antes da mensagem na Antonnia ser totalmente criada. Se você não encontrar a mensagem, registre no log e ignore — o status será atualizado quando disponível. A integração do WhatsApp lida com isso de forma elegante.

Rastreamento de erros

Quando a entrega falhar, inclua o código de erro e a mensagem:

httpx.patch(
    f"{BASE_URL}/sessions/{session_id}/messages/{message_id}",
    headers=HEADERS,
    json={
        "delivery_status": "failed",
        "delivery_error_code": 131026,
        "delivery_error_message": "Message failed to send because more than 24 hours have passed since the customer last replied",
    },
)

Esses detalhes de erro aparecem no painel da Antonnia, ajudando os operadores a diagnosticar problemas de entrega.

Boas práticas

Sempre defina provider_message_id ao atualizar o status — isso vincula a mensagem da Antonnia à mensagem do seu canal para consultas futuras
Atualize o status progressivamente — vá de pending → sent → delivered → read conforme seu canal confirma cada etapa
Trate failed com cuidado — inclua códigos de erro e mensagens para que os operadores possam tomar providências
Não tente novamente atualizações que falharam — se o PATCH falhar, registre o erro no log e siga em frente