Conversations (Tickets) API Reference

Conversations (Tickets) API

The Conversations API is the core of the OnCodes support helpdesk. It handles ticket creation, retrieval, replies, status changes, and more. All endpoints are under /api/v1/helpdesk/ and require an active authenticated session.

Base URL

https://support.oncodes.com/api/v1/helpdesk/

Authentication

Extract the CSRF token from the browser cookie and include it as a header on all mutating requests:

X-XSRF-TOKEN: <decoded value of XSRF-TOKEN cookie>
Content-Type: application/json
Accept: application/json

// Get token in browser console:
decodeURIComponent(document.cookie.match(/XSRF-TOKEN=([^;]+)/)[1])

Conversations

List Conversations

Endpoint: GET /api/v1/helpdesk/agent/conversations

Returns a paginated list of conversations. Supports filtering by status, assignee, and other attributes.

Query Parameters

Filter Keys

Filter Example

// Get all pending conversations
GET /api/v1/helpdesk/agent/conversations?page=1&perPage=15&viewId=all&filters=[{"key":"status","value":"pending"}]

Response

{
  "pagination": {
    "data": [
      {
        "id": 1274,
        "type": "ticket",
        "subject": "Test Ticket - API Documentation Sample",
        "status_category": 5,
        "status_label": "Pending",
        "customer_status_label": "Waiting on you",
        "channel": "website",
        "priority": 0,
        "updated_at": "2026-02-26T08:32:00.000000Z",
        "created_at": "2026-02-26T08:31:02.000000Z",
        "closed_at": null,
        "assigned_at": "...",
        "closed_by": null,
        "latest_message": { ... },
        "group": null,
        "assignee": { "id": 1, "name": "OnCodes" },
        "user": { "id": 3, "name": "underwoo_d" },
        "tags": [],
        "attributes": { ... }
      }
    ],
    "next_cursor": null,
    "prev_cursor": null,
    "per_page": 15
  },
  "status": "success"
}

Get Conversation

Endpoint: GET /api/v1/helpdesk/agent/conversations/{id}

Returns full details of a single conversation including customer, assignee, group, tags, status, and recent messages.

Response Fields

Create Conversation

Endpoint: POST /api/v1/helpdesk/agent/conversations

Creates a new conversation/ticket. Returns 200 OK on success.

Request Body

Example Request

fetch('https://support.oncodes.com/api/v1/helpdesk/agent/conversations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'X-XSRF-TOKEN': decodeURIComponent(document.cookie.match(/XSRF-TOKEN=([^;]+)/)[1])
  },
  body: JSON.stringify({
    subject: 'My Support Ticket',
    message: 'I need help with...',
    userId: 3,
    status: 'open',
    categoryId: 1
  })
});

Response

HTTP 200 OK
{
  "conversation": {
    "id": 1274,
    "subject": "My Support Ticket",
    "status_id": 1,
    ...
  },
  "status": "success"
}

Update Conversation

Endpoint: PUT /api/v1/helpdesk/agent/conversations/{id}

Updates conversation properties such as subject, assignee, group, or priority. Note: to change status, use the dedicated Change Status endpoint instead.

Updatable Fields

Note: Only GET, PUT, and DELETE are supported. PATCH returns 405 Method Not Allowed.

Delete Conversation

Endpoint: DELETE /api/v1/helpdesk/agent/conversations/{id}

Permanently deletes a conversation. Returns 204 No Content on success (even if ID does not exist).

Change Conversation Status

Endpoint: POST /api/v1/helpdesk/agent/conversations/status/change

Changes the status of one or more conversations. Supports bulk status updates.

Request Body

Example — Mark as Resolved

fetch('/api/v1/helpdesk/agent/conversations/status/change', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-XSRF-TOKEN': token },
  body: JSON.stringify({
    conversationIds: [1274],
    statusId: 3
  })
});

Response

HTTP 200 OK
{ "status": "success" }

Status Reference

Messages

List Messages

Endpoint: GET /api/v1/helpdesk/agent/conversations/{id}/messages

Returns all messages for a conversation using cursor-based pagination.

Response

{
  "pagination": {
    "data": [
      {
        "id": 5104,
        "uuid": "66b26668-...",
        "type": "message",
        "author": "agent",
        "body": "<p>Message content</p>",
        "created_at": "2026-02-26T08:31:02.000000Z",
        "user": { "id": 1, "name": "OnCodes" },
        "conversation_id": 1274,
        "source": null,
        "data": null,
        "attachments": []
      }
    ],
    "next_cursor": null,
    "prev_cursor": null,
    "per_page": 20
  }
}

Message Types

Send Message / Reply

Endpoint: POST /api/v1/helpdesk/agent/conversations/{id}/messages

Sends a reply to the customer or adds an internal note. Returns 201 Created.

Request Body

Example — Reply to Customer

fetch('/api/v1/helpdesk/agent/conversations/1274/messages', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-XSRF-TOKEN': token },
  body: JSON.stringify({
    body: '<p>Thank you for reaching out! We will address your issue shortly.</p>',
    type: 'message'
  })
});

Example — Add Internal Note

fetch('/api/v1/helpdesk/agent/conversations/1274/messages', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-XSRF-TOKEN': token },
  body: JSON.stringify({
    body: '<p>Customer contacted support about billing issue.</p>',
    type: 'note'
  })
});

Response

HTTP 201 Created
{
  "message": {
    "id": 5105,
    "uuid": "abc-...",
    "type": "message",
    "author": "agent",
    "body": "<p>Thank you for reaching out!</p>",
    "created_at": "2026-02-26T08:32:00.000000Z",
    "conversation_id": 1274,
    "user_id": 1,
    "attachments": [],
    "model_type": "conversationItem"
  },
  "status": "success"
}

Inbox Views

List Views

Endpoint: GET /api/v1/helpdesk/inbox/views

Returns all inbox views including built-in views (Your inbox, Unassigned, All) and custom views, each with conversation counts.

Response

{
  "views": [
    { "id": 2, "key": "mine", "name": "Your inbox", "pinned": true, "icon": "inbox", "count": 1 },
    { "id": 3, "key": "unassigned", "name": "Unassigned", "pinned": true, "icon": "unassigned", "count": 0 },
    { "id": 4, "key": "closed", "name": "Closed", "pinned": true, "icon": "archive", "count": 0 },
    { "id": 5, "key": "all", "name": "All", "pinned": true, "icon": "team", "count": 0 },
    { "id": 1, "key": null, "name": "ChatNet", "pinned": false, "count": 1, "isGroupView": false },
    { "id": "group:1", "key": "group:1", "name": "General", "count": 1, "isGroupView": true }
  ]
}

Use the key value as the viewId query parameter when listing conversations (e.g. viewId=mine, viewId=all).

Statuses

List Statuses

Endpoint: GET /api/v1/helpdesk/statuses/list?label=agent

Returns available conversation statuses.

Response

{
  "statuses": [
    { "id": 1, "label": "Open", "category": 6 },
    { "id": 2, "label": "Pending", "category": 5 },
    { "id": 3, "label": "Resolved", "category": 4 },
    { "id": 4, "label": "Locked", "category": 3 }
  ]
}

Customers (Lookup)

Look Up Customer

Endpoint: GET /api/v1/helpdesk/normalized-models/customer

Returns a list of customers for use in dropdowns. Supports search.

Get Customer by ID

Endpoint: GET /api/v1/helpdesk/normalized-models/customer/{id}

Returns a single customer. Example: customer underwoo_d has ID 3.

Conversation Attributes

List Attributes

Endpoint: GET /api/v1/helpdesk/attributes/list?type=conversation&for=agent&attributeIds=

Returns all configurable conversation attributes, including built-in fields and any custom ones.

Built-in Attribute Fields

Other Useful Endpoints