Chats

Chats · 11 operations

GETList chats/api/chatGETCount chats by state, channel or manager/api/chat/breakdownGETGet chat/api/chat/{id}GETList chat channels/api/chat/channelsGETGet chat messages/api/chat/{id}/messageGETSearch chat messages/api/chat/{id}/message/searchPOSTSend chat message/api/chat/{id}/messagePOSTStart chat/api/chat/startPATCHAssign chat/api/chat/{id}/assignPATCHMark chat as spam/api/chat/{id}/spamPATCHSet chat tag/api/chat/{id}/tag

GET

List chats

/api/chat

Messenger chats with students, teachers, customers and leads (Telegram, iMessage and other connected channels). awaitingReply=true keeps open chats whose last message came from the contact; assignment=UNASSIGNED keeps open chats nobody handles. chatTagIds keeps chats whose tag is any of these (GET /api/chat-tag). Paginated, no total: to count chats use GET /api/chat/breakdown.

list_chats

Query parameters · 25

limitnumberPage size, 30 by default1–100

beforeChatIdnumberCursor: last chat of the shown page (keyset, see buildChatKeysetFilter).min 1

beforeLastMessageAtstringlastMessageAt of the cursor chat, echoed as received (school wall time, no Z). Absent for a chat without messages.

searchstringSearches chat name and message texts; every word must match in either.length max 100

searchScopestringname leaves message texts out of search; the chats page lists message hits through /chat/message/search.One of: all namedefault all

dialogStatusstringOnly chats whose dialog is in this stateOne of: OPEN CLOSED

assignmentstringUNASSIGNED: open dialogs without an assignee; MINE: open dialogs assigned to me. Both imply an open dialog, so dialogStatus is not needed.One of: UNASSIGNED MINE

spambooleanSpam chats only; overrides dialogStatus and assignment, since every work tab excludes spam.

Show 17 more

excludeSpambooleanAll chats except spam, whatever the dialog state

entityTypestringOnly chats linked to a card of this type, none for unlinked; applies on top of tab and search.One of: student teacher customer none

entityTypesstring[]Linked to a card of any of these types; joins entityType rather than replacing it.One of: student teacher customer none

assignedUserIdsnumber[]Chats whose responsible manager is one of these users, open or closed.

includeUnassignedbooleanAdds chats without a responsible manager; alone it keeps only those.

openedStartstringA dialog of the chat was opened from this school-local day on.

openedEndstringInclusive: the end of that school-local day.

closedStartstringA dialog of the chat was closed from this school-local day on.

closedEndstringInclusive: the end of that school-local day.

unreadbooleanChats with inbound messages the current user has not read.

onlyMinebooleanChats assigned to me, on top of tab, type and search; unlike assignment: 'MINE', any dialog state.

awaitingReplybooleanOpen chats whose last message came from the contact: they wait for our reply.

chatTagIdsnumber[]Only chats with any of these chat tags

messengerIdnumberOnly chats of this channelmin 1

studentIdnumbermin 1

teacherIdnumbermin 1

customerIdnumbermin 1

Response · 200

application/json

statusCodenumberrequiredexample 200

messagestringrequired—

dataobject[]17 fields

chatIdnumberrequired—

channelobjectrequired4 fields

messengerIdnumberrequired—

nameOfMessengerstringrequired—

typeOfMessengerstringrequiredOne of: TELEGRAM_BOT INSTAGRAM FACEBOOK IMESSAGE

capabilitiesobjectrequirednullableWhat the channel supports; null when its adapter is not registered, so the chat is read-only.

contactNamestringrequirednullableContact name as given by the channel; read-only.

namestringrequirednullableChat name set in the CRM; null falls back to the card name, then contactName.

avatarstringrequirednullable—

isGroupbooleanrequired—

assignedUserobjectrequirednullableAssignee; null means the chat is in the unassigned queue.3 fields

idnumberrequired—

firstNamestringrequired—

lastNamestringrequirednullable—

participantsobject[]required5 fields

chatParticipantIdnumberrequired—

studentIdnumberrequirednullable—

teacherIdnumberrequirednullable—

customerIdnumberrequirednullable—

personobjectrequirednullableCard name, null for an unlinked participant. Used when the channel gives no name (iMessage labels a direct chat with the phone number).3 fields

firstNamestringrequired—

lastNamestringrequirednullable—

middleNamestringrequirednullable—

lastMessageobjectrequirednullable7 fields

chatMessageIdnumberrequired—

directionstringrequiredOne of: INBOUND OUTBOUND

authorTypestringrequiredOne of: CONTACT USER SYSTEM

textstringrequirednullable—

attachmentTypesstring[]requiredLets the list show an attachment label without fetching attachments.One of: IMAGE VIDEO AUDIO DOCUMENT

isDeletedbooleanrequired—

sentAtstringrequiredformat YYYY-MM-DDTHH:mm:ss

unreadCountnumberrequired—

lastMessageAtstringrequirednullableformat YYYY-MM-DDTHH:mm:ss

isSpambooleanrequiredSpam chats stay out of every work tab and open no dialog until the mark is removed.

spamMarkedAtstringrequirednullableformat YYYY-MM-DDTHH:mm:ss

blockedByContactAtstringrequirednullableThe channel stopped delivering to the contact; cleared by any sign of life from them.format YYYY-MM-DDTHH:mm:ss

blockReasonstringrequirednullableOne of: CONTACT_BLOCKED ACCOUNT_DELETED

openDialogobjectrequirednullableCurrent open dialog, or null; this, not the chat, tells whether it is in work now.14 fields

chatDialogIdnumberrequired—

chatIdnumberrequired—

statusstringrequiredOne of: OPEN CLOSED

openedAtstringrequiredformat YYYY-MM-DDTHH:mm:ss

closedAtstringrequirednullableformat YYYY-MM-DDTHH:mm:ss

openedBystringrequiredWho opened the dialog; SYSTEM is our side without a user (channel echo).One of: CONTACT MANAGER SYSTEM

openedByUserobjectrequirednullableOpening manager; set only for MANAGER.3 fields

idnumberrequired—

firstNamestringrequired—

lastNamestringrequirednullable—

closedByUserobjectrequirednullableNull while open and when auto-closed after inactivity.3 fields

idnumberrequired—

firstNamestringrequired—

lastNamestringrequirednullable—

firstMessageIdnumberrequirednullable—

firstManagerMessageAtstringrequirednullableFirst manager message in the dialog; it assigns the chat to that manager.format YYYY-MM-DDTHH:mm:ss

firstContactMessageAtstringrequirednullableFirst message from the contact (customer, student or teacher).format YYYY-MM-DDTHH:mm:ss

lastMessageAtstringrequirednullableformat YYYY-MM-DDTHH:mm:ss

notSpamAtstringrequirednullableSet when a manager answered the first-contact spam suggestion with "not spam"; spam itself is on the chat.format YYYY-MM-DDTHH:mm:ss

messageCountnumberrequired—

tagobjectrequirednullableOne tag per chat, null — untagged; a chat with a restricted tag the role has no grant for is not returned at all.4 fields

chatTagIdnumberrequired—

nameOfTagstringrequired—

isRestrictedbooleanrequired—

isSilentbooleanrequired—

Errors400401403429500

curl "https://your-school.rist.pro/api/chat" \
  -H "Authorization: Bearer $RIST_API_KEY"

const response = await fetch("https://your-school.rist.pro/api/chat", {
  headers: {
    Authorization: `Bearer ${process.env.RIST_API_KEY}`,
  },
});
const { data } = await response.json();

import os
import requests

response = requests.get(
    "https://your-school.rist.pro/api/chat",
    headers={"Authorization": f"Bearer {os.environ['RIST_API_KEY']}"},
)
response.raise_for_status()
data = response.json()["data"]

Response example · 200

{
  "statusCode": 200,
  "message": "Operation completed successfully",
  "data": [
    {
      "chatId": 1,
      "channel": {
        "messengerId": 1,
        "nameOfMessenger": "string",
        "typeOfMessenger": "TELEGRAM_BOT",
        "capabilities": {}
      },
      "contactName": "string",
      "name": "string",
      "avatar": "string",
      "isGroup": false,
      "assignedUser": {
        "id": 1,
        "firstName": "string",
        "lastName": "string"
      },
      "participants": [
        {
          "chatParticipantId": 1,
          "studentId": 1,
          "teacherId": 1,
          "customerId": 1,
          "person": {
            "firstName": "string",
            "lastName": "string",
            "middleName": "string"
          }
        }
      ],
      "lastMessage": {
        "chatMessageId": 1,
        "direction": "INBOUND",
        "authorType": "CONTACT",
        "text": "string",
        "attachmentTypes": [
          "IMAGE"
        ],
        "isDeleted": false,
        "sentAt": "2026-11-09T14:30:00"
      },
      "unreadCount": 0,
      "lastMessageAt": "2026-11-09T14:30:00",
      "isSpam": false,
      "spamMarkedAt": "2026-11-09T14:30:00",
      "blockedByContactAt": "2026-11-09T14:30:00",
      "blockReason": "CONTACT_BLOCKED",
      "openDialog": {
        "chatDialogId": 1,
        "chatId": 1,
        "status": "OPEN",
        "openedAt": "2026-11-09T14:30:00",
        "closedAt": "2026-11-09T14:30:00",
        "openedBy": "CONTACT",
        "openedByUser": {
          "id": 1,
          "firstName": "string",
          "lastName": "string"
        },
        "closedByUser": {
          "id": 1,
          "firstName": "string",
          "lastName": "string"
        },
        "firstMessageId": 1,
        "firstManagerMessageAt": "2026-11-09T14:30:00",
        "firstContactMessageAt": "2026-11-09T14:30:00",
        "lastMessageAt": "2026-11-09T14:30:00",
        "notSpamAt": "2026-11-09T14:30:00",
        "messageCount": 0
      },
      "tag": {
        "chatTagId": 1,
        "nameOfTag": "string",
        "isRestricted": false,
        "isSilent": false
      }
    }
  ]
}

GET

Count chats by state, channel or manager

/api/chat/breakdown

How many chats match the GET /api/chat filters, per dialog state (OPEN, CLOSED, SPAM), channel or assigned manager (groupBy). messageStart/messageEnd (school days) keep chats with a message from the contact or staff in that period: "unique teacher chats today, open and closed" is entityType=teacher, groupBy=dialogStatus, both set to today. Chats with an isSilent tag never open a dialog, so they count as CLOSED. One call instead of paging through GET /api/chat.

count_chats