Skip to content
Optiwork API Docs

Search your conversations

GET
/chats/search
curl --request GET \
  --url 'https://chat.work.optidata.cloud/api/chats/search?query=launch&archived=false&page=1' \
  --header 'Authorization: Bearer <token>'

Paginated search over the caller’s conversations by name. Set archived=true to search the archived ones instead of the active ones.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
query
string

Free text matched against the conversation name.

archived
boolean

Search archived conversations instead of active ones.

page
integer
default: 1 >= 1

1-based page number.

Responses

Section titled “ Responses ”

200

Section titled “200”

Matching conversations, paginated.

Media typeapplication/json
object
current_page
integer
current_page_url
string format: uri
data
Array
first_page_url
string | null format: uri
from
integer | null
next_page_url
string | null format: uri
path
string format: uri
per_page
integer
prev_page_url
string | null format: uri
to
integer | null
data
Array<object>

A conversation: a private chat, a group or a channel. Which one it is follows from type and is_individual.

Beyond its own columns it carries the caller’s view of it — pivot with their membership, unread_messages_count, and the flattened is_pinned / is_muted / is_archived / draft_message conveniences. Which relations are embedded depends on the endpoint.

object
id
required
integer format: int64
chat_settings_id
integer | null format: int64
cuid

Identifier of the company the conversation belongs to.

string
guid

External identifier, set when the conversation mirrors one in another Optiwork module.

string | null
name

The group or channel name. null on a private conversation, whose name is the other person.

string | null
description
string | null
icon_url
string | null format: uri
hash
string | null
is_individual
required

true for a one-to-one conversation.

boolean
type

What kind of conversation this is: 1 group, 2 private, 3 the user’s own saved-messages space, 4 a conversation created by another Optiwork module, 5 channel, 6 a conversation bridged to an external messaging integration. A freshly created conversation may report null here until it is classified.

integer | null
Allowed values: 1 2 3 4 5 6
visibility

Set on channels; null elsewhere.

string | null
Allowed values: public private
is_webapp_integration_active
boolean
whatsapp_group_id
integer | null format: int64
unread_messages_count

How many messages the caller has not seen.

integer
is_pinned
boolean
is_muted
boolean | null
muted_until
string | null format: date-time
is_archived
boolean
is_current_user_in_chat

false once the caller has left or been removed.

boolean
draft_message

The caller’s unsent text for this conversation.

string | null
active_call

The call currently running in the conversation, or null.

object | null
pivot

One user’s membership of one conversation. It appears as pivot on the conversation payload and carries everything that is personal to that user: their role, their read marker and their pin, mute, archive and draft state.

object
id
integer format: int64
chat_id
integer format: int64
user_id
integer format: int64
role
string
Allowed values: OWNER ADMIN PARTICIPANT
last_message_seen
One of:
null
pinned_at

When the user pinned the conversation, or null.

string | null format: date-time
is_muted
boolean | null
muted_until

When the mute expires. null on an indefinite mute, and on an unmuted conversation. Unlike the other timestamps, the value inside pivot is a plain YYYY-MM-DD HH:MM:SS UTC string, not ISO-8601.

string | null
is_archived
boolean
has_mention

Whether an unread message mentions this user.

boolean
draft_message
string | null
favorited_at
string | null format: date-time
guid
string | null
created_at
string | null format: date-time
updated_at
string | null format: date-time
deleted_at

Set when the user has left or been removed.

string | null format: date-time
settings

Settings that apply to a conversation as a whole.

object
id
integer format: int64
chat_id
integer format: int64
max_users

Participant ceiling, or null when unlimited.

integer | null
is_temporary
boolean
is_read_only

When true, nobody may post.

boolean
is_write_admin_only

When true, only administrators may post.

boolean
unread_message_summary_size

How many unread messages trigger an automatic summary, or null when the feature is off for this conversation.

integer | null
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
users

The participants, each with their own pivot and status.

Array
object
id
required

Numeric id, used on the conversation and participant routes.

integer format: int64
uuid
required

Stable identifier of the user across the Optiwork suite.

string format: uuid
cuid

Identifier of the company the user belongs to.

string
username
string | null
email
required
string format: email
name
required
string
company_name
string | null
type

null for a person. 0 marks the Optiwork AI assistant, 1 a bot and 2 a contact reached over an external messaging integration.

integer | null
dark_mode
boolean
messenger_color

The colour used for this user’s name in the interface.

string
avatar_url
string | null format: uri
created_at
string format: date-time
updated_at
string format: date-time
deleted_at

Set when the user has been removed from the company.

string | null format: date-time
whatsapp_info

Details of the linked external-messaging contact, present when the user is reached over an external messaging integration (type 2); null for an ordinary person. Its keys depend on the integration, so treat it as an open object.

object | null
pivot

One user’s membership of one conversation. It appears as pivot on the conversation payload and carries everything that is personal to that user: their role, their read marker and their pin, mute, archive and draft state.

object
id
integer format: int64
chat_id
integer format: int64
user_id
integer format: int64
role
string
Allowed values: OWNER ADMIN PARTICIPANT
last_message_seen
One of:
null
pinned_at

When the user pinned the conversation, or null.

string | null format: date-time
is_muted
boolean | null
muted_until

When the mute expires. null on an indefinite mute, and on an unmuted conversation. Unlike the other timestamps, the value inside pivot is a plain YYYY-MM-DD HH:MM:SS UTC string, not ISO-8601.

string | null
is_archived
boolean
has_mention

Whether an unread message mentions this user.

boolean
draft_message
string | null
favorited_at
string | null format: date-time
guid
string | null
created_at
string | null format: date-time
updated_at
string | null format: date-time
deleted_at

Set when the user has left or been removed.

string | null format: date-time
status

Presence information for a user.

object
id
integer format: int64
user_id
integer format: int64
last_seen_at

When the user was last active.

string | null format: date-time
created_at
string format: date-time
updated_at
string format: date-time
last_message
One of:
null
last_message_seen
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": 1,
      "visibility": "public",
      "pivot": {
        "role": "OWNER",
        "last_message_seen": {
          "type": "USER",
          "origin": "chat"
        }
      },
      "users": [
        {
          "messenger_color": "#2180f3",
          "pivot": {
            "role": "OWNER",
            "last_message_seen": {
              "type": "USER",
              "origin": "chat"
            }
          }
        }
      ],
      "last_message": {
        "type": "USER",
        "origin": "chat"
      },
      "last_message_seen": {
        "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"
}

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."
}