Conversations

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

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: ak_live_xxxx"

Python

import requests

response = requests.get(
    "https://apps.aurionai.net/api/v2/conversations",
    headers={"X-API-Key": "ak_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": "ak_live_xxxx" },
  }
);
const conversations = await response.json();

Response:

{
  "data": [
    {
      "id": "conv_abc123",
      "subject": "Cannot access email",
      "status": "open",
      "priority": "high",
      "channel": "email",
      "contact_id": "ct_456",
      "contact_name": "Jane Smith",
      "assigned_team_id": "team_789",
      "assigned_agent_id": "agent_012",
      "tags": ["email", "access"],
      "created_at": "2026-03-08T09:15:00Z",
      "last_activity_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`
`assigned_team_id`	string	Filter by team
`assigned_agent_id`	string	Filter by agent
`contact_id`	string	Filter by contact
`tags`	string	Comma-separated tag filter
`search`	string	Full-text search in subject and messages
`limit`	integer	Results per page (default: 25, max: 100)
`offset`	integer	Number of results to skip

Get Conversation

curl "https://apps.aurionai.net/api/v2/conversations/conv_abc123" \
  -H "X-API-Key: ak_live_xxxx"

Create Conversation

curl -X POST "https://apps.aurionai.net/api/v2/conversations" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Password reset request",
    "contact_id": "ct_456",
    "channel": "email",
    "priority": "medium",
    "message": {
      "body": "I need help resetting my corporate email password.",
      "type": "text"
    }
  }'

Reply to Conversation

curl -X POST "https://apps.aurionai.net/api/v2/conversations/conv_abc123/reply" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "I have reset your password. Please check your email for the new credentials.",
    "type": "reply"
  }'

Message Types:

Type	Description
`reply`	Public reply visible to the contact
`note`	Private internal note (not visible to contact)
`forward`	Forward conversation to external email

Update Conversation

curl -X PATCH "https://apps.aurionai.net/api/v2/conversations/conv_abc123" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "priority": "low",
    "assigned_agent_id": "agent_012",
    "tags": ["resolved", "password"]
  }'

Assign Conversation

curl -X POST "https://apps.aurionai.net/api/v2/conversations/conv_abc123/assign" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team_789",
    "agent_id": "agent_012"
  }'

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: ak_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
`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

Filter Condition:

Field	Type	Description
`field`	string	Field to filter on (e.g., `status`, `priority`, `channel`, `assigned_agent_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: ak_live_xxxx"

{
  "statuses": ["open", "pending", "resolved", "closed"],
  "priorities": ["low", "medium", "high", "urgent"],
  "channels": ["email", "chat", "whatsapp", "voice", "widget"],
  "teams": [{ "id": "team_789", "name": "IT Support" }],
  "agents": [{ "id": "agent_012", "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: ak_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/conv_abc123/unassign" \
  -H "X-API-Key: ak_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/conv_abc123/reassign" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "agent_045",
    "team_id": "team_789"
  }'

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": "agent_045",
  "assignee_team_id": "team_789",
  "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/conv_abc123/children" \
  -H "X-API-Key: ak_live_xxxx"

[
  {
    "id": "conv_child_001",
    "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/conv_child_001/parent" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_id": "conv_abc123"
  }'

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/conv_abc123/activities/export?format=csv" \
  -H "X-API-Key: ak_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/conv_abc123/links" \
  -H "X-API-Key: ak_live_xxxx"

[
  {
    "id": "link_001",
    "linked_conversation_id": "conv_def456",
    "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/conv_abc123/links/link_001" \
  -H "X-API-Key: ak_live_xxxx"

{
  "status": "deleted",
  "id": "link_001"
}

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/conv_abc123/attachments/att_001/download" \
  -H "X-API-Key: ak_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/conv_abc123/attachments/att_001" \
  -H "X-API-Key: ak_live_xxxx"

{
  "status": "deleted",
  "id": "att_001"
}

Resolution

Get Resolution

Retrieve the resolution details for a conversation.

curl "https://apps.aurionai.net/api/v2/conversations/conv_abc123/resolution" \
  -H "X-API-Key: ak_live_xxxx"

{
  "id": "res_001",
  "conversation_id": "conv_abc123",
  "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/conv_abc123/resolution" \
  -H "X-API-Key: ak_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/conv_abc123/spam" \
  -H "X-API-Key: ak_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/conv_abc123/unspam" \
  -H "X-API-Key: ak_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/conv_abc123" \
  -H "X-API-Key: ak_live_xxxx"

{
  "status": "deleted"
}

Restore Conversation

Restore a previously soft-deleted conversation.

curl -X POST "https://apps.aurionai.net/api/v2/conversations/conv_abc123/restore" \
  -H "X-API-Key: ak_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/conv_abc123/archive" \
  -H "X-API-Key: ak_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/conv_abc123/unarchive" \
  -H "X-API-Key: ak_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/conv_abc123/read" \
  -H "X-API-Key: ak_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_token_abc123"

{
  "id": "conv_abc123",
  "subject": "Cannot access email",
  "channel": "email",
  "status": "open",
  "messages": [
    {
      "id": "msg_001",
      "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_token_abc123/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": "msg_shared_001",
  "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 Scopes

Scope 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/activities/export, GET /v2/conversations/:id/attachments/:id/download, GET /v2/conversations/filter-options, GET /v2/conversations/tags/search

conversations:write POST /v2/conversations, PATCH /v2/conversations/:id, POST /v2/conversations/:id/reply, POST /v2/conversations/:id/assign, POST /v2/conversations/:id/reassign, POST /v2/conversations/:id/unassign, POST /v2/conversations/search, POST /v2/conversations/:id/parent, PUT /v2/conversations/:id/resolution, POST /v2/conversations/:id/spam, POST /v2/conversations/:id/unspam, DELETE /v2/conversations/:id, POST /v2/conversations/:id/restore, POST /v2/conversations/:id/archive, POST /v2/conversations/:id/unarchive, PATCH /v2/conversations/:id/read, DELETE /v2/conversations/:id/links/:id, DELETE /v2/conversations/:id/attachments/:id

Scope	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/activities/export`, `GET /v2/conversations/:id/attachments/:id/download`, `GET /v2/conversations/filter-options`, `GET /v2/conversations/tags/search`
`conversations:write`	`POST /v2/conversations`, `PATCH /v2/conversations/:id`, `POST /v2/conversations/:id/reply`, `POST /v2/conversations/:id/assign`, `POST /v2/conversations/:id/reassign`, `POST /v2/conversations/:id/unassign`, `POST /v2/conversations/search`, `POST /v2/conversations/:id/parent`, `PUT /v2/conversations/:id/resolution`, `POST /v2/conversations/:id/spam`, `POST /v2/conversations/:id/unspam`, `DELETE /v2/conversations/:id`, `POST /v2/conversations/:id/restore`, `POST /v2/conversations/:id/archive`, `POST /v2/conversations/:id/unarchive`, `PATCH /v2/conversations/:id/read`, `DELETE /v2/conversations/:id/links/:id`, `DELETE /v2/conversations/:id/attachments/:id`

Conversations

On this page