Mensagens
Tipos de mensagem, formatos de conteúdo e rastreamento de entrega
Mensagens são as partes individuais de conteúdo trocadas dentro de uma sessão. Toda mensagem tem um role (quem enviou), content (o que foi dito) e um delivery status (se chegou ao destino).
Objeto da mensagem
{
"id": "msg_abc123",
"session_id": "sess_456",
"conversation_id": "conv_789",
"organization_id": "org_xyz",
"role": "user",
"content": { "type": "text", "text": "Hello" },
"provider_message_id": "channel_msg_001",
"replied_provider_message_id": null,
"run_id": null,
"delivery_status": "pending",
"delivery_error_code": null,
"delivery_error_message": null,
"delivered_at": null,
"metadata": {},
"created_at": "2025-01-15T10:30:00Z",
"updated_at": null
}Roles
| Role | Description |
|---|---|
user | Mensagem do usuário final (entrada na Antonnia) |
assistant | Mensagem do agente de IA ou humano (saída da Antonnia) |
Ao processar webhooks, filtre por role: "assistant" para obter as mensagens que seu canal precisa entregar.
Tipos de conteúdo
Text
{ "type": "text", "text": "Hello world" }Text with template
{
"type": "text",
"text": "Hello {{name}}",
"template_id": "tmpl_123",
"template_parameters": { "name": "John" }
}Image
{ "type": "image", "url": "https://..." }Audio
{ "type": "audio", "url": "https://...", "transcript": "optional text" }Video
{ "type": "video", "url": "https://..." }File
{
"type": "file",
"url": "https://...",
"mime_type": "application/pdf",
"name": "document.pdf"
}Tipos internos — ignore estes ao processar webhooks de saída:
function_call— invocação de ferramenta da IAfunction_result— resultado de ferramenta da IAthought— etapa de raciocínio da IA
Estes são usados internamente pelo agente de IA e não devem ser entregues aos usuários finais.
Provider message ID
O campo provider_message_id vincula uma mensagem da Antonnia à sua correspondente no seu canal. Defina este campo:
- Entrada: Ao criar uma mensagem do usuário, passe o ID da mensagem do canal como
provider_message_id - Saída: Após entregar uma mensagem do assistente, atualize-a com o ID da mensagem do seu canal via
PATCH
Isso permite threading de respostas e rastreamento de entrega entre sistemas.
Status de entrega
As mensagens rastreiam seu progresso de entrega:
pending → sent → delivered → read
↓
failed (with error_code + error_message)
↓
rejectedVeja o Guia de Status de Entrega para detalhes.
Relacionados
- Guia de Mensagens de Mídia — manipulando imagens, áudio, vídeo e arquivos
- Referência da API de Mensagens — documentação completa dos endpoints