List Messages

List CometChat messages with REST API using filters for users, groups, categories, types, timestamps, and threads.

GET /messages

List Messages

cURL

curl --request GET \
  --url https://{appId}.api-{region}.cometchat.io/v3/messages \
  --header 'apikey: <api-key>'

import requests

url = "https://{appId}.api-{region}.cometchat.io/v3/messages"

headers = {"apikey": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {apikey: '<api-key>'}};

fetch('https://{appId}.api-{region}.cometchat.io/v3/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{appId}.api-{region}.cometchat.io/v3/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "apikey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{appId}.api-{region}.cometchat.io/v3/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("apikey", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://{appId}.api-{region}.cometchat.io/v3/messages")
  .header("apikey", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{appId}.api-{region}.cometchat.io/v3/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["apikey"] = '<api-key>'

response = http.request(request)
puts response.read_body

200

{
  "data": [
    {
      "id": "1",
      "conversationId": "superhero3_user_superhero5",
      "sender": "superhero3",
      "receiverType": "user",
      "receiver": "superhero5",
      "category": "message",
      "type": "text",
      "data": {
        "text": "test     hello",
        "entities": {
          "sender": {
            "entity": {
              "uid": "superhero3",
              "name": "Spiderman",
              "role": "default",
              "avatar": "https://data-us.cometchat.io/assets/images/avatars/spiderman.png",
              "status": "offline",
              "createdAt": 1638361550
            },
            "entityType": "user"
          },
          "receiver": {
            "entity": {
              "uid": "superhero5",
              "name": "Cyclops",
              "role": "default",
              "avatar": "https://data-us.cometchat.io/assets/images/avatars/cyclops.png",
              "status": "offline",
              "createdAt": 1638361550,
              "conversationId": "superhero3_user_superhero5"
            },
            "entityType": "user"
          }
        },
        "metadata": {
          "key1": "val1"
        }
      },
      "sentAt": 1638423490,
      "updatedAt": 1638423490
    }
  ],
  "meta": {
    "current": {
      "limit": 100,
      "count": 1
    },
    "next": {
      "affix": "append",
      "sentAt": 1638423490,
      "id": "1"
    }
  }
}

For the complete error reference, see Error Guide.

Authorizations

apikey · string · header · required

API Key with fullAccess scope(i.e. Rest API Key from the Dashboard).

Headers

onBehalfOf · string

UID of the user on whose behalf the action is performed.

Query Parameters

searchKey · string

Fetches messages that include the searchKey.

hideMessagesFromBlockedUsers · boolean

Fetches messages sent by users who are blocked by the requesting user.

hasAttachments · boolean

Fetches messages that include attachments.

attachmentTypes · enum<string>

Displays messages according to the type of attachment. Supported types include: image, video, audio, and file.

Available options: image, video, audio, file

hasMentions · boolean

Fetches messages that include mentions.

hasLinks · boolean

Fetches messages that include links.

mentionedUids · boolean

Fetches messages that include the mentioned comma-separated UIDs.

hasReactions · boolean

Fetches messages that include reactions.

receiverType · enum<string>

Displays messages based on receiverType (user/group)

Available options: user, group

affix · string

Determines whether to pull the messages either before or after any message id. Possible values are append(after) and prepend(before).

id · string

Retrieves all those messages after the passed id.

category · enum<string>

Filters messages by category. Possible values: message, action and custom.

Available options: message, action, custom

type · string

Filters messages by type.

sender · string

Filters messages with sender. If onBehalfOf header is also set then the messages from their common conversations will be filtered.

senders · string[]

Filter messages by multiple sender UIDs. Accepts comma-separated UID values.

mentionsWithBlockedInfo · boolean

For the mentioned users, provides blocked information with respect to the UID in onBehalfOf header.

mentionsWithTagInfo · boolean

Provides user tags for the mentioned users.

hideDeleted · boolean

Hides deleted messages from List.

onlyDeleted · boolean

Includes only deleted messages in List.

hideReplies · boolean

Shows only messages skipping the replies in the message thread.

count · boolean

Includes unread message count in List.

unread · boolean

Retrieves all the unread messages in a conversation. It must be used alongside count query parameter.

sentAt · integer

Fetches the messages list after a particular sentAt timestamp.

sentAt[from] · integer

Filter by sentAt start timestamp (Unix timestamp). Filters messages sent on or after this timestamp. Can be used with sentAt[to] for a date range.

Example:

1738368000

sentAt[to] · integer

Filter by sentAt end timestamp (Unix timestamp). Filters messages sent on or before this timestamp. Can be used with sentAt[from] for a date range.

Example:

1739059200

updatedAt[from] · integer

Filter by updatedAt start timestamp (Unix timestamp). Filters messages updated on or after this timestamp. Only returns messages that have actually been updated (excludes messages where updatedAt equals createdAt). Can be used with updatedAt[to] for a date range.

Example:

1738368000

updatedAt[to] · integer

Filter by updatedAt end timestamp (Unix timestamp). Filters messages updated on or before this timestamp. Only returns messages that have actually been updated (excludes messages where updatedAt equals createdAt). Can be used with updatedAt[from] for a date range.

Example:

1739059200

editedAt[from] · integer

Filter by editedAt start timestamp (Unix timestamp). Filters messages edited on or after this timestamp. Can be used with editedAt[to] for a date range.

Example:

1738368000

editedAt[to] · integer

Filter by editedAt end timestamp (Unix timestamp). Filters messages edited on or before this timestamp. Can be used with editedAt[from] for a date range.

Example:

1739059200

limit · integer · default: 10

The number of records to fetch. Minimum value: 1, Maximum value: 1000

conversationId · string

Fetches all the messages belong to a particular conversation.

withTags · boolean

This will fetch messages along with the tags.

tags · string[]

This will fetch only those messages belonging to the mentioned tags.

categories · string[]

Fetches messages based on multiple categories.

types · any[]

Fetches messages based on multiple types.

fromTimestamp · integer

Fetches the messages from this timestamp.

toTimestamp · integer

Fetches the messages till this timestamp. It will be ignored if fromTimestamp is missing or empty.

hideQuotedMessages · boolean

If set to true, the API response will exclude all quotedMessage nodes from the returned messages. This allows clients to fetch only the messages without any quoted messages.

Response

200 - application/json

List Message

data · any[]

meta · object