API de Mensagens

Todos os endpoints de mensagem são vinculados a uma sessão: /sessions/{session_id}/messages.

Criar mensagem

Cria uma nova mensagem em uma sessão.

POST /sessions/{session_id}/messages

Corpo da requisição

Field	Type	Required	Description
`content`	object	Yes	Conteúdo da mensagem (veja tipos de conteúdo)
`role`	string	Yes	`"user"` ou `"assistant"`
`provider_message_id`	string	No	ID da mensagem no seu canal
`replied_provider_message_id`	string	No	ID no provedor da mensagem que está sendo respondida
`run_id`	string	No	Identificador de execução da IA (uso interno)

curl -X POST https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/messages \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "type": "text", "text": "Hello, I need help" },
    "role": "user",
    "provider_message_id": "channel_msg_001"
  }'

response = httpx.post(
    f"{BASE_URL}/sessions/sess_abc123/messages",
    headers=HEADERS,
    json={
        "content": {"type": "text", "text": "Hello, I need help"},
        "role": "user",
        "provider_message_id": "channel_msg_001",
    },
)
message = response.json()

Response `201`

{
  "id": "msg_abc123",
  "session_id": "sess_abc123",
  "conversation_id": "conv_789",
  "organization_id": "org_xyz",
  "role": "user",
  "content": { "type": "text", "text": "Hello, I need help" },
  "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
}

Erros

Code	Description
`400`	Tipo de conteúdo inválido
`401`	Não autorizado
`404`	Sessão não encontrada

Obter mensagem

Recupera uma única mensagem.

GET /sessions/{session_id}/messages/{message_id}

curl -X GET https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/messages/msg_xyz789 \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN"

response = httpx.get(
    f"{BASE_URL}/sessions/sess_abc123/messages/msg_xyz789",
    headers=HEADERS,
)
message = response.json()

Response `200`

Retorna o objeto completo da mensagem.

Erros

Code	Description
`401`	Não autorizado
`403`	A mensagem pertence a outra organização
`404`	Mensagem ou sessão não encontrada

Atualizar mensagem

Atualiza campos de rastreamento de entrega em uma mensagem. Não modifica o conteúdo da mensagem.

PATCH /sessions/{session_id}/messages/{message_id}

Corpo da requisição

Field	Type	Required	Description
`provider_message_id`	string	No	ID da mensagem no seu canal
`replied_provider_message_id`	string	No	ID no provedor da mensagem respondida
`delivery_status`	string	No	`"pending"`, `"sent"`, `"delivered"`, `"read"`, `"failed"`, `"rejected"`
`delivery_error_code`	integer	No	Código de erro do canal (quando falhou)
`delivery_error_message`	string	No	Descrição do erro do canal (quando falhou)
`delivered_at`	datetime	No	Quando a mensagem foi entregue

# Mark as sent with provider ID
curl -X PATCH https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/messages/msg_xyz789 \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_message_id": "channel_msg_456",
    "delivery_status": "sent"
  }'

# Mark as sent with provider ID
httpx.patch(
    f"{BASE_URL}/sessions/sess_abc123/messages/msg_xyz789",
    headers=HEADERS,
    json={
        "provider_message_id": "channel_msg_456",
        "delivery_status": "sent",
    },
)

Reportar falha de entrega

curl -X PATCH https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/messages/msg_xyz789 \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_status": "failed",
    "delivery_error_code": 131026,
    "delivery_error_message": "24-hour messaging window expired"
  }'

httpx.patch(
    f"{BASE_URL}/sessions/sess_abc123/messages/msg_xyz789",
    headers=HEADERS,
    json={
        "delivery_status": "failed",
        "delivery_error_code": 131026,
        "delivery_error_message": "24-hour messaging window expired",
    },
)

Response `200`

Retorna o objeto da mensagem atualizado.

Buscar mensagens

Busca mensagens dentro de uma sessão.

POST /sessions/{session_id}/messages/search

Corpo da requisição

Field	Type	Required	Description
`session_id`	string	Yes	Sessão para buscar
`provider_message_id`	string	No	Filtrar por ID da mensagem no canal
`replied_provider_message_id`	string	No	Filtrar por ID da mensagem respondida no canal
`role`	string	No	`"user"` ou `"assistant"`
`offset`	integer	No	Offset de paginação
`limit`	integer	No	Máximo de resultados

curl -X POST https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/messages/search \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "provider_message_id": "channel_msg_001"
  }'

response = httpx.post(
    f"{BASE_URL}/sessions/sess_abc123/messages/search",
    headers=HEADERS,
    json={
        "session_id": "sess_abc123",
        "provider_message_id": "channel_msg_001",
    },
)
messages = response.json()  # List[Message]

Response `200`

Retorna um array de objetos de mensagem.

API de Mensagens

On this page