Mensagens de Mídia

A Antonnia suporta mensagens de mídia rica: imagens, áudio, vídeo e arquivos. Sua integração precisa lidar com mídia em ambas as direções — entrada (usuário envia mídia) e saída (IA responde com mídia).

Referência de tipos de conteúdo

Type	Fields	Exemplo
`image`	`url`	`{"type": "image", "url": "https://..."}`
`audio`	`url`, `transcript` (opcional)	`{"type": "audio", "url": "https://...", "transcript": "Hello"}`
`video`	`url`	`{"type": "video", "url": "https://..."}`
`file`	`url`, `mime_type`, `name`	`{"type": "file", "url": "https://...", "mime_type": "application/pdf", "name": "doc.pdf"}`

Entrada: recebendo mídia

Quando um usuário envia mídia pelo seu canal, baixe-a e crie uma mensagem com uma URL pública.

Image

curl -X POST https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc/messages \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "type": "image", "url": "https://cdn.example.com/photo.jpg" },
    "role": "user",
    "provider_message_id": "channel_msg_001"
  }'

# 1. Download media from your channel (if URL is private/temporary)
media_url = await download_and_upload(channel_message["media_url"])

# 2. Create message with public URL
httpx.post(
    f"{BASE_URL}/sessions/{session_id}/messages",
    headers=HEADERS,
    json={
        "content": {"type": "image", "url": media_url},
        "role": "user",
        "provider_message_id": channel_message["id"],
    },
)

Audio

httpx.post(
    f"{BASE_URL}/sessions/{session_id}/messages",
    headers=HEADERS,
    json={
        "content": {
            "type": "audio",
            "url": audio_url,
            "transcript": "Optional transcription text",
        },
        "role": "user",
        "provider_message_id": channel_message["id"],
    },
)

File

httpx.post(
    f"{BASE_URL}/sessions/{session_id}/messages",
    headers=HEADERS,
    json={
        "content": {
            "type": "file",
            "url": file_url,
            "mime_type": "application/pdf",
            "name": "invoice.pdf",
        },
        "role": "user",
        "provider_message_id": channel_message["id"],
    },
)

As URLs devem ser acessíveis publicamente. Muitas APIs de canal fornecem URLs de mídia temporárias ou autenticadas. Baixe a mídia e hospede novamente em uma URL pública antes de criar a mensagem na Antonnia.

Saída: entregando mídia

Quando a IA responde com mídia, entregue pelo seu canal:

async def deliver_message(message: dict, session: dict):
    content = message["content"]
    instance_id = session["metadata"]["mychannel_instance_id"]
    user_id = session["metadata"]["mychannel_user_id"]

    if 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,
            url=content["url"],
            filename=content.get("name", "file"),
            mime_type=content.get("mime_type"),
        )

    else:
        return  # Unknown type

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

Tipos de mídia não suportados

Se o seu canal não suporta um tipo de mídia, você tem duas opções:

Converter para placeholder de texto — enviar uma mensagem de texto indicando o tipo de conteúdo
Ignorar silenciosamente — não entregar a mensagem

As integrações WhatsApp e ZAPI convertem mensagens de vídeo não suportadas em placeholders de texto:

if content["type"] == "video":
    # Channel doesn't support video — send text placeholder
    channel_msg_id = await channel_api.send_text(
        instance_id, user_id, "[Video message]"
    )

Padrões de mídia em produção

Canal	Images	Audio	Video	Files
WhatsApp	Baixar e re-hospedar	Baixar e re-hospedar	Placeholder de texto	Baixar e re-hospedar
HubSpot	URL direta	URL direta	Não suportado	Não suportado
ZAPI	URL direta	URL direta	Placeholder de texto	URL direta
Syngoo	Busca lazy de URL	Busca lazy de URL	Não suportado	Não suportado

Mensagens de Mídia

On this page