Conversations
Read the conversations your bots have had — across chat, voice, SMS, and WhatsApp — including messages and step-by-step traces. Read endpoints need conversations:read; delete needs conversations:write.
Endpoints
| Method & path | Ability | Notes |
|---|---|---|
GET /api/v1/conversations | conversations:read | Paginated list (see below) |
GET /api/v1/conversations/{id} | conversations:read | Includes messages[] |
GET /api/v1/conversations/{id}/trace | conversations:read | Step-by-step execution trace |
DELETE /api/v1/conversations/{id} | conversations:write | Hard delete (cascades) |
List conversations
Pages with limit (default 100, max 500) and offset, where limit + offset ≤ 10000. The total count is returned in the X-Total-Count response header.
Filters (strict allow-list — an unknown query parameter returns 400):
| Parameter | Filters by |
|---|---|
bot_id | A specific bot |
channel | web | sms | whatsapp | api | agent | voice | post_call |
external_call_id, external_linked_id, source_conversation_id | Your external identifiers |
since, until | RFC 3339 timestamps |
analysis.sentiment, analysis.topic, analysis.outcome | Post-call analysis |
curl "https://app.hania.ai/api/v1/conversations?channel=voice&limit=50" \
-H "Authorization: Bearer $HANIA_API_KEY"List item fields: id, bot_id, bot_name, channel, customer_id, external_call_id, external_linked_id, message_count, started_at, ended_at, last_message_at, last_message_preview (≤ 100 chars), has_trace, optional post_call_analysis, optional source_conversation_id.
Retrieve a conversation
GET /api/v1/conversations/{id} returns the conversation plus its messages[] in ascending order. Each message: id, role, content, optional metadata (JSON string), created_at.
Trace
GET /api/v1/conversations/{id}/trace returns the execution steps — useful for debugging tool calls and model turns. Each step: id, step_number, action_type, action_name, result_summary, items_count, started_at, completed_at, duration_ms, error_message, and (when applicable) model, prompt_tokens, completion_tokens, total_tokens, tool_function, tool_execution_ms.
Delete
DELETE /api/v1/conversations/{id} permanently removes the conversation and its messages and trace (cascades). This cannot be undone.