Mirakl Messages API
The Messages API from Mirakl — 9 operation(s) for messages.
OpenAPI Specification
openapi: 3.1.0
info:
description: '{% partial file="/partial-content/product/connect-channel-platform/rest/connect/openapi-description.md" /%}'
title: Mirakl Connect Channel Platform APIs Carriers Messages API
version: ''
servers:
- description: Connect Channel Platform API
url: https://miraklconnect.com/api/channel-platform
tags:
- name: Messages
paths:
/api/messages:
get:
deprecated: true
description: '<div class="extension-title">Deprecated endpoint</div>
This API is going to be removed in a future update, please use M10 and M11 instead
<div class="extension-title">Description</div>
Returns messages received or sent to the operator. By default, returns only messages that are received by the operator.
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Synchronous only - at each message list display</div>
<div class="max-call-frequency">Maximum usage: Synchronous only - at each message list display</div>
<div class="extension-title">Pagination</div>
<p>This resource supports offset pagination (<a href="#section/Offset-pagination-and-sort">see documentation</a>)</p>
<div class="extension-title">Sort fields</div>
<code>sort</code> field can have the following values:<ul><li><b>dateCreated</b> (Default) - Sort by creation date (desc by default)</li></ul>
</div>'
operationId: M01
parameters:
- description: Returns messages concerned by this <code>customer_id</code>
explode: true
in: query
name: customer_id
required: false
schema:
type: string
style: form
- description: Returns messages concerned by this <code>shop_id</code>
explode: true
in: query
name: shop_id
required: false
schema:
type: integer
format: int64
style: form
- description: '<ul><li> If <code>TRUE</code>: returns only messages received by operator.</li><li> If <code>FALSE</code>: returns only messages sent to the operator.</li><li> If <code>ALL</code>: returns all messages, even direct messages between customer and shop.</li></ul>'
explode: true
in: query
name: received
required: false
schema:
type: string
default: 'TRUE'
enum:
- 'TRUE'
- 'FALSE'
- ALL
style: form
- deprecated: true
description: Ignored, will be removed in a future version
explode: true
in: query
name: read
required: false
schema:
type: string
deprecated: true
enum:
- 'TRUE'
- 'FALSE'
- ALL
style: form
- description: Order identifier
explode: true
in: query
name: order_id
required: false
schema:
type: string
style: form
- description: Offer identifier
explode: true
in: query
name: offer_id
required: false
schema:
type: integer
format: int64
style: form
- description: Start creation date for filtering
explode: true
in: query
name: start_date
required: false
schema:
type: string
format: date-time
style: form
- description: End creation date for filtering
explode: true
in: query
name: end_date
required: false
schema:
type: string
format: date-time
style: form
- deprecated: true
description: Ignored, will be removed in a future version
explode: true
in: query
name: archived
required: false
schema:
type: string
deprecated: true
enum:
- 'TRUE'
- 'FALSE'
- ALL
style: form
- deprecated: true
description: '<ul><li> If <code>TRUE</code>: returns only the visible messages.</li><li> If <code>FALSE</code>: returns only the not visible messages.</li></ul>'
explode: true
in: query
name: visible
required: false
schema:
type: string
default: 'TRUE'
deprecated: true
enum:
- 'TRUE'
- 'FALSE'
- ALL
style: form
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
messages:
- archived: false
body: 'Hi,
I ordered a CD from you earlier this week, and I wanted to know if you used USPS or UPS to deliver, since UPS drivers have trouble finding my house (it is at the bottom of a cul-de-sac). The order number is N°0823623574.
Thanks for your help,
Yvan'
commercial_id: MIR-KQ1CI2U0
date_created: '2019-03-25T14:25:24Z'
from_id: 356-30-5081
from_name: Juan Cao
from_type: CUSTOMER
id: 2006
order_id: MIR-KQ1CI2U0-B
read: false
subject: Question about delivery
to_operator: true
to_operator_archived: false
to_shop_archived: false
to_shop_id: 136
to_shop_name: Rogersound Labs
total_count: 1
application/json-auto:
summary: Complete example with value types (application/json)
value:
messages:
- archived: true
body: string
commercial_id: string
date_created: '2023-03-28T09:34:42Z'
documents:
- date_uploaded: '2023-03-28T09:34:42Z'
file_name: string
file_size: 0
id: 0
type: string
from_id: string
from_name: string
from_type: OPERATOR
id: 0
offer_id: 0
order_id: string
read: true
subject: string
to_customer_archived: true
to_customer_id: string
to_customer_name: string
to_operator: true
to_operator_archived: true
to_shop_archived: true
to_shop_id: 0
to_shop_name: string
visible: true
total_count: 0
schema:
type: object
$ref: '#/components/schemas/M01_Response_200'
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: M01 - List messages linked to orders and offers
tags:
- Messages
x-badges:
- color: noIntegrationBadge
name: ⚠️ No Integration Allowed ⚠️
position: after
/api/inbox/threads/{thread_id}:
get:
description: '<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Synchronous only - At each page that includes a message thread display</div>
<div class="max-call-frequency">Maximum usage: Synchronous only - At each page that includes a message thread display</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/integrating_mirakl/integrate_messages.htm">More context (Products Marketplace)</a></li><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/service_features/integrating_services/sending_service_messages.htm">More context (Services Marketplace)</a></li></ul></div>'
operationId: M10
parameters:
- description: The identifier of the thread to retrieve.
explode: false
in: path
name: thread_id
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
authorized_participants:
- display_name: Shop display name
id: Shop id
type: SHOP
- display_name: Customer display name
id: Customer id
type: CUSTOMER
current_participants:
- display_name: Shop display name
id: Shop id
type: SHOP
- display_name: Customer display name
id: Customer id
type: CUSTOMER
customer_organization:
display_name: Customer organization
id: customer-org-id
date_created: '2018-10-02T08:36:36.479Z'
date_updated: '2018-10-03T09:40:17.241Z'
entities:
- id: Entity id
label: Entity label
type: Entity type
id: 702c3e56-dcca-41e2-b6bd-72ba3fa809be
messages:
- body: Hello, I have recently order a service and I have a few questions ...
date_created: '2018-10-02T08:36:36.479Z'
from:
display_name: Customer display name
type: CUSTOMER_USER
id: df4a3163-a44b-4c5f-8380-faebfa43ca68
to:
- display_name: Shop display name
id: Shop id
type: SHOP
- attachments:
- id: fce1742e-8160-45ed-b88a-100023d9d97b
name: Brochure du service
size: 200
- id: 983fd83f-0b39-4bdf-9932-bd774ab66ce4
name: Tarif
size: 10
body: Dear customer, ...
date_created: '2018-10-03T09:40:17.241Z'
from:
display_name: Shop user display name
organization_details:
display_name: Shop display name
id: Shop id
type: SHOP
type: SHOP_USER
id: d752f26f-03eb-499c-8f4d-828fa9640055
to:
- display_name: Customer display name
id: Customer id
type: CUSTOMER
metadata:
last_message_date: '2018-10-03T09:40:17.241Z'
last_sender:
display_name: Shop user display name
organization_details:
display_name: Shop display name
id: Shop id
type: SHOP
type: SHOP_USER
shop_reply_needed_since: null
total_count: 2
no_store_reply_needed: []
topic:
type: FREE_TEXT
value: Questions about my order
application/json-auto:
summary: Complete example with value types (application/json)
value:
authorized_participants:
- display_name: string
id: string
type: OPERATOR
current_participants:
- display_name: string
id: string
type: OPERATOR
customer_organization:
display_name: string
id: string
date_created: '2023-03-28T09:34:42Z'
date_updated: '2023-03-28T09:34:42Z'
entities:
- id: string
label: string
type: string
id: string
messages:
- attachments:
- id: string
name: string
size: 0
body: string
date_created: '2023-03-28T09:34:42Z'
from:
display_name: string
organization_details:
display_name: string
id: string
type: OPERATOR
type: OPERATOR_USER
id: string
to:
- display_name: string
id: string
type: OPERATOR
metadata:
last_message_date: '2023-03-28T09:34:42Z'
last_sender:
display_name: string
organization_details:
display_name: string
id: string
type: OPERATOR
type: OPERATOR_USER
shop_reply_needed_since: '2023-03-28T09:34:42Z'
total_count: 0
no_store_reply_needed:
- date: '2023-03-28T09:34:42Z'
user_type: OPERATOR
topic:
type: FREE_TEXT
value: string
schema:
type: object
$ref: '#/components/schemas/M10_Response_200'
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: M10 - Retrieve a thread
tags:
- Messages
/api/inbox/threads:
get:
description: '<div class="extension-title">Description</div>
You may want to retrieve the threads linked to a specific entity, using both <code>entity_type</code> and <code>entity_id</code>.
<br>For example, to retrieve threads for an order, use <code>entity_type=MMP_ORDER&entity_id=my-order-1</code>.
<br>
Available values for <code>entity_type</code> are:
<ul>
<li><code>MMP_ORDER</code>: for threads on product orders</li>
<li><code>MMP_OFFER</code>: for threads on offers</li>
<li><code>MPS_ORDER</code>: for threads on service orders</li>
<li><code>MPS_SERVICE</code>: for threads on services</li>
<li><code>SELLER_OPERATOR</code>: for threads between sellers and operator</li>
</ul>
This resource uses seek pagination. The default value for parameter <code>limit</code> is 50.
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Synchronous only - At each page that includes an inbox display</div>
<div class="max-call-frequency">Maximum usage: Synchronous only - At each page that includes an inbox display</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/integrating_mirakl/integrate_messages.htm">More context (Products Marketplace)</a></li><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/service_features/integrating_services/sending_service_messages.htm">More context (Services Marketplace)</a></li></ul><div class="extension-title">Pagination</div>
<p>This resource supports seek pagination (<a href="#section/Seek-pagination-and-sort">see documentation</a>)</p>
</div>'
operationId: M11
parameters:
- description: 'Entity type to include in result (default: include all).<br/> Available values: MMP_ORDER, MMP_OFFER, MPS_ORDER, MPS_SERVICE, SELLER_OPERATOR'
explode: true
in: query
name: entity_type
required: false
schema:
type: string
style: form
- description: 'Comma separated list of Entity id to include in result (default: include all).<br/> The entity_type must be specified to use this filter, otherwise an error 400 will be returned.<br/> Example of an entity_id query: entity_id=order1-A,order20-A,order13-A&entity_type=MMP_ORDER'
explode: true
in: query
name: entity_id
required: false
schema:
type: array
items:
type: string
style: form
- description: Retrieve threads modified at or after this date.
explode: true
in: query
name: updated_since
required: false
schema:
type: string
format: date-time
style: form
- description: True to include message details. Limited to the last 100 messages received on each thread.
explode: true
in: query
name: with_messages
required: false
schema:
type: boolean
default: false
style: form
- description: 'List of the channel codes to filter with, using a comma (,) as a separator.
<br/> If specified, only order messages linked to the given channels will be returned (Whatever the value of <code>entity_type</code>).
<br/> Otherwise, messages will be returned regardless of their channels.
'
explode: true
in: query
name: channel_codes
required: false
schema:
type: array
items:
type: string
uniqueItems: true
style: form
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
data:
- authorized_participants:
- display_name: Shop display name
id: Shop id
type: SHOP
- display_name: Customer display name
id: Customer id
type: CUSTOMER
current_participants:
- display_name: Shop display name
id: Shop id
type: SHOP
- display_name: Customer display name
id: Customer id
type: CUSTOMER
customer_organization:
display_name: Customer organization
id: customer-org-id
date_created: '2016-09-03T13:37:00Z'
date_updated: '2018-09-03T13:37:00Z'
entities:
- id: Entity id
label: Entity label
type: Entity type
id: 702c3e56-dcca-41e2-b6bd-72ba3fa809be
metadata:
last_message_date: '2018-09-03T13:37:00Z'
last_sender:
display_name: Shop user display name
organization_details:
display_name: Shop display name
id: Shop id
type: SHOP
type: SHOP_USER
shop_reply_needed_since: null
total_count: 2
no_store_reply_needed: []
topic:
type: FREE_TEXT
value: Topic value
next_page_token: bGltaXQ9NTAmYWZ0ZXI9MjA3NjYwNTAtZDc5Yy00YzUyLWEwODctZWI5YjY1MjFkNzA5JnNvcnQ9ZGF0ZSxERVND.jFoPX_GjfbaRV88hhNxWWEzeRSqPt1WNExsrcBTkuSY=
application/json-auto:
summary: Complete example with value types (application/json)
value:
data:
- authorized_participants:
- display_name: string
id: string
type: OPERATOR
current_participants:
- display_name: string
id: string
type: OPERATOR
customer_organization:
display_name: string
id: string
date_created: '2023-03-28T09:34:42Z'
date_updated: '2023-03-28T09:34:42Z'
entities:
- id: string
label: string
type: string
id: string
messages:
- attachments:
- id: string
name: string
size: 0
body: string
date_created: '2023-03-28T09:34:42Z'
from:
display_name: string
organization_details:
display_name: string
id: string
type: OPERATOR
type: OPERATOR_USER
id: string
to:
- display_name: string
id: string
type: OPERATOR
metadata:
last_message_date: '2023-03-28T09:34:42Z'
last_sender:
display_name: string
organization_details:
display_name: string
id: string
type: OPERATOR
type: OPERATOR_USER
shop_reply_needed_since: '2023-03-28T09:34:42Z'
total_count: 0
no_store_reply_needed:
- date: '2023-03-28T09:34:42Z'
user_type: OPERATOR
topic:
type: FREE_TEXT
value: string
next_page_token: string
previous_page_token: string
schema:
type: object
$ref: '#/components/schemas/M11_Response_200'
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: M11 - List all threads
tags:
- Messages
post:
description: '<div class="extension-title">Description</div>
Create a thread with a seller and send a first message
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Synchronous only - At each thread</div>
<div class="max-call-frequency">Maximum usage: Synchronous only - At each thread answer</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/integrating_mirakl/integrate_messages.htm">More context (Products Marketplace)</a></li><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/service_features/integrating_services/sending_service_messages.htm">More context (Services Marketplace)</a></li></ul></div>'
operationId: M14
parameters: []
requestBody:
content:
multipart/form-data:
examples:
multipart/form-data-auto:
summary: Complete example with value types (multipart/form-data)
value:
files:
- string
thread_input:
body: string
entity:
id: string
type: string
topic:
type: FREE_TEXT
value: string
schema:
type: object
properties:
files:
type: array
description: List of attachments for the message<br/>Maximum 1000 across all threads of the same entity.<br/>For example, for a given seller, you can not have more than 1000 attachments across all its threads.
items:
type: string
format: binary
thread_input:
$ref: '#/components/schemas/M14_Request_MultipartFormData_ThreadInput'
description: Message and thread data
required:
- thread_input
responses:
'201':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
message_id: 873f1cb5-a7a2-4e07-8e0e-12eb64e93ece
thread_id: 702c3e56-dcca-41e2-b6bd-72ba3fa809be
application/json-auto:
summary: Complete example with value types (application/json)
value:
message_id: string
thread_id: string
schema:
type: object
$ref: '#/components/schemas/M14_Response_201'
description: Created
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: M14 - Create a thread with a seller
tags:
- Messages
x-codeSamples:
- lang: cURL
source: "curl -i -X POST \\\n https://your-instance.mirakl.net/api/inbox/threads \\\n -H 'Content-Type: multipart/form-data' \\\n -F 'files=@path/to/file' \\\n -F 'thread_input=\"{\\\"body\\\":\\\"string\\\",\\\"entity\\\":{\\\"id\\\":\\\"string\\\",\\\"type\\\":\\\"string\\\"},\\\"topic\\\":{\\\"type\\\":\\\"FREE_TEXT\\\",\\\"value\\\":\\\"string\\\"}}\";type=application/json'\n"
/api/inbox/threads/{thread_id}/message:
post:
description: '<div class="extension-title">Description</div>
Maximum of 1000 messages on a thread
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Synchronous only - At each thread answer</div>
<div class="max-call-frequency">Maximum usage: Synchronous only - At each thread answer</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/integrating_mirakl/integrate_messages.htm">More context (Products Marketplace)</a></li><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/service_features/integrating_services/sending_service_messages.htm">More context (Services Marketplace)</a></li></ul></div>'
operationId: M12
parameters:
- description: The ID of the thread to reply to.
explode: false
in: path
name: thread_id
required: true
schema:
type: string
style: simple
requestBody:
content:
multipart/form-data:
examples:
multipart/form-data-auto:
summary: Complete example with value types (multipart/form-data)
value:
files:
- string
message_input:
body: string
to:
- id: string
type: OPERATOR
topic:
type: FREE_TEXT
value: string
schema:
type: object
properties:
files:
type: array
description: List of attachments for the message<br/>Maximum 50 across all threads of the same entity.<br/>For example, for a given order, you can not have more than 50 attachments across all its threads.
items:
type: string
format: binary
message_input:
$ref: '#/components/schemas/M12_Request_MultipartFormData_MessageInput'
description: The message data
required:
- message_input
responses:
'201':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
message_id: 873f1cb5-a7a2-4e07-8e0e-12eb64e93ece
thread_id: 702c3e56-dcca-41e2-b6bd-72ba3fa809be
application/json-auto:
summary: Complete example with value types (application/json)
value:
message_id: string
thread_id: string
schema:
type: object
$ref: '#/components/schemas/M12_Response_201'
description: Created
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: M12 - Reply to a thread
tags:
- Messages
x-codeSamples:
- lang: cURL
source: "curl -i -X POST \\\n https://your-instance.mirakl.net/api/inbox/threads/{thread_id}/message \\\n -H 'Content-Type: multipart/form-data' \\\n -F 'files=@path/to/file' \\\n -F 'message_input=\"{\\\"body\\\":\\\"string\\\",\\\"to\\\":[{\\\"id\\\":\\\"string\\\",\\\"type\\\":\\\"OPERATOR\\\"}],\\\"topic\\\":{\\\"type\\\":\\\"FREE_TEXT\\\",\\\"value\\\":\\\"string\\\"}}\";type=application/json'\n"
/api/inbox/threads/{attachment_id}/download:
get:
description: '<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Synchronous only - At each message attachment download</div>
<div class="max-call-frequency">Maximum usage: Synchronous only - At each message attachment download</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/integrating_mirakl/integrate_messages.htm">More context (Products Marketplace)</a></li><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/service_features/integrating_services/sending_service_messages.htm">More context (Services Marketplace)</a></li></ul></div>'
operationId: M13
parameters:
- description: The identifier of the attachment to retrieve.
explode: false
in: path
name: attachment_id
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/octet-stream:
examples:
application/octet-stream-auto:
summary: Complete example with value types (application/octet-stream)
value: string
schema:
type: string
format: binary
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: M13 - Download an attachment
tags:
- Messages
/api/orders/{order_id}/messages:
post:
deprecated: true
description: '<div class="extension-title">Deprecated endpoint</div>
This API will be removed in a future version. Use OR43 and M12 instead.
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mirakl/refs/heads/main/openapi/mirakl-messages-api-openapi.yml