AISARAISAR
REST API

Conversations

A conversation is the umbrella record for all communication with a single contact, grouping one or more channel-specific threads (WhatsApp, Telegram, Instagram, etc). These endpoints manage a conversation's lifecycle — opening and closing it, assigning participants (operators) via the participants sub-resource, keeping internal notes and tags, and reading its unified event timeline and thread structure. Most mutating actions append to the conversation's event log, readable via `GET /conversations/{id}/events`.

Endpoints

MethodPath
GET/v1/conversations/counters

Conversation counters by status (all/awaiting/unread/assigned/unassigned/archived).

GET/v1/conversations

List the company's conversations with pagination and filters.

POST/v1/conversations

Create a new conversation for a contact.

GET/v1/conversations/{conversation}

Get a conversation by id (with contact, threads, participants).

PATCH/v1/conversations/{conversation}

Update conversation fields (subject, lifecycle status, archival).

DELETE/v1/conversations/{conversation}

Delete a conversation (soft delete).

POST/v1/conversations/{conversation}/close

Close a conversation with a required comment.

POST/v1/conversations/{conversation}/open

Open (reopen) a closed conversation.

POST/v1/conversations/{conversation}/archive

Archive a conversation.

POST/v1/conversations/{conversation}/unarchive

Unarchive a conversation.

GET/v1/conversations/{conversation}/participants

List conversation participants (operators, teams, bots).

POST/v1/conversations/{conversation}/participants

Add a participant — e.g. assign an operator as the primary owner (is_primary).

DELETE/v1/conversations/{conversation}/participants/{participant}

Remove a participant from the conversation (unassign).

GET/v1/conversations/{conversation}/tags

List conversation tags.

POST/v1/conversations/{conversation}/tags

Add a tag to the conversation.

DELETE/v1/conversations/{conversation}/tags/{tag}

Remove a tag from the conversation.

GET/v1/conversations/{conversation}/notes

List internal notes on the conversation.

POST/v1/conversations/{conversation}/notes

Add an internal note (not visible to the contact).

PATCH/v1/conversations/{conversation}/notes/{note}

Edit a note's body.

DELETE/v1/conversations/{conversation}/notes/{note}

Delete a note.

GET/v1/conversations/{conversation}/events

Conversation event timeline (created, comments, status changes, assignments).

POST/v1/conversations/{conversation}/events

Log an event on the conversation timeline (e.g. an operator comment).

GET/v1/conversations/{conversation}/threads

List threads (per-channel conversations) inside the conversation.

POST/v1/conversations/{conversation}/threads

Create a new thread inside an existing conversation for an additional channel.

POST/v1/conversations/mark-read

Mark all (or the given) company conversations as read.

POST/v1/conversations/{conversation}/mark-read

Mark a specific conversation (or one of its threads) as read.

Examples

List unassigned conversations

Request

bash
curl -X GET "https://api.aisar.app/v1/conversations?thread_filter=unassigned&perPage=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

json
{
  "data": {
    "items": [
      {
        "id": 15,
        "company_id": 1,
        "contact_id": 45,
        "subject": null,
        "lifecycle_status": "active",
        "is_closed": false,
        "is_archived": false,
        "last_message_id": 1001,
        "last_message_at": "2026-02-09T18:00:00Z",
        "last_message": { "id": 1001, "message_content": { "text": "Здравствуйте, подскажите по заказу" }, "direction": "inbound" },
        "unread_count_for_current_user": 1,
        "closed_at": null,
        "archived_at": null,
        "created_at": "2026-02-09T17:00:00Z",
        "updated_at": "2026-02-09T18:00:00Z",
        "contact": { "id": 45, "displayName": "John Doe", "phones": [{ "phone": "+77001234567", "type": "mobile" }] },
        "threads": [{ "id": 33, "channel_id": 3, "is_group": false }]
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 1, "lastPage": 1 },
    "counters": { "all": 120, "awaiting": 21, "unread": 14, "assigned": 47, "unassigned": 73, "archived": 9 }
  }
}

Close a conversation

Request

bash
curl -X POST "https://api.aisar.app/v1/conversations/15/close" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Вопрос клиента решён, заказ подтверждён."
  }'

Response

json
{
  "data": {
    "message": "Conversation closed.",
    "conversation": {
      "id": 15,
      "lifecycle_status": "closed",
      "is_closed": true,
      "closed_at": "2026-02-09T18:20:00Z"
    }
  }
}