Conversations

Every inbound Messenger DM, Instagram DM and comment, on Facebook Page posts and on Instagram media, becomes a conversation in the workspace that owns the account. The model is the same for both networks and both kinds, so one inbox screen handles everything.

Endpoints

Method	Path	Body / query	Returns
GET	/v1/conversations	query: workspace, account, kind, status, unread, page, limit	list
GET	/v1/conversations/:id		conversation plus its last 50 messages
GET	/v1/conversations/:id/messages	?page=&limit=	list of messages
POST	/v1/conversations/:id/messages	{ text, quick_replies? }	201 message, sent to the network
POST	/v1/conversations/:id/private-reply	{ text }	201 message, one private DM to a commenter
PATCH	/v1/conversations/:id	{ status?, unread? }	conversation

Sending is covered in Replying. Receiving in real time is covered in Webhooks for the inbox.

The conversation object

{
  "id": "cnv2b4d6f8h1j3l",
  "workspace": "ws7k2m9p4q1r8t3",
  "account": "acig4h2k5m7p9r1",
  "network": "instagram",
  "kind": "dm",
  "platform_thread_id": "17847000000000001",
  "contact": {
    "id": "5834920000000001",
    "name": "Dana de Vries",
    "handle": "dana.dv",
    "avatar_url": "https://scontent.example/dana.jpg"
  },
  "post_platform_id": null,
  "comment_id": null,
  "last_message_at": "2026-08-25T10:02:17Z",
  "last_message_preview": "Hi, do you have a slot on Friday afternoon?",
  "unread": 1,
  "status": "open",
  "created": "2026-08-25T10:02:17Z"
}

Field	Notes
account	The connected account the conversation belongs to. Its network is copied onto the conversation
kind	dm for Messenger and Instagram direct messages, comment for a comment thread
platform_thread_id	Meta’s id for the DM thread, or for the comment thread
contact	The person on the other side. handle is the Instagram username when known, name is what Meta exposes. Both can be null if Meta withholds them
post_platform_id	comment only: the Page post or Instagram media the comment is on
comment_id	comment only: the top-level comment that started the thread
last_message_at, last_message_preview	For list views. The preview is the text of the newest message, truncated
unread	Number of inbound messages you have not marked read
status	open or closed

Kinds

DM conversations are one thread per contact per account. A returning customer continues the same conversation. Messages can be text, images, video, audio, files, quick-reply postbacks and reactions.

Comment conversations are one thread per top-level comment. Replies under the same comment, from the commenter or from you, land in the same conversation. A second comment on the same post by the same person is a new conversation.

The message object

{
  "id": "msg7q9s1u3w5y2a",
  "conversation": "cnv2b4d6f8h1j3l",
  "direction": "in",
  "kind": "text",
  "text": "Hi, do you have a slot on Friday afternoon?",
  "media_url": null,
  "platform_message_id": "m_AbCdEf0123456789",
  "sent_by": "contact",
  "status": "sent",
  "created": "2026-08-25T10:02:17Z"
}

Field	Values
direction	in from the contact, out from you
kind	text, image, video, audio, file, comment, reply, postback, reaction
media_url	For image, video, audio and file: a URL to the attachment, hosted by Meta
sent_by	contact for inbound. For outbound, the surface that sent it: api, embed (the widget), dashboard, mcp, or auto
status	sent once the message is stored (inbound) or delivered to the network (outbound). Outbound can also be pending or failed

In a comment conversation the inbound comment has kind: "comment" and your answers have kind: "reply". A postback is a tapped quick reply; its text is the payload you gave. A reaction carries the emoji in text.

Listing

curl "https://social.missless.tel/v1/conversations?workspace=ws7k2m9p4q1r8t3&status=open&unread=true" \
  -H "Authorization: Bearer $MISSLESS_API_KEY"

Query	Notes
workspace	One workspace. With a partner key, omit it to list across the partner
account	One connected account
kind	dm or comment
status	open or closed
unread	true returns only conversations with unread above zero
page, limit	Newest activity first, by last_message_at

GET /v1/conversations/:id returns the conversation with a messages array holding the last 50 messages, oldest first. Use GET /v1/conversations/:id/messages with page for older history.

Unread and status

Mark a conversation read when the customer’s staff has seen it:

curl -X PATCH https://social.missless.tel/v1/conversations/cnv2b4d6f8h1j3l \
  -H "Authorization: Bearer $MISSLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "unread": 0 }'

unread accepts only 0. Each new inbound message adds one. Sending a reply does not reset it; mark read explicitly so an inbox built on the API behaves the same as the widget.

status is for your workflow. Set closed when a thread is handled. A new inbound message on a closed conversation reopens it and increments unread, so nothing gets lost.