API reference
Support messages
The messages in a support thread: answers, internal notes and attached files.
Base URL https://partners.monotree.com/api/v1
· every call needs a token
Endpoints
get/support/threads/{thread}/messages
List messages
post
/support/threads/{thread}/messages
Answer a support thread
post
/support/threads/{thread}/messages/{message}/retry
Send a failed answer again
post
/support/threads/{thread}/notes
Add a note
get
/support/attachments/{attachment}
Download an attachment
List messages
/support/threads/{thread}/messages
support:read The messages of a thread, always oldest first, a page at a time. Without after or before you get the latest ones. before with the id of the first message you have walks back through a long thread; after with the id of the last one gives what is new. has_more says whether there are more on that side. This list has no cursor: next_cursor is always null.
Parameters
thread
required
string · path
after
string · query
before.
before
string · query
after.
limit
integer · query
default 50 · up to 100
Response · 200 A page of messages, oldest first.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such support thread, or no such message in it (after, before).
validation_error: after and before were sent together, or limit is out of range.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/messages \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/messages', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/messages', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/messages",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"data": [
{
"id": "msg_01m7d1ajqgwbvenrpw7gz6xn25",
"object": "support_message",
"direction": "in",
"kind": "message",
"author": {
"type": "customer",
"name": "Sophie Garnier"
},
"body": "Bonjour, mon invitation ne marche pas.",
"edited": false,
"deleted": false,
"attachments": [],
"delivery": null,
"send_state": null,
"sent_at": "2026-11-14T12:43:10Z",
"delivered_at": null
},
{
"id": "msg_01m7d1awpxds8kqrrt6733j0d2",
"object": "support_message",
"direction": "out",
"kind": "message",
"author": {
"type": "api",
"name": "API · Back office, production"
},
"body": "Bonjour Sophie, voici le guide.",
"edited": false,
"deleted": false,
"attachments": [
{
"id": "att_2",
"name": "guide.pdf",
"mime": "application/pdf",
"size": 48213,
"url": "https://partners.monotree.com/api/v1/support/attachments/att_2"
}
],
"delivery": {
"state": "delivered",
"error": null,
"delivered_at": "2026-11-14T12:43:21Z"
},
"send_state": "sent",
"sent_at": "2026-11-14T12:43:21Z",
"delivered_at": "2026-11-14T12:43:21Z"
}
],
"has_more": false,
"next_cursor": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Send a failed answer again
/support/threads/{thread}/messages/{message}/retry
support:write An answer whose delivery.state is failed is handed to Monotree again. It is the same message, so nothing arrives twice. No body is needed.
Parameters
thread
required
string · path
message
required
string · path
Accepts an optional Idempotency-Key header to make a retry safe.
Response · 200 The answer, on its way again.
id
string
object
string
direction
string
in: theirs. out: from your desk.
one of in, out
kind
string
auto: the automatic reply sent while the desk was offline. It does not count as an answer.
one of message, auto
author
object
type
string
customer: someone at the customer. seller: one of your people, in the portal. api: a token of yours. assistant: the assistant sending its own draft (auto on sends). system: the desk itself (the automatic reply).
one of customer, seller, api, assistant, system
name
string, nullable
API · and the token's name; the name the assistant goes by; or Support for the desk.
body
string, nullable
edited
boolean
deleted
boolean
body is then null and its attachments empty.
attachments
array of objects
delivery
object, nullable
state
string
sending: on its way to Monotree. sent: with Monotree. delivered: it reached them. failed: it could not be delivered; see error and send it again.
one of sending, sent, delivered, failed
error
string, nullable
state is failed.
delivered_at
string, nullable
send_state
string, nullable
delivery, kept for now: use delivery.state. Null on their messages.
one of sending, sent, failed
sent_at
string, nullable
delivered_at
string, nullable
delivery.delivered_at: use that.
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such support thread, or no such message in it.
invalid_state: the message is not an answer of yours that failed. idempotency_in_progress: a call with the same Idempotency-Key is still running.
idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: in a thread by mail this counts as an answer (20 an hour to one thread, 200 an hour in all); or over the general limit. Wait for the number of seconds in Retry-After.
curl -X POST https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/messages/msg_01m7d1awpxds8kqrrt6733j0d2/retry \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/messages/msg_01m7d1awpxds8kqrrt6733j0d2/retry', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/messages/msg_01m7d1awpxds8kqrrt6733j0d2/retry', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/messages/msg_01m7d1awpxds8kqrrt6733j0d2/retry",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "msg_01m7d1awpxds8kqrrt6733j0d2",
"object": "support_message",
"direction": "out",
"kind": "message",
"author": {
"type": "api",
"name": "API · Back office, production"
},
"body": "Bonjour Sophie, voici le guide.",
"edited": false,
"deleted": false,
"attachments": [],
"delivery": {
"state": "sent",
"error": null,
"delivered_at": null
},
"send_state": "sent",
"sent_at": "2026-11-14T12:43:21Z",
"delivered_at": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Add a note
/support/threads/{thread}/notes
support:write A note on the thread for your own people. The customer never sees it, and it does not change the thread's status. Notes come back in the thread's notes, oldest first; a note cannot be changed or removed. Sends support.thread.updated with change: noted.
Parameters
thread
required
string · path
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
body
required
string
at most 10000 characters
Response · 201 The note.
id
string
object
string
author
object
type
string
seller: one of your people, in the portal. api: a token of yours.
one of seller, api
name
string, nullable
body
string
created_at
string, nullable
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such support thread for your company and mode.
idempotency_in_progress: a call with the same Idempotency-Key is still running.
validation_error: body is missing, empty or longer than 10,000 characters. idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X POST https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/notes \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "Called the manager; she will try again on Monday."
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/notes', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'body' => 'Called the manager; she will try again on Monday.',
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/notes', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"body": "Called the manager; she will try again on Monday."
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/notes",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"body": "Called the manager; she will try again on Monday."
},
)
data = response.json(){
"id": "note_2",
"object": "support_note",
"author": {
"type": "api",
"name": "API · Back office, production"
},
"body": "Called the manager; she will try again on Monday.",
"created_at": "2026-11-14T12:43:20Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Download an attachment
/support/attachments/{attachment}
support:read The file itself, for a token that may read its thread. This is what url points to on a file sent with one of your answers: fetch it with your token in the Authorization header. A PNG, JPEG, GIF or WebP picture comes with its own content type; anything else as application/octet-stream with the file's name in Content-Disposition. A file the customer sent is kept by Monotree: its url is that address, and this endpoint redirects to it. The answer says Cache-Control: private, no-store: do not keep it in a shared cache.
Parameters
attachment
required
string · path
attachments.
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such attachment in a thread of your company and mode.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/support/attachments/att_2 \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/support/attachments/att_2', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/attachments/att_2', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/support/attachments/att_2",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json()Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.