Skip to content
Optiwork API Docs

Send a direct message to a user

POST
/users/{userUuid}/chats/messages
curl --request POST \
  --url https://chat.work.optidata.cloud/api/users/3f1c9a52-4d7e-4b31-9c02-77a1b6e5d840/chats/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "content": "Can you review the draft today?" }'

The shortest way to reach a person: send text to a user and let the server find — or create — the private conversation between the two of you. No conversation id needed.

Use POST /chats/{chat}/messages when you need files, mentions, replies or polls; this operation only carries text.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
userUuid
required
string format: uuid

UUID of the user. Read your own from GET /me.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
content
required

The message text.

string

Responses

Section titled “ Responses ”

200

Section titled “200”

The created message, in the send-time serialization (CreatedMessage): the 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"
}

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”

Validation failed, or the target user is the caller — you cannot send a direct message to yourself.

Media typeapplication/json

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

object
message
required

Human-readable description of the failure.

string
Examples
Exampleself
{
  "message": "You cannot send a message to yourself."
}

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