Skip to content
Optiwork API Docs

Send a message

POST
/chats/{chat}/messages
curl --request POST \
  --url https://chat.work.optidata.cloud/api/chats/36/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "content": "The report is ready for review.", "idempotencyHash": "8baf581a-63b4-49b9-bf0c-740d13db6ffa" }'

Posts a message into the conversation. A message can carry any combination of text, file attachments, user mentions, a reply to an earlier message, and a poll.

Attachments make the request multipart/form-data: send each file as files[0][blob], files[0][name], files[0][source] and so on. source is required per file and says where the file came from — SOURCE_USER_FILE_SYSTEM for an upload, SOURCE_OPTIWORK_DRIVE for a file already stored in Drive.

Sending is idempotent when you supply idempotencyHash: a retry with the same value returns the message created by the first attempt instead of posting a duplicate. Generate one UUID per message you intend to send and reuse it across retries — this is the safest way to send from an unreliable network.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

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

Numeric id of the conversation.

Request Bodyrequired

Section titled “Request Bodyrequired”

The payload of a new message. Every field is optional on its own, but a message with neither content nor files carries nothing.

object
content

The message text.

string | null
idempotencyHash

Client-generated value that makes the send idempotent. A retry with the same value returns the message the first attempt created instead of posting a duplicate.

string | null
<= 100 characters
hash

Client-chosen identifier for the message. Generated by the server when omitted.

string | null
<= 100 characters
replyMessage

Id of the message this one replies to.

integer | null format: int64
origin

Free-text label naming where the message came from. Defaults to chat.

string | null
hasUserMentions

Whether the text mentions anyone.

boolean | null
mentionedUserUuids

UUIDs of the mentioned users. Required when hasUserMentions is true.

Array<string>
shouldSendFileAsGroupAdmin
boolean | null
data
object | null
files

Attachments. Requires a multipart/form-data request when the bytes travel with the message.

Array<object>
object
blob

The file bytes.

string format: binary
name
string
size
integer
type

MIME type of the file.

string
extension
string
audio

true for a voice message.

boolean
duration

Playback length in seconds.

string
source
required

Where the file comes from — an upload, or a file already stored in Drive. Required on every file.

string
Allowed values: SOURCE_USER_FILE_SYSTEM SOURCE_OPTIWORK_DRIVE
meta
object
key
additional properties
any
poll

A poll to attach to the message.

object
question
required
string
<= 255 characters
is_multiple_answers
boolean
options
required
Array<string>
>= 2 items <= 12 items
Examples

Plain text

{
  "content": "The report is ready for review.",
  "idempotencyHash": "8baf581a-63b4-49b9-bf0c-740d13db6ffa"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The created message. On a retry carrying a known idempotencyHash, the message created by the first attempt is returned unchanged.

The message carries the send-time serialization (CreatedMessage): the whole conversation is embedded under chat, user is the full user record, and the read-side enrichment fields are absent.

Media typeapplication/json
object
message
required

The message shape returned by the send endpoints (POST /chats/{chat}/messages and POST /users/{userUuid}/chats/messages). It is a different serialization from the Message returned by the read endpoints: it embeds the whole conversation under chat, serializes user as the full user record, and omits the read-side enrichment fields (reactions, meta, is_seen, is_forwarded, is_important, is_favorite, message_link_id, poll).

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.

string
idempotency_hash

The client-supplied value that made the send idempotent.

string | null
content

The message text.

string | null
data
object | null
origin
string
has_user_mentions
boolean
views
integer
order_in_chat
integer
user

The author, serialized as the full user record.

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
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
object | null
reply_message
One of:
null
chat

The conversation the message belongs to, embedded — the conversation’s own columns plus its participants under users. This embed is unique to the send responses.

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
created_at
string format: date-time
updated_at
string format: date-time
Example
{
  "message": {
    "type": "USER",
    "origin": "chat",
    "user": {
      "messenger_color": "#2180f3"
    },
    "chat": {
      "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"
}

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