Overview
What a conversation is, how to send messages and which limits apply.
A conversation is the private channel between buyer and seller, after the sale. It is born with the order: there is no POST /v1/conversations. To start contact, send a message in the order's conversation.
How customer service works end to end: Serve buyers. Open claims (disputes) are a separate resource.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/conversations | List conversations |
GET | /v1/conversations/{conversationId} | Get conversation |
GET | /v1/conversations/{conversationId}/messages | List messages |
POST | /v1/conversations/{conversationId}/messages | Send message |
All require Authorization: Bearer mk_your_api_key. See Authentication.
Conversation
channel:post_saleorsupport_ticket.status:open,blockedorclosed. When it isblocked,blockedReasonsays why.orderId: the order of the conversation.
When you can send: sendability
Each conversation has sendability, computed before you send:
canSend:trueorfalse.issues: what blocks it, each with acode(conversation_blocked,text_too_long,attachments_unsupported,too_many_attachments,contact_reason_required,contact_reason_exhausted).maxTextLengthandmaxAttachments: the limits.contactReasons: the remaining quota (remaining) of each contact reason.
On POST …/messages, the same check runs again. If something does not fit, the response is 409 message_not_sendable with the issues, and no job is created. Without errors, it is 202 with a job, and the message goes from sending to sent or failed.
Messages
authorRole is buyer, seller or marketplace. Moderation (approved, pending, rejected, not_moderated) comes in moderation. Attachments are private files: read them with Get content.
Webhook
message.received arrives when the buyer or the marketplace writes. It carries ids only (conversationId, messageId, orderId…), never the text or the attachment. Read the message with List messages. See Receiving webhooks.