API reference

Conversations

List, read, and update conversations.

Every request needs x-tenant-id and an API key or OAuth token. Channel IDs are copied from Settings → Developer in the app. See Authentication.

List conversations

get/api/public/v1/conversations

Returns a paginated, filterable, sortable list of conversations for the authenticated tenant.

Query parameters

pageinteger
Default 1
limitinteger
Default 25
sortstring
lastMessageAtcreatedAtupdatedAtunreadCountprioritystatusresolutionDueAt
Default "lastMessageAt"
orderstring
ascdesc
Default "desc"
statusstring
openpendingresolvedclosedarchived
assignedTostring
Agent id, or 'unassigned'.
prioritystring
lowmediumhighurgent
labelstring
Comma-separated label id filter.
channelstring
Channel id filter.
searchstring
Matches contact name/phone, agent name, or label name.
createdAfterstring (date-time)
createdBeforestring (date-time)
updatedAfterstring (date-time)
updatedBeforestring (date-time)
fieldsstring

Response 200Paginated list of conversations

successboolean
dataobject[]
25 child fields
- idstring
- contactIdstring | null
- channelIdstring | null
- assignedAgentIdstring | null
- statusstring
  One ofopenpendingresolvedclosedarchived
- prioritystring
  One oflowmediumhighurgent
- isArchivedboolean
- labelIdsstring[]
- labelsobject[]
  3 child fields
  idstring | null
  namestring | null
  colorstring | null
- unreadCountinteger
- lastMessagePreviewstring | null
- lastMessageAtstring (date-time) | null
- lastMessageDirectionstring | null
- isPinnedboolean
- isMutedboolean
- isResolvedboolean
- startedAtstring (date-time) | null
- resolvedAtstring (date-time) | null
- closedAtstring (date-time) | null
- sourcestring | null
- createdAtstring (date-time)
- updatedAtstring (date-time)
- contactobject
  4 child fields
  idstring | null
  namestring | null
  phonestring | null
  emailstring | null
- channelobject
  3 child fields
  idstring | null
  namestring | null
  typestring | null
- assignedAgentobject
  3 child fields
  idstring | null
  fullNamestring | null
  emailstring | null
paginationobject
8 child fields
- pageinteger
- limitinteger
- totalinteger
- totalPagesinteger
- hasNextPageboolean
- hasPrevPageboolean
- nextCursorstring | null
- prevCursorstring | null
metaobject
1 child field
- apiVersionstring
requestIdstring | null
timestampstring (date-time)

Errors

400Malformed request or missing tenant context
401Missing or invalid API key
403Forbidden — developer platform disabled, key expired/disabled, or tenant mismatch
422Validation failed
429Too many requests — rate limit exceeded
500Unexpected server error

Error envelope and fixes →

curl -X GET "https://api.inaiy.com/api/public/v1/conversations" \
  -H "x-tenant-id: demo" \
  -H "x-api-key: wp_live_xxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "6650a1b2c3d4e5f6a7b8c9d0",
      "contactId": "664fa1b2c3d4e5f6a7b8c9d0",
      "channelId": "663fa1b2c3d4e5f6a7b8c9d0",
      "assignedAgentId": "662fa1b2c3d4e5f6a7b8c9d0",
      "status": "open",
      "priority": "medium",
      "isArchived": false,
      "labelIds": [
        "661fa1b2c3d4e5f6a7b8c9d0"
      ],
      "labels": [
        {
          "id": "661fa1b2c3d4e5f6a7b8c9d0",
          "name": "VIP",
          "color": "#6366f1"
        }
      ],
      "unreadCount": 2,
      "lastMessagePreview": "See you tomorrow!",
      "lastMessageAt": "2026-07-12T09:30:00.000Z",
      "lastMessageDirection": "inbound",
      "isPinned": false,
      "isMuted": false,
      "isResolved": false,
      "startedAt": "2026-07-10T08:00:00.000Z",
      "resolvedAt": null,
      "closedAt": null,
      "source": "whatsapp",
      "createdAt": "2026-07-10T08:00:00.000Z",
      "updatedAt": "2026-07-12T09:30:00.000Z",
      "contact": {
        "id": "664fa1b2c3d4e5f6a7b8c9d0",
        "name": "Jane Doe",
        "phone": "+14155552671",
        "email": "jane@example.com"
      },
      "channel": {
        "id": "663fa1b2c3d4e5f6a7b8c9d0",
        "name": "Main WhatsApp",
        "type": "whatsapp"
      },
      "assignedAgent": {
        "id": "662fa1b2c3d4e5f6a7b8c9d0",
        "fullName": "Alex Agent",
        "email": "alex@company.com"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 137,
    "totalPages": 6,
    "hasNextPage": true,
    "hasPrevPage": false,
    "nextCursor": null,
    "prevCursor": null
  },
  "meta": {
    "apiVersion": "v1",
    "sort": {
      "field": "lastMessageAt",
      "order": "desc"
    }
  },
  "requestId": "a1f4c2e0-9b6d-4a1e-8c3f-2d7e5b9a0c11",
  "timestamp": "2026-07-12T09:30:00.000Z"
}

Get a conversation by id

get/api/public/v1/conversations/{id}

Fetch a single conversation by its public id.

Path parameters

idstringrequired
24-char conversation ObjectId

Query parameters

fieldsstring
Comma-separated list of fields to return (sparse fieldset).

Response 200The conversation

successboolean
dataobject
25 child fields
- idstring
- contactIdstring | null
- channelIdstring | null
- assignedAgentIdstring | null
- statusstring
  One ofopenpendingresolvedclosedarchived
- prioritystring
  One oflowmediumhighurgent
- isArchivedboolean
- labelIdsstring[]
- labelsobject[]
  3 child fields
  idstring | null
  namestring | null
  colorstring | null
- unreadCountinteger
- lastMessagePreviewstring | null
- lastMessageAtstring (date-time) | null
- lastMessageDirectionstring | null
- isPinnedboolean
- isMutedboolean
- isResolvedboolean
- startedAtstring (date-time) | null
- resolvedAtstring (date-time) | null
- closedAtstring (date-time) | null
- sourcestring | null
- createdAtstring (date-time)
- updatedAtstring (date-time)
- contactobject
  4 child fields
  idstring | null
  namestring | null
  phonestring | null
  emailstring | null
- channelobject
  3 child fields
  idstring | null
  namestring | null
  typestring | null
- assignedAgentobject
  3 child fields
  idstring | null
  fullNamestring | null
  emailstring | null
metaobject
1 child field
- apiVersionstring
requestIdstring | null
timestampstring (date-time)

Errors

400Malformed request or missing tenant context
401Missing or invalid API key
403Forbidden — developer platform disabled, key expired/disabled, or tenant mismatch
404Conversation not found
429Too many requests — rate limit exceeded
500Unexpected server error

Error envelope and fixes →

curl -X GET "https://api.inaiy.com/api/public/v1/conversations/6650a1b2c3d4e5f6a7b8c9d0" \
  -H "x-tenant-id: demo" \
  -H "x-api-key: wp_live_xxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "success": true,
  "data": {
    "id": "6650a1b2c3d4e5f6a7b8c9d0",
    "contactId": "664fa1b2c3d4e5f6a7b8c9d0",
    "channelId": "663fa1b2c3d4e5f6a7b8c9d0",
    "assignedAgentId": "662fa1b2c3d4e5f6a7b8c9d0",
    "status": "open",
    "priority": "medium",
    "isArchived": false,
    "labelIds": [
      "661fa1b2c3d4e5f6a7b8c9d0"
    ],
    "labels": [
      {
        "id": "661fa1b2c3d4e5f6a7b8c9d0",
        "name": "VIP",
        "color": "#6366f1"
      }
    ],
    "unreadCount": 2,
    "lastMessagePreview": "See you tomorrow!",
    "lastMessageAt": "2026-07-12T09:30:00.000Z",
    "lastMessageDirection": "inbound",
    "isPinned": false,
    "isMuted": false,
    "isResolved": false,
    "startedAt": "2026-07-10T08:00:00.000Z",
    "resolvedAt": null,
    "closedAt": null,
    "source": "whatsapp",
    "createdAt": "2026-07-10T08:00:00.000Z",
    "updatedAt": "2026-07-12T09:30:00.000Z",
    "contact": {
      "id": "664fa1b2c3d4e5f6a7b8c9d0",
      "name": "Jane Doe",
      "phone": "+14155552671",
      "email": "jane@example.com"
    },
    "channel": {
      "id": "663fa1b2c3d4e5f6a7b8c9d0",
      "name": "Main WhatsApp",
      "type": "whatsapp"
    },
    "assignedAgent": {
      "id": "662fa1b2c3d4e5f6a7b8c9d0",
      "fullName": "Alex Agent",
      "email": "alex@company.com"
    }
  },
  "meta": {
    "apiVersion": "v1"
  },
  "requestId": "a1f4c2e0-9b6d-4a1e-8c3f-2d7e5b9a0c11",
  "timestamp": "2026-07-12T09:30:00.000Z"
}

Update a conversation

patch/api/public/v1/conversations/{id}

Consolidated update supporting assign/unassign agent, status change, archive, priority, and add/remove labels. Provide at least one field. Message sending is not supported.

Path parameters

idstringrequired
24-char conversation ObjectId

Request body

statusstring
One ofopenpendingresolvedclosedarchived
prioritystring
One oflowmediumhighurgent
assignedAgentIdstring | null
24-char agent ObjectId to assign, or null to unassign.
archivedboolean
addLabelsstring[]
removeLabelsstring[]

Response 200Conversation updated

successboolean
dataobject
25 child fields
- idstring
- contactIdstring | null
- channelIdstring | null
- assignedAgentIdstring | null
- statusstring
  One ofopenpendingresolvedclosedarchived
- prioritystring
  One oflowmediumhighurgent
- isArchivedboolean
- labelIdsstring[]
- labelsobject[]
  3 child fields
  idstring | null
  namestring | null
  colorstring | null
- unreadCountinteger
- lastMessagePreviewstring | null
- lastMessageAtstring (date-time) | null
- lastMessageDirectionstring | null
- isPinnedboolean
- isMutedboolean
- isResolvedboolean
- startedAtstring (date-time) | null
- resolvedAtstring (date-time) | null
- closedAtstring (date-time) | null
- sourcestring | null
- createdAtstring (date-time)
- updatedAtstring (date-time)
- contactobject
  4 child fields
  idstring | null
  namestring | null
  phonestring | null
  emailstring | null
- channelobject
  3 child fields
  idstring | null
  namestring | null
  typestring | null
- assignedAgentobject
  3 child fields
  idstring | null
  fullNamestring | null
  emailstring | null
metaobject
1 child field
- apiVersionstring
requestIdstring | null
timestampstring (date-time)

Errors

400Malformed request or missing tenant context
401Missing or invalid API key
403Forbidden — developer platform disabled, key expired/disabled, or tenant mismatch
404Conversation not found
409Invalid status transition or conflicting update
422Validation failed
429Too many requests — rate limit exceeded
500Unexpected server error

Error envelope and fixes →

curl -X PATCH "https://api.inaiy.com/api/public/v1/conversations/6650a1b2c3d4e5f6a7b8c9d0" \
  -H "x-tenant-id: demo" \
  -H "x-api-key: wp_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved","priority":"high","assignedAgentId":"662fa1b2c3d4e5f6a7b8c9d0"}'

Request body

{
  "status": "resolved",
  "priority": "high",
  "assignedAgentId": "662fa1b2c3d4e5f6a7b8c9d0"
}

Response 200

{
  "success": true,
  "data": {
    "id": "6650a1b2c3d4e5f6a7b8c9d0",
    "contactId": "664fa1b2c3d4e5f6a7b8c9d0",
    "channelId": "663fa1b2c3d4e5f6a7b8c9d0",
    "assignedAgentId": "662fa1b2c3d4e5f6a7b8c9d0",
    "status": "open",
    "priority": "medium",
    "isArchived": false,
    "labelIds": [
      "661fa1b2c3d4e5f6a7b8c9d0"
    ],
    "labels": [
      {
        "id": "661fa1b2c3d4e5f6a7b8c9d0",
        "name": "VIP",
        "color": "#6366f1"
      }
    ],
    "unreadCount": 2,
    "lastMessagePreview": "See you tomorrow!",
    "lastMessageAt": "2026-07-12T09:30:00.000Z",
    "lastMessageDirection": "inbound",
    "isPinned": false,
    "isMuted": false,
    "isResolved": false,
    "startedAt": "2026-07-10T08:00:00.000Z",
    "resolvedAt": null,
    "closedAt": null,
    "source": "whatsapp",
    "createdAt": "2026-07-10T08:00:00.000Z",
    "updatedAt": "2026-07-12T09:30:00.000Z",
    "contact": {
      "id": "664fa1b2c3d4e5f6a7b8c9d0",
      "name": "Jane Doe",
      "phone": "+14155552671",
      "email": "jane@example.com"
    },
    "channel": {
      "id": "663fa1b2c3d4e5f6a7b8c9d0",
      "name": "Main WhatsApp",
      "type": "whatsapp"
    },
    "assignedAgent": {
      "id": "662fa1b2c3d4e5f6a7b8c9d0",
      "fullName": "Alex Agent",
      "email": "alex@company.com"
    }
  },
  "meta": {
    "apiVersion": "v1"
  },
  "requestId": "a1f4c2e0-9b6d-4a1e-8c3f-2d7e5b9a0c11",
  "timestamp": "2026-07-12T09:30:00.000Z"
}