Open a conversation
const url = 'https://app.mondochat.io/v1/conversations';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"with":"bob"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.mondochat.io/v1/conversations \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "with": "bob" }'Returns the conversation with with or creates it: 201 for a new one, 200 for an existing one. A new one needs the start_conversation policy toward the peer’s role, the caller’s new_conversations_per_day limit, and the vouch when the policy has require_vouch; creating emits the conversation.created webhook. With draft: true and no conversation yet, it runs the same checks and answers 202 with the Conversation a create would return, stores nothing, and that id is unknown to every other route. Needs a session token.
Errors: 403 banned; 403 policy_denied (reason require_vouch); 403 limit_reached; 404 not_found for a peer never created through the server API or a session; 422 validation for the caller’s own external id.
Guide: Conversations.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Responses
Section titled “Responses”Already exists
A conversation in full, from the viewer’s side.
object
Whether the viewer archived it; needs workspace.queue.
Whether the viewer blocked the peer.
What the viewer may do here.
object
Block the peer.
Buy from the peer.
Start a call.
Send messages.
Send the peer an offer.
Send photos.
Send voice notes.
The conversation id.
The viewer can send the peer a sign-up invite.
The latest message of a conversation, as the viewer sees it.
object
True for an away reply.
When the message was sent.
True when deleted for everyone.
True only for the viewer’s own message once the peer received or read it.
The message id.
text, photo, video, voice, system or card.
True for a view-once message.
The text or caption up to 140 characters; empty for a message deleted for everyone; removed by moderation for a redacted one.
True only for the viewer’s own message once the peer has read it, and false while either participant has read_receipts off.
The other user.
object
The user’s id on your site.
The user’s id in mondochat.
Display name.
A role key from the app’s roles.
Whether the viewer pinned it; false while workspace.pins is off.
The viewer’s latest 3 paid sales here.
A paid purchase in a conversation.
The viewer’s inbox sequence for this row; keep the higher seq.
Messages from the peer the viewer has not read.
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}Successful Response
A conversation in full, from the viewer’s side.
object
Whether the viewer archived it; needs workspace.queue.
Whether the viewer blocked the peer.
What the viewer may do here.
object
Block the peer.
Buy from the peer.
Start a call.
Send messages.
Send the peer an offer.
Send photos.
Send voice notes.
The conversation id.
The viewer can send the peer a sign-up invite.
The latest message of a conversation, as the viewer sees it.
object
True for an away reply.
When the message was sent.
True when deleted for everyone.
True only for the viewer’s own message once the peer received or read it.
The message id.
text, photo, video, voice, system or card.
True for a view-once message.
The text or caption up to 140 characters; empty for a message deleted for everyone; removed by moderation for a redacted one.
True only for the viewer’s own message once the peer has read it, and false while either participant has read_receipts off.
The other user.
object
The user’s id on your site.
The user’s id in mondochat.
Display name.
A role key from the app’s roles.
Whether the viewer pinned it; false while workspace.pins is off.
The viewer’s latest 3 paid sales here.
A paid purchase in a conversation.
The viewer’s inbox sequence for this row; keep the higher seq.
Messages from the peer the viewer has not read.
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}Draft: checked, not stored
A conversation in full, from the viewer’s side.
object
Whether the viewer archived it; needs workspace.queue.
Whether the viewer blocked the peer.
What the viewer may do here.
object
Block the peer.
Buy from the peer.
Start a call.
Send messages.
Send the peer an offer.
Send photos.
Send voice notes.
The conversation id.
The viewer can send the peer a sign-up invite.
The latest message of a conversation, as the viewer sees it.
object
True for an away reply.
When the message was sent.
True when deleted for everyone.
True only for the viewer’s own message once the peer received or read it.
The message id.
text, photo, video, voice, system or card.
True for a view-once message.
The text or caption up to 140 characters; empty for a message deleted for everyone; removed by moderation for a redacted one.
True only for the viewer’s own message once the peer has read it, and false while either participant has read_receipts off.
The other user.
object
The user’s id on your site.
The user’s id in mondochat.
Display name.
A role key from the app’s roles.
Whether the viewer pinned it; false while workspace.pins is off.
The viewer’s latest 3 paid sales here.
A paid purchase in a conversation.
The viewer’s inbox sequence for this row; keep the higher seq.
Messages from the peer the viewer has not read.
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}Problem
An RFC 9457 problem: the body of every error answer.
object
The stable error code to branch on, such as policy_denied.
What went wrong this time, when there is more to say.
For validation, one entry per invalid field.
One invalid field.
object
The path to the field.
What is wrong with it.
The path of the request.
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.
The HTTP status code.
A short summary of the problem.
A URL that names the problem, https://app.mondochat.io/problems/<code>.
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"}