Conversations

Manage omnichannel conversations — email, chat, WhatsApp, and voice — via the Aurion API.

⚠️ Preview — not yet in the public API

The endpoints on this page are part of the AurionAI helpdesk and are currently accessible only through an authenticated dashboard session. They are not yet exposed through public API keys — a request authenticated with X-API-Key returns 403. Public API-key access is planned. The reference below documents the intended contract.

The Conversations API (v2) provides a unified interface for managing support conversations across all channels — email, chat, WhatsApp, and voice. This is the primary API for the Aurion CS helpdesk platform.

List Conversations

cURL

curl "https://apps.aurionai.net/api/v2/conversations?status=open&limit=10" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Python

import requests

response = requests.get(
    "https://apps.aurionai.net/api/v2/conversations",
    headers={"X-API-Key": "itsm_sk_live_xxxx"},
    params={"status": "open", "limit": 10},
)
conversations = response.json()

TypeScript

const response = await fetch(
  "https://apps.aurionai.net/api/v2/conversations?status=open&limit=10",
  {
    headers: { "X-API-Key": "itsm_sk_live_xxxx" },
  }
);
const conversations = await response.json();

Response:

{
  "items": [
    {
      "id": "3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34",
      "ticket_number": 142,
      "subject": "Cannot access email",
      "status": "open",
      "priority": "high",
      "channel": "email",
      "contact_id": "7c1e9a44-2f8b-4d63-9e10-3a5c8b7d6e21",
      "contact_name": "Jane Smith",
      "assignee_team_id": "b21d4f60-7a3c-49e8-8f1d-2c6b9e4a0d57",
      "assignee_user_id": "9e4a0d57-1b2c-4d3e-8a6f-7c0b5e2d1a48",
      "assignee_team_name": "IT Support",
      "assignee_user_name": "John Doe",
      "last_message_snippet": "Thanks, that worked!",
      "is_read": false,
      "tags": ["email", "access"],
      "created_at": "2026-03-08T09:15:00Z",
      "updated_at": "2026-03-08T10:30:00Z"
    }
  ],
  "total": 48,
  "limit": 10,
  "offset": 0
}

Query Parameters:

Parameter	Type	Description
`status`	string	`open`, `pending`, `resolved`, `closed`
`priority`	string	`low`, `medium`, `high`, `urgent`
`channel`	string	`email`, `chat`, `whatsapp`, `voice`, `widget`
`assignee_team_id`	string	Filter by team (UUID)
`assignee_user_id`	string	Filter by assigned agent (UUID)
`contact_id`	string	Filter by contact (UUID)
`tags`	string	Comma-separated tag filter
`search`	string	Full-text search in subject and messages (min 2 characters)
`limit`	integer	Results per page (default: 50, max: 100)
`offset`	integer	Number of results to skip

Get Conversation

curl "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Parameter	Type	Description
`include_deleted`	boolean	Include soft-deleted conversations in the lookup (default: `false`)

Create Conversation

Creates a new conversation. There is no nested message object — the first message body is taken from the top-level description field. Returns 201 Created.

curl -X POST "https://apps.aurionai.net/api/v2/conversations" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "7c1e9a44-2f8b-4d63-9e10-3a5c8b7d6e21",
    "subject": "Password reset request",
    "description": "I need help resetting my corporate email password.",
    "channel": "agent_created",
    "priority": "medium"
  }'

Request Body:

Field	Type	Description
`contact_id`	string	AurionAI contact UUID (required)
`channel`	string	Source channel (default: `agent_created`)
`subject`	string	Conversation subject (max 500)
`description`	string	First message body (max 5000)
`priority`	string	`low`, `medium`, `high`, `urgent`
`category`	string	Category (max 120)
`form_id`	string	Custom form id to validate against
`form_data`	object	Structured form field values
`custom_attrs`	object	Arbitrary custom attributes
`assignee_user_id`	string	Assign to an agent on create (UUID)
`assignee_team_id`	string	Assign to a team on create (UUID)

Response: AgentConversationCreateResponse — { id, ticket_number, status, priority, subject, created_at, assignee_user_id, assignee_team_id }.

Add Message

Post a message (public reply, internal note, or forward) to a conversation. Returns 201 Created. There is no /reply endpoint — use POST /{id}/messages. The optional Idempotency-Key header makes retries safe.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/messages" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0a1e8c-3b2d-4a91-8c7e-1d6f0b3a9e25" \
  -d '{
    "body": "I have reset your password. Please check your email for the new credentials.",
    "content_type": "text",
    "is_internal": false
  }'

Request Body:

Field	Type	Description
`body`	string	Message text (0-4000; may be empty only when a template is referenced via `metadata.template_id`)
`body_html`	string	Optional HTML body
`content_type`	string	One of `text`, `note_public`, `note_private`, `forward` (default: `text`)
`is_internal`	boolean	Whether the message is an internal note hidden from the contact (default: `false`)
`version`	integer	Optional optimistic-concurrency version of the conversation
`metadata`	object	Arbitrary metadata (e.g. `template_id` for template sends)
`attachment_ids`	array	Pre-uploaded attachment UUIDs to attach
`to` / `cc` / `bcc`	array	Explicit recipient lists for reply / forward
`next_status`	string	Optional status to move the conversation to with this reply: `open`, `pending`, `waiting`, `resolved` (ignored when `is_internal=true`)

Message Content Types:

`content_type`	Description
`text`	Public reply visible to the contact
`note_public`	Note visible to the contact
`note_private`	Private internal note (not visible to the contact)
`forward`	Forward the conversation to an external recipient

Public vs. private is expressed by content_type together with is_internal — there are no reply/note content types.

Update Conversation

curl -X PATCH "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "priority": "low",
    "tags": ["resolved", "password"]
  }'

Assign Conversation

curl -X POST "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/assign" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "9e4a0d57-1b2c-4d3e-8a6f-7c0b5e2d1a48",
    "team_id": "b21d4f60-7a3c-49e8-8f1d-2c6b9e4a0d57"
  }'

Request Body:

Field	Type	Description
`user_id`	string	Target agent UUID (optional)
`team_id`	string	Target team UUID (optional)
`required_skills`	array	Skills the assignee must have for routing (optional)

Conversation Lifecycle

open → pending → resolved → closed
  ↑                           |
  └───── reopen ──────────────┘

Channels

Channel	Description
`email`	Conversations from email channels
`chat`	Live chat widget conversations
`whatsapp`	WhatsApp Business conversations
`voice`	Voice call conversations (linked to call records)
`widget`	Web widget conversations

Conversation vs Ticket

Conversations are the v2 API for the Aurion CS helpdesk — omnichannel, real-time, with rich threading
Tickets are the v1 API that maps to your external ITSM provider (Freshservice, HaloITSM, ServiceNow, JSM)

Both can coexist. Voice calls can create either tickets (ITSM flow) or conversations (CS flow) depending on your configuration.

Tickets — ITSM ticket management (v1 API)
Contacts & Companies — Manage conversation contacts
Calls & Recordings — Voice call data linked to conversations
Channels — Configure email, WhatsApp, and voice channels
Webhooks — Subscribe to conversation.* events
SLA Management — Track SLA compliance on conversations

Search & Filter

Search Conversations

Use the search endpoint for advanced filtering with conditions-based queries.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/search" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "match": "all",
    "conditions": [
      { "field": "status", "operator": "is", "value": "open" },
      { "field": "priority", "operator": "includes", "values": ["high", "urgent"] }
    ],
    "search": "email access",
    "sort_by": "updated_at",
    "sort_order": "desc",
    "limit": 25,
    "offset": 0
  }'

Request Body:

Field	Type	Description
`match`	string	`all` (AND) or `any` (OR) for combining conditions (default: `all`)
`conditions`	array	Filter conditions (see below)
`search`	string	Full-text search in subject and messages
`sort_by`	string	Sort field (default: `updated_at`)
`sort_order`	string	`asc` or `desc` (default: `desc`)
`limit`	integer	Results per page (1-100, default: 50)
`offset`	integer	Number of results to skip (default: 0)

Filter Condition:

Field	Type	Description
`field`	string	Field to filter on (e.g., `status`, `priority`, `channel`, `assignee_user_id`)
`operator`	string	`is`, `is_not`, `includes`, `excludes`, `contains`, `does_not_contain`, `in_the_last`, `before`, `after`, `between`
`value`	string	Single value for `is`, `is_not`, `contains`, `does_not_contain` operators
`values`	array	Multiple values for `includes`, `excludes` operators

Response: Same format as List Conversations.

Returns available filter options for the inbox (statuses, priorities, channels, teams, agents, tags).

curl "https://apps.aurionai.net/api/v2/conversations/filter-options" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "statuses": ["open", "pending", "resolved", "closed"],
  "priorities": ["low", "medium", "high", "urgent"],
  "channels": ["email", "chat", "whatsapp", "voice", "widget"],
  "teams": [{ "id": "b21d4f60-7a3c-49e8-8f1d-2c6b9e4a0d57", "name": "IT Support" }],
  "agents": [{ "id": "9e4a0d57-1b2c-4d3e-8a6f-7c0b5e2d1a48", "name": "John Doe" }],
  "tags": ["email", "access", "password"]
}

Search Tags

Search for existing conversation tags by prefix.

curl "https://apps.aurionai.net/api/v2/conversations/tags/search?q=pass&limit=10" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Parameter	Type	Description
`q`	string	Search query (max 120 characters)
`limit`	integer	Max results (1-50, default: 15)

{
  "items": ["password", "password-reset", "passthrough"]
}

Assignment

Unassign Conversation

Remove the current assignee from a conversation.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/unassign" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "unassigned"
}

Reassign Conversation

Reassign a conversation to a different agent or team. If only team_id is provided, the system automatically picks an eligible agent via round-robin routing.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/reassign" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "2d1a4807-9e4a-4d3e-8a6f-7c0b5e2d1b9c",
    "team_id": "b21d4f60-7a3c-49e8-8f1d-2c6b9e4a0d57"
  }'

Request Body:

Field	Type	Description
`user_id`	string	Target agent ID (optional; auto-assigned if omitted)
`team_id`	string	Target team ID (optional)

{
  "assignee_user_id": "2d1a4807-9e4a-4d3e-8a6f-7c0b5e2d1b9c",
  "assignee_team_id": "b21d4f60-7a3c-49e8-8f1d-2c6b9e4a0d57",
  "routing_reason": "manual_reassignment"
}

Parent-Child Relationships

List Child Conversations

Get all child conversations linked to a parent.

curl "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/children" \
  -H "X-API-Key: itsm_sk_live_xxxx"

[
  {
    "id": "6b5e0d1f-2a34-4c7f-8a21-3f8c2b1a9d4e",
    "subject": "Follow-up: Email access",
    "status": "open",
    "priority": "medium",
    "channel": "email",
    "contact_name": "Jane Smith",
    "created_at": "2026-03-09T14:00:00Z",
    "updated_at": "2026-03-09T15:30:00Z"
  }
]

Set Parent Conversation

Link a conversation as a child of another conversation.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/6b5e0d1f-2a34-4c7f-8a21-3f8c2b1a9d4e/parent" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_id": "3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34"
  }'

Response: Returns the updated conversation detail.

Activity Export

Export Conversation Activities

Export the full activity log for a conversation as CSV or JSON.

curl "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/activities/export?format=csv" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -o activities.csv

Query Parameters:

Parameter	Type	Description
`format`	string	`csv` or `json` (default: `csv`)

Returns a file download with Content-Disposition: attachment.

Linking & Relationships

Get Linked Items

List all conversations linked to this conversation.

curl "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/links" \
  -H "X-API-Key: itsm_sk_live_xxxx"

[
  {
    "id": "4c5d6e7f-8a9b-4c0d-1e2f-3a4b5c6d7e8f",
    "linked_conversation_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "link_type": "related",
    "subject": "Printer not working",
    "status": "open",
    "priority": "medium",
    "created_at": "2026-03-08T11:00:00Z"
  }
]

Link Types: related, parent, child, duplicate

Remove Link

Delete a link between two conversations.

curl -X DELETE "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/links/4c5d6e7f-8a9b-4c0d-1e2f-3a4b5c6d7e8f" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "deleted",
  "id": "4c5d6e7f-8a9b-4c0d-1e2f-3a4b5c6d7e8f"
}

Attachments

Download Attachment

Download an attachment file directly. For S3-stored files, returns a 302 redirect to a presigned URL.

curl "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/attachments/0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b/download" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -o attachment.pdf

Returns the file contents with appropriate Content-Type header. If malware scanning is enabled, files pending scan return 202 Accepted with a Retry-After header, and quarantined files return 410 Gone.

Delete Attachment

Remove an attachment from a conversation. Also deletes the file from storage (S3 or local).

curl -X DELETE "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/attachments/0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "deleted",
  "id": "0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b"
}

Resolution

Get Resolution

Retrieve the resolution details for a conversation.

curl "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/resolution" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "id": "8a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d",
  "conversation_id": "3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34",
  "root_cause": "Expired Active Directory password",
  "actions_taken": "Reset password and updated group policy",
  "resolution": "User can now access email normally",
  "ai_generated": false
}

Set Resolution

Create or update the resolution for a conversation.

curl -X PUT "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/resolution" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "root_cause": "Expired Active Directory password",
    "actions_taken": "Reset password and updated group policy",
    "resolution": "User can now access email normally",
    "ai_generated": false
  }'

Request Body:

Field	Type	Description
`root_cause`	string	Root cause of the issue
`actions_taken`	string	Actions taken to resolve
`resolution`	string	Resolution summary
`ai_generated`	boolean	Whether the resolution was AI-generated (default: `false`)

Response: Returns the saved resolution object.

Lifecycle Operations

Mark as Spam

Flag a conversation as spam. Removes it from the active inbox.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/spam" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "spam_marked"
}

Unmark Spam

Restore a conversation that was previously flagged as spam.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/unspam" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "spam_unmarked"
}

Delete Conversation

Soft-delete a conversation. Can be restored later.

curl -X DELETE "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "deleted"
}

Restore Conversation

Restore a previously soft-deleted conversation.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/restore" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "restored"
}

Archive Conversation

Move a conversation to the archive. Only conversations that are not already archived, deleted, or spam can be archived.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/archive" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "archived"
}

Unarchive Conversation

Restore a conversation from the archive back to the active inbox.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/unarchive" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "unarchived"
}

Mark as Read

Mark a conversation as read for the current user.

curl -X PATCH "https://apps.aurionai.net/api/v2/conversations/3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34/read" \
  -H "X-API-Key: itsm_sk_live_xxxx"

{
  "status": "read"
}

Get Shared Conversation

Retrieve a conversation via a share token. No authentication required — the token acts as the access credential.

curl "https://apps.aurionai.net/api/v2/conversations/share/sh_4f9a2c7e8b1d6e0a"

{
  "id": "3f8c2b1a-9d4e-4c7f-8a21-6b5e0d1f2a34",
  "subject": "Cannot access email",
  "channel": "email",
  "status": "open",
  "messages": [
    {
      "id": "c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
      "body": "I need help with my email access.",
      "sender_type": "contact",
      "created_at": "2026-03-08T09:15:00Z"
    }
  ],
  "resolution": null,
  "attachments": [],
  "expires_at": "2026-04-08T09:15:00Z",
  "permission": "view_only"
}

Permissions: view_only (read-only access) or view_and_comment (can add comments).

Returns 410 Gone if the share link has expired, or 404 if the conversation no longer exists.

Add Comment on Shared Conversation

Add a comment to a shared conversation. Only available when the share link permission is view_and_comment.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/share/sh_4f9a2c7e8b1d6e0a/comments" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "I tried the suggested fix and it worked.",
    "author_name": "Jane Smith"
  }'

Request Body:

Field	Type	Description
`body`	string	Comment text (1-5000 characters)
`author_name`	string	Display name of the commenter (default: `Anonymous`, max 200 characters)

{
  "id": "d7e8f9a0-1b2c-4d3e-5f6a-7b8c9d0e1f2a",
  "body": "I tried the suggested fix and it worked.",
  "author_name": "Jane Smith",
  "created_at": "2026-03-08T12:00:00Z"
}

Returns 403 Forbidden if the share link is view-only.

Required Permissions

Each endpoint is gated by a dashboard-session permission. The four permissions used by this router are conversations:read, conversations:write, conversations:delete, and conversations:archive, plus a role check on activity export.

Permission	Endpoints
`conversations:read`	`GET /v2/conversations`, `GET /v2/conversations/:id`, `GET /v2/conversations/:id/children`, `GET /v2/conversations/:id/links`, `GET /v2/conversations/:id/resolution`, `GET /v2/conversations/:id/attachments/:id/download`, `GET /v2/conversations/filter-options`, `GET /v2/conversations/tags/search`, `POST /v2/conversations/search`, `PATCH /v2/conversations/:id/read`
`conversations:write`	`POST /v2/conversations`, `PATCH /v2/conversations/:id`, `POST /v2/conversations/:id/messages`, `POST /v2/conversations/:id/assign`, `POST /v2/conversations/:id/reassign`, `POST /v2/conversations/:id/unassign`, `POST /v2/conversations/:id/parent`, `PUT /v2/conversations/:id/resolution`, `POST /v2/conversations/:id/spam`, `POST /v2/conversations/:id/unspam`, `DELETE /v2/conversations/:id/links/:id`, `DELETE /v2/conversations/:id/attachments/:id`
`conversations:delete`	`DELETE /v2/conversations/:id`, `POST /v2/conversations/:id/restore`
`conversations:archive`	`POST /v2/conversations/:id/archive`, `POST /v2/conversations/:id/unarchive`
admin / owner role	`GET /v2/conversations/:id/activities/export` (requires `super_admin`, `tenant_owner`, or `tenant_admin` — not a scope)

When public API-key access ships, the allowlist only ever derives {resource}:read and {resource}:write from the request path — so conversations:delete and conversations:archive are dashboard-session permissions that would not be reachable as API-key scopes, and the export endpoint is role-gated rather than scope-gated.

Conversations

On this page