Skip to content
Optiwork API Docs

Search conversations, messages and people

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

One query, three result sets. chats holds conversations whose name matches, messages holds conversations that contain a matching message (with the matching messages nested inside each one), and users holds matching people.

Narrow the search with scope: chats returns only the conversation matches, messages only the message matches. Omit it to get everything.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
query
string

The text to look for.

scope
string
Allowed values: chats messages

Restrict the search to one kind of result.

Responses

Section titled “ Responses ”

200

Section titled “200”

The search results, one bucket per kind.

Media typeapplication/json
object
chats

Conversations whose name matches the query.

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
users

People whose name or e-mail matches the query.

Array<object>

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
messages

Conversations that contain at least one matching message. Each entry is a conversation with the matching messages nested under messages.

Array
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
messages
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
{
  "chats": [
    {
      "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"
      }
    }
  ],
  "messages": [
    {
      "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"
      },
      "messages": [
        {
          "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"
}

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