Mensagens de Saída

Mensagens de saída fluem da Antonnia para o seu canal. Quando o agente de IA responde, a Antonnia dispara um webhook message.created. Sua integração entrega a mensagem pela API do seu canal e reporta o status de entrega de volta.

Handler de webhook

@app.post("/webhook/antonnia")
async def handle_event(request: Request):
    event = await request.json()

    if event["type"] == "message.created":
        message = event["data"]["object"]
        await deliver_message(message)

Filtrando mensagens

Nem todo evento message.created precisa ser entregue. Aplique estes filtros:

async def deliver_message(message: dict):
    # 1. Only deliver assistant messages
    if message["role"] != "assistant":
        return

    # 2. Skip internal AI content types
    content_type = message["content"]["type"]
    if content_type in ("function_call", "function_result", "thought"):
        return

    # 3. Proceed with delivery
    await send_to_channel(message)

Sempre ignore tipos internos. O agente de IA pode emitir mensagens function_call, function_result e thought como parte do seu processo de raciocínio. Elas não são destinadas aos usuários finais.

Roteamento com metadata da sessão

Busque a sessão para obter informações de roteamento específicas do canal:

async def send_to_channel(message: dict):
    session = httpx.get(
        f"{BASE_URL}/sessions/{message['session_id']}",
        headers=HEADERS,
    ).json()

    instance_id = session["metadata"]["mychannel_instance_id"]
    user_id = session["metadata"]["mychannel_user_id"]

    content = message["content"]
    # ... send via your channel API

Entregando por tipo de conteúdo

Mapeie os tipos de conteúdo da Antonnia para os formatos de mensagem do seu canal:

    if content["type"] == "text":
        channel_msg_id = await channel_api.send_text(
            instance_id, user_id, content["text"]
        )
    elif content["type"] == "image":
        channel_msg_id = await channel_api.send_image(
            instance_id, user_id, content["url"]
        )
    elif content["type"] == "audio":
        channel_msg_id = await channel_api.send_audio(
            instance_id, user_id, content["url"]
        )
    elif content["type"] == "video":
        channel_msg_id = await channel_api.send_video(
            instance_id, user_id, content["url"]
        )
    elif content["type"] == "file":
        channel_msg_id = await channel_api.send_file(
            instance_id, user_id, content["url"], content.get("name")
        )
    else:
        # Unknown type — skip or convert to text
        return

Se o seu canal não suporta um tipo de conteúdo (ex.: vídeo), você pode convertê-lo em um placeholder de texto ou ignorá-lo. As integrações WhatsApp e ZAPI convertem mensagens de vídeo não suportadas em texto "[Video message]".

Atualizando o status de entrega

Após entregar a mensagem, reporte o status de volta para a Antonnia:

curl -X PATCH https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc/messages/msg_xyz \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_message_id": "channel_msg_456",
    "delivery_status": "sent"
  }'

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

O que atualizar

Field	Quando definir
`provider_message_id`	Sempre — vincula a mensagem da Antonnia à mensagem do seu canal
`delivery_status`	Sempre — defina como `"sent"` após entrega bem-sucedida
`delivery_error_code`	Em caso de falha — código de erro do seu canal
`delivery_error_message`	Em caso de falha — descrição do erro legível por humanos

Lidando com falhas de entrega

Se a API do seu canal retornar um erro:

try:
    channel_msg_id = await channel_api.send_text(instance_id, user_id, text)
    await update_message(message, channel_msg_id, "sent")
except ChannelAPIError as e:
    await update_message_failed(message, e.code, str(e))

async def update_message_failed(message: dict, error_code: int, error_msg: str):
    httpx.patch(
        f"{BASE_URL}/sessions/{message['session_id']}/messages/{message['id']}",
        headers=HEADERS,
        json={
            "delivery_status": "failed",
            "delivery_error_code": error_code,
            "delivery_error_message": error_msg,
        },
    )

Veja o Guia de Status de Entrega para o fluxo completo de status.

Mensagens de template

Alguns canais (como WhatsApp) exigem templates pré-aprovados para mensagens de saída. Quando content inclui template_id, envie um template em vez de uma mensagem de formato livre:

if content.get("template_id"):
    channel_msg_id = await channel_api.send_template(
        instance_id, user_id,
        template_id=content["template_id"],
        parameters=content.get("template_parameters", {}),
    )
else:
    channel_msg_id = await channel_api.send_text(instance_id, user_id, content["text"])

Mensagens de Saída

On this page