Skip to content
Optiwork API Docs

List the messages of a conversation

GET
/chats/{chat}/messages
curl --request GET \
  --url 'https://chat.work.optidata.cloud/api/chats/36/messages?page=1' \
  --header 'Authorization: Bearer <token>'

A page of messages, newest page first, with their files, reactions, poll summary, reply target and sender.

The page is chosen for you: the server counts how many messages sit above your last-seen one and returns the page that contains it, so an unattended call lands on the conversation’s unread boundary rather than at the top. Pass message_id to anchor on a specific message instead, or search to filter the conversation’s messages by text.

If the caller was removed from the conversation, the listing stops at the message that was current when they left.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
chat
required
integer format: int64

Numeric id of the conversation.

Query Parameters

Section titled “Query Parameters”
search
string

Return only messages whose content contains this text (accent-insensitive).

message_id
integer format: int64

Anchor the page on this message instead of the last-seen one.

page
integer
default: 1 >= 1

1-based page number.

Responses

Section titled “ Responses ”

200

Section titled “200”

A page of messages.

Media typeapplication/json
object
current_page
integer
data
Array
first_page_url
string | null format: uri
from
integer | null
last_page
integer
last_page_url
string | null format: uri
links
Array<object>

Navigation links of a paginated envelope.

object
url
string | null format: uri
label
string
page
integer | null
active
boolean
next_page_url
string | null format: uri
path
string format: uri
per_page
integer
prev_page_url
string | null format: uri
to
integer | null
total
integer
data
Array<object>

One message. type separates what a person wrote (USER) from what the service recorded about the conversation (SYSTEM) — a rename, a join, a departure. Render SYSTEM messages as notices, not as chat bubbles; their data holds the details of what happened.

object
id
required
integer format: int64
chat_id
required
integer format: int64
user_id
required

Author of the message.

integer format: int64
parent_id

The message this one replies to, or null.

integer | null format: int64
type
required
string
Allowed values: USER SYSTEM
hash
required

Stable identifier of the message. This is what POST /chats/messages/forward takes.

string
idempotency_hash

The client-supplied value that made the send idempotent.

string | null
content

The message text.

string | null
data

Structured payload. On a SYSTEM message it describes the event; on a USER message it carries the mentioned user ids, when there are any.

object | null
meta
object | null
origin

Where the message came in from — chat for Talk itself, or the name of the external messaging integration that relayed it.

string
is_seen
boolean
is_forwarded

true when the message was copied here from another conversation.

boolean
is_important
boolean
is_favorite

1 when the caller has favourited this message, 0 otherwise.

integer
has_user_mentions
boolean
views

How many participants have seen the message.

integer
order_in_chat

Position of the message within the conversation.

integer
message_link_id
integer | null format: int64
user

The trimmed user record embedded in message payloads and search results.

object
id
required
integer format: int64
uuid
required
string format: uuid
name
required
string
email
string format: email
cuid
string
avatar_url
string | null format: uri
deleted_at
string | null format: date-time
whatsapp_info

Details of the linked external-messaging contact, present when the embedded user is one (type 2); null otherwise. Open object.

object | null
files
Array<object>

A file attached to a message.

object
id
integer format: int64
message_id
integer format: int64
chat_id
integer | null format: int64
cuid
string
hash

Alternative identifier accepted by the attachment content endpoints.

string | null
name
string
url
string | null format: uri
mime_type
string | null
size

Size in bytes.

integer | null
audio

true for a voice message.

boolean | null
duration

Playback length in seconds, for audio and video.

string | null
preview

Thumbnail, when one was generated.

string | null
type
string | null
meta

Storage metadata. Its keys depend on where the file is stored, so treat it as an open object.

object | null
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
link

Preview of the first link found in the text, when there is one.

object | null
reply_message
One of:
null
reactions

Reactions on the message: the ids of the users who left each emoji, keyed by the emoji. Empty when nobody has reacted.

object
key
additional properties
Array<integer>
poll
One of:
null
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
Example
{
  "current_page": 1,
  "data": [
    {
      "type": "USER",
      "origin": "chat"
    }
  ]
}

401

Section titled “401”

Missing, malformed or expired authentication key.

Media typeapplication/json

Authentication failures — and a few permission denials — use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

403

Section titled “403”

The caller is not a participant of the conversation, or lacks the role the operation requires.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Exampledenied
{
  "message": "This action is unauthorized."
}

404

Section titled “404”

The resource does not exist, or does not belong to the given conversation.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Examplemissing
{
  "message": "No query results for model [App\\Models\\Chat\\Chat] 99999999"
}

422

Section titled “422”

The request body or query string failed validation.

Media typeapplication/json
object
message
required

The first validation message.

string
errors
required

Validation messages keyed by field name.

object
key
additional properties
Array<string>
Examples
Exampleinvalid
{
  "message": "The content field is required.",
  "errors": {
    "content": [
      "The content field is required."
    ]
  }
}

429

Section titled “429”

Rate limit exceeded. Retry after the window resets.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Examplethrottled
{
  "message": "Too Many Attempts."
}