Change a conversation

PATCH

/v1/conversations/{id}

const url = 'https://app.mondochat.io/v1/conversations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"pinned":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://app.mondochat.io/v1/conversations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "pinned": true }'

Sets the caller’s own view of a conversation: alias, pinned, archived and note. A field left out is unchanged; alias and note are trimmed and null or empty clears them. The fields apply together or not at all, and only the caller is told (conversation.updated). alias needs workspace.aliases, pinned needs workspace.pins, archived needs workspace.queue, note needs workspace.notes. Needs a session token.

Errors: 403 policy_denied with reason aliases, pins, queue or notes when the key is off; 403 limit_reached with reason pins for an 11th pin; 404 not_found for a non-participant; 422 validation for an alias over 64 characters, or a note over 200 characters or with a line break.

Guide: Conversations.

Authorizations

session

Parameters

Path Parameters

required

string format: uuid

Request Body^required

application/json

ConversationPatch

The viewer’s own settings for a conversation; a field left out is unchanged.

object

alias

Any of:

string
null

string

<= 64 characters

archived

Any of:

boolean
null

boolean

note

Any of:

string
null

string

<= 200 characters /^[^\r\n]*$/

pinned

Any of:

boolean
null

boolean

Responses

200

Successful Response

application/json

Conversation

A conversation in full, from the viewer’s side.

object

alias

Any of:

string
null

string

archived

Archived

Whether the viewer archived it; needs workspace.queue.

boolean

blocked_by_me

required

Blocked By Me

Whether the viewer blocked the peer.

boolean

can

required

Can

What the viewer may do here.

object

block

required

Block

Block the peer.

boolean

buy

required

Buy

Buy from the peer.

boolean

call

required

Call

Start a call.

boolean

message

required

Message

Send messages.

boolean

offer

required

Offer

Send the peer an offer.

boolean

photos

required

Photos

Send photos.

boolean

reason

Any of:

string
null

string

Allowed value: inbound

voice

required

Voice

Send voice notes.

boolean

first_contact

Any of:

string
null

string format: date-time

required

The conversation id.

string format: uuid

invitable

Invitable

The viewer can send the peer a sign-up invite.

boolean

last_message

required

Any of:

LastMessage
null

LastMessage

The latest message of a conversation, as the viewer sees it.

object

auto

Auto

True for an away reply.

boolean

card_type

Any of:

string
null

string

Allowed values: call_invite call_ended call_missed purchase offer system signup_invite

created_at

required

Created At

When the message was sent.

string format: date-time

deleted

Deleted

True when deleted for everyone.

boolean

delivered_to_peer

Delivered To Peer

True only for the viewer’s own message once the peer received or read it.

boolean

duration_ms

Any of:

integer
null

integer

required

The message id.

string format: uuid

kind

required

Kind

text, photo, video, voice, system or card.

string

Allowed values: text photo video voice system card

once

Once

True for a view-once message.

boolean

preview

required

Preview

The text or caption up to 140 characters; empty for a message deleted for everyone; removed by moderation for a redacted one.

string

read_by_peer

Read By Peer

True only for the viewer’s own message once the peer has read it, and false while either participant has read_receipts off.

boolean

sender_id

required

Any of:

string
null

string format: uuid

note

Any of:

string
null

string

peer

required

Peer

The other user.

object

avatar

Any of:

string
null

string

external_id

required

External Id

The user’s id on your site.

string

required

The user’s id in mondochat.

string format: uuid

last_seen_at

Any of:

string
null

string format: date-time

name

required

Name

Display name.

string

online

Any of:

boolean
null

boolean

presence_pass

Any of:

string
null

string

role

required

Role

A role key from the app’s roles.

string

tier

Any of:

string
null

string

peer_reply_time

Any of:

string
null

string

Allowed values: minutes hour hours

photo_consent_mine

required

Any of:

string
null

string

Allowed values: yes no

photo_consent_theirs

required

Any of:

string
null

string

Allowed values: yes no

pinned

Pinned

Whether the viewer pinned it; false while workspace.pins is off.

boolean

purchases

Purchases

The viewer’s latest 3 paid sales here.

Array<object>

default:

Sale

A paid purchase in a conversation.

object

created_at

required

Created At

When the purchase was made.

string format: date-time

currency

required

Currency

ISO 4217 currency code.

string

kind

Any of:

string
null

string

price_minor

required

Price Minor

The price in minor units.

integer

title

required

Title

What was bought.

string

seq

required

Seq

The viewer’s inbox sequence for this row; keep the higher seq.

integer

spent

Any of:

Money
null

Money

An amount of money.

object

amount_minor

required

Amount Minor

The amount in minor units, such as cents.

integer

currency

required

Currency

ISO 4217 currency code.

string

unread_count

required

Unread Count

Messages from the peer the viewer has not read.

integer

waiting_since

Any of:

string
null

string format: date-time

Example

{
  "archived": false,
  "blocked_by_me": false,
  "can": {
    "block": true,
    "buy": false,
    "call": false,
    "message": true,
    "offer": false,
    "photos": true,
    "voice": true
  },
  "first_contact": "2026-11-01T09:00:00Z",
  "id": "0199d6a0-2000-7000-8000-000000000001",
  "invitable": false,
  "last_message": {
    "auto": false,
    "created_at": "2026-11-01T09:58:30Z",
    "deleted": false,
    "delivered_to_peer": false,
    "id": "0199d6a0-3000-7000-8000-000000000001",
    "kind": "text",
    "once": false,
    "preview": "Hi Alice",
    "read_by_peer": false,
    "sender_id": "0199d6a0-1000-7000-8000-000000000002"
  },
  "peer": {
    "avatar": "https://example.test/bob.jpg",
    "external_id": "bob",
    "id": "0199d6a0-1000-7000-8000-000000000002",
    "last_seen_at": "2026-11-01T09:58:00Z",
    "name": "Bob",
    "online": true,
    "presence_pass": "example-presence-pass",
    "role": "member"
  },
  "pinned": false,
  "purchases": [],
  "seq": 7,
  "unread_count": 1
}

4XX

Problem

application/problem+json

An RFC 9457 problem: the body of every error answer.

object

code

required

The stable error code to branch on, such as policy_denied.

string

detail

What went wrong this time, when there is more to say.

string | null

errors

For validation, one entry per invalid field.

Array<object>

One invalid field.

object

loc

The path to the field.

array

msg

What is wrong with it.

string

instance

The path of the request.

string

reason

For policy_denied and limit_reached, the rule or limit that refused the request; for forbidden, a short cause such as you_blocked; for banned, temporary when the ban expires.

string

status

required

The HTTP status code.

integer

title

required

A short summary of the problem.

string

type

required

A URL that names the problem, https://app.mondochat.io/problems/<code>.

string

Example

{
  "code": "policy_denied",
  "detail": null,
  "instance": "/v1/conversations/0199d6a0-2000-7000-8000-000000000001",
  "reason": "pins",
  "status": 403,
  "title": "Policy denied",
  "type": "https://app.mondochat.io/problems/policy_denied"
}

Change a conversation

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

Example

4XX

Example

Request Body^required