API reference
Support threads
The conversations of your support desk: what the employees and admins of your customers ask, in their app or by email. The support guide explains the model.
Base URL https://partners.monotree.com/api/v1
· every call needs a token
Endpoints
get/support/tags
List support tags
get
/support/people
List people you can write to
get
/support/threads
List support threads
post
/support/threads
Start a support thread
post
/support/threads/simulate
Simulate a customer's message
get
/support/threads/{thread}
Get a support thread
patch
/support/threads/{thread}
Change a support thread
delete
/support/threads/{thread}
Delete a support thread
post
/support/threads/{thread}/merge
Merge a thread into another
List people you can write to
/support/people
support:read The people at your customers a thread can be started with by chat: those who have a Support room in their Monotree app and have written to support in it before. Newest first, by when they first wrote. With customer, the admin Monotree invited at that customer comes first on the first page, flagged admin: true: they can always be written to by mail (channel: email and their email), also at a new customer where nobody has written yet; their id is null until there is a thread with them. Anyone else known by mail only is not listed. People of a customer that is cancelled, deleted or not live yet are not listed: there is no Monotree to write to them in.
Parameters
limit
integer · query
default 25 · up to 100
cursor
string · query
next_cursor of the page before, for the next page. Send the same filters with it.
customer
string · query
external_ref: and your own reference.
q
string · query
Response · 200 A page of people.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_cursor: the cursor is not one this API gave out.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such customer for your company and mode.
validation_error: a field is missing or invalid; fields says which.
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/people \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/support/people', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/people', {
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/people",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"data": [
{
"id": "per_132",
"object": "support_person",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"phone": null,
"role": "Manager",
"title": null,
"locale": "fr",
"timezone": null,
"departments": [],
"device": null,
"last_active_on": null,
"verified": true,
"chat": true,
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"company_name": "Boulangerie Martin"
}
}
],
"has_more": false,
"next_cursor": null
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
List support threads
/support/threads
support:read Your customers' support threads without their messages, as the Support page lists them: the thread last written in comes first (by last_message_at). Without view you get every thread. The filters narrow together. A sandbox token lists the threads of sandbox customers only, and a live token never lists them. next_cursor holds the place of the last thread of the page, so a thread written in while you page moves to the top and is not met twice. To keep a copy in step, ask with updated_since, or listen to the support events.
Parameters
limit
integer · query
default 25 · up to 100
cursor
string · query
next_cursor of the page before, for the next page. Send the same filters with it.
view
string · query
status is the thread's own field. The two differ for a thread put aside: it keeps its status (open or waiting) but its view is snoozed. open: waits for you. waiting: waits for the customer. snoozed: open or waiting, put aside until later (those are not in open or waiting). followup: an escalation of the thread was released and nobody has followed up yet, whatever the thread's status. closed, dismissed.
one of open, waiting, snoozed, followup, closed, dismissed
status
string · query
status. Unlike view, open and waiting include the threads put aside (snoozed). Sent together with view, both must hold.
one of open, waiting, closed, dismissed
channel
string · query
chat) or mail (email).
one of chat, email
assignee
string · query
sel_5, or external_ref: and your reference for them), none for threads nobody has, or me for those of the person who made the token.
kind
string · query
one of question, bug, feature_request, other
priority
string · query
one of urgent, high, normal, low
tag
string · query
customer
string · query
external_ref: and your own reference.
q
string · query
updated_since
string · query
updated_at is at or after this time.
Response · 200 A page of threads, without their messages.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_cursor: the cursor is not one this list gave out. invalid_cursor: the cursor is not one this API gave out.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such customer (customer) or seller (assignee).
validation_error: a filter has a value that is not allowed, q is shorter than 2 characters, or tag names no tag.
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 \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/support/threads', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/threads', {
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",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"data": [
{
"id": "sth_01m7d1ajq9w7ak2vnnp8hfdwj8",
"object": "support_thread",
"channel": "chat",
"status": "open",
"view": "open",
"priority": "high",
"kind": "bug",
"subject": null,
"summary": null,
"preview": "Bonjour, mon invitation ne marche pas.",
"language": "fr",
"unread": true,
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"company_name": "Boulangerie Martin",
"external_ref": "org_48213"
},
"person": {
"id": "per_132",
"object": "support_person",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"phone": null,
"role": "Manager",
"title": null,
"locale": "fr",
"timezone": null,
"departments": [],
"device": null,
"last_active_on": null,
"verified": true,
"chat": true,
"customer": null
},
"assignee": null,
"tags": [],
"cc": [],
"signed": true,
"needs_person": null,
"no_reply_needed": false,
"snoozed_until": null,
"resolution": null,
"dismissed_reason": null,
"rating": null,
"rated_at": null,
"reopened_count": 0,
"message_count": 2,
"started_at": "2026-11-14T12:43:10Z",
"waiting_since": "2026-11-14T12:43:10Z",
"first_response_at": null,
"last_message_at": "2026-11-14T12:43:10Z",
"closed_at": null,
"updated_at": "2026-11-14T12:43:11Z"
}
],
"has_more": true,
"next_cursor": "t7Rz0aPq5WJ7ImF0IjoiMjAyNi0xMS0xNCAxMjo0MzoxMCIsImlkIjoyMjV9"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Start a support thread
/support/threads
support:write Writes to someone before they wrote, as Write to a customer does in the portal. By chat to one of a customer's people (find them with List people): where that person has a chat thread that is open or waiting, your message goes into it, since it is the same room to them; otherwise a new thread starts. By email to an address, always as a new thread. A token can only write to someone it has a reason to know: someone at one of your customers who has written to you before, or the admin Monotree invited at one of your customers that is live or suspended, by the exact address it invited (the admin of the setup, of the last change of admin that was applied, or of the last invitation sent again; an address you changed a moment ago does not count yet, and a draft's never). Nobody else: not a colleague at the admin's mail domain. Any other address answers 409 invalid_state and nothing is sent. Naming a customer narrows the check to that customer. A mail counts against the recipients that may be written to in an hour (1,000 per mode). A new thread waits for the customer (waiting) and has nobody assigned.
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
channel
required
string
one of chat, email
customer
string
external_ref: and your own reference. Needed for chat. For email it says whose the address is, and is needed with a sandbox token; it does not make an unknown address allowed.
at most 140 characters
person
string
chat: who to write to, from List people.
at most 40 characters
email
string
email: the address to write to. It must be someone who has written before, the admin email of one of your customers, or an address at that admin's own mail domain (not a public mail domain); otherwise the call answers 409.
at most 250 characters
name
string, nullable
email: their name, used where the address is new.
at most 250 characters
subject
string, nullable
email: the subject of the mail.
at most 250 characters
body
required
string
at most 10000 characters
Response · 201 The thread whole, with your message in it. For a chat this can be a thread that was there already.
id
string
object
string
channel
string
chat: their Support room in the Monotree app. email: mail to your support address.
one of chat, email
status
string
open waits for you, waiting waits for the customer. closed is done; dismissed was never one to answer (spam, a mistake, an automatic mail).
one of open, waiting, closed, dismissed
view
string
status, or snoozed for an open or waiting thread put aside until snoozed_until. Never followup: a thread under that view keeps its own view here.
one of open, waiting, snoozed, closed, dismissed
priority
string
normal until the assistant reads the thread or you set it; what you set stays.
one of urgent, high, normal, low
kind
string, nullable
one of question, bug, feature_request, other
subject
string, nullable
summary
string, nullable
preview
string, nullable
language
string, nullable
unread
boolean
unread: false.
customer
object, nullable
id
string
company_name
string
external_ref
string, nullable
person
object
id
string, nullable
email.
object
string
name
string
email
string, nullable
phone
string, nullable
role
string, nullable
title
string, nullable
locale
string, nullable
timezone
string, nullable
departments
array of strings
device
object, nullable
platform
string, nullable
model
string, nullable
os
string, nullable
app_version
string, nullable
last_active_on
string, nullable
verified
boolean
chat
boolean
admin
boolean
customer
object, nullable
customer.
id
string
company_name
string
assignee
object, nullable
id
string
name
string
tags
array of objects
cc
array of objects
signed
boolean
signature setting for a chat and is always true for a mail, unless set on the thread.
needs_person
object, nullable
auto on sends, did not send its draft and one of your people must look. Cleared when one of you answers.
since
string
reason
string, nullable
no_reply_needed
boolean
snoozed_until
string, nullable
resolution
string, nullable
answered, no_reply (there was nothing to answer), no_response (they went quiet), outreach (a message of yours to many people, sent from the portal). Null while it is open or waiting.
dismissed_reason
string, nullable
staff (by hand, no reason given), spam, mistake, duplicate, api (over the API, no reason given); or by the desk itself, auto (an automatic mail) or deleted (they took the message back).
rating
string, nullable
one of positive, negative
rated_at
string, nullable
reopened_count
integer
message_count
integer
started_at
string, nullable
waiting_since
string, nullable
first_response_at
string, nullable
last_message_at
string, nullable
closed_at
string, nullable
updated_at
string, nullable
messages
array of objects
has_earlier_messages
boolean
messages.
notes
array of objects
history
array of objects
escalations
array of objects
draft
object, nullable
id
string
object
string
status
string
queued and running: the assistant is at it. ready: written. failed: it could not be written; see error. cancelled: given up.
one of queued, running, ready, failed, cancelled
round
integer
version
integer
trigger
string
one of new, followup, redraft, manual, release
stale
boolean
body
string, nullable
language
string, nullable
summary
string, nullable
kind
string, nullable
question, bug, feature_request or other.
no_reply_needed
boolean
confidence
string, nullable
one of high, medium, low
recommendation
object, nullable
action
string
send: send the draft. ask_customer: ask the customer for more. create_ticket: escalate to Monotree. close: close without answering. escalate: hand to Monotree now.
one of send, ask_customer, create_ticket, close, escalate
label
string
text
string
unverified
array of strings
questions
array of objects
answers.
answers
array of objects
note
string, nullable
escalation
object, nullable
category
string
bug, feature_request or investigation.
title
string
description
string
tags
array of strings
sources
array of objects
error
string, nullable
status is failed.
outcome
string, nullable
sent_unchanged, edited, replaced: it was sent, as written, changed, or mostly rewritten. discarded: put aside. superseded: an answer went out another way, or a draft for their next turn replaced it. no_reply_accepted: the thread was closed on it.
one of sent_unchanged, edited, replaced, discarded, superseded, no_reply_accepted
created_at
string, nullable
finished_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 customer, or no such person at that customer.
invalid_state: the person has no Support room to write to; or, for email, the address is not someone who has written before, nor the admin Monotree invited at one of your live or suspended customers (of the one named in customer, when sent). idempotency_in_progress: a call with the same Idempotency-Key is still running.
validation_error: a field is missing for the channel (customer and person for chat, email for email), or a sandbox token sent an email without customer. idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: more than 30 threads started by email in an hour (all your tokens of one mode together; chat is not counted), more than 1,000 recipients of mails in an hour, 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 \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel": "chat",
"customer": "external_ref:org_48213",
"person": "per_132",
"body": "Bonjour Sophie, tout va bien ?"
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/support/threads', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'channel' => 'chat',
'customer' => 'external_ref:org_48213',
'person' => 'per_132',
'body' => 'Bonjour Sophie, tout va bien ?',
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/threads', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"channel": "chat",
"customer": "external_ref:org_48213",
"person": "per_132",
"body": "Bonjour Sophie, tout va bien ?"
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/support/threads",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"channel": "chat",
"customer": "external_ref:org_48213",
"person": "per_132",
"body": "Bonjour Sophie, tout va bien ?"
},
)
data = response.json(){
"id": "sth_01m7d1ajq9w7ak2vnnp8hfdwj8",
"object": "support_thread",
"channel": "chat",
"status": "waiting",
"view": "waiting",
"priority": "high",
"kind": "bug",
"subject": null,
"summary": null,
"preview": "Bonjour, mon invitation ne marche pas.",
"language": "fr",
"unread": false,
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"company_name": "Boulangerie Martin",
"external_ref": "org_48213"
},
"person": {
"id": "per_132",
"object": "support_person",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"phone": null,
"role": "Manager",
"title": null,
"locale": "fr",
"timezone": null,
"departments": [],
"device": null,
"last_active_on": null,
"verified": true,
"chat": true,
"customer": null
},
"assignee": {
"id": "sel_5",
"name": "Emma Dubois"
},
"tags": [
{
"id": 1,
"name": "Invitations",
"color": "#0e7490"
}
],
"cc": [],
"signed": true,
"needs_person": null,
"no_reply_needed": false,
"snoozed_until": null,
"resolution": null,
"dismissed_reason": null,
"rating": null,
"rated_at": null,
"reopened_count": 0,
"message_count": 2,
"started_at": "2026-11-14T12:43:10Z",
"waiting_since": null,
"first_response_at": "2026-11-14T12:43:21Z",
"last_message_at": "2026-11-14T12:43:21Z",
"closed_at": null,
"updated_at": "2026-11-14T12:44:09Z",
"messages": [
{
"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_earlier_messages": false,
"notes": [
{
"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"
}
],
"history": [
{
"type": "opened",
"by": null,
"details": null,
"at": "2026-11-14T12:43:10Z"
},
{
"type": "assigned",
"by": "API · Back office, production",
"details": {
"assignee": "Emma Dubois"
},
"at": "2026-11-14T12:44:09Z"
}
],
"escalations": [
{
"id": "esc_01m7d1cbwj6agthjesfk7198t7",
"title": "Invitation link opens a blank page",
"category": "bug",
"status": "sent",
"relation": "created",
"released_in": null,
"follow_up_due": false,
"followed_up_at": null,
"follow_up_outcome": null
}
],
"draft": {
"id": "drf_227",
"object": "support_draft",
"status": "ready",
"round": 1,
"version": 1,
"trigger": "new",
"stale": false,
"body": "Bonjour Sophie,\n\nMerci pour votre message.\n\nEssayez d'abord de vous déconnecter puis de vous reconnecter, et vérifiez que l'application Monotree est à jour.",
"language": "fr",
"summary": null,
"kind": "bug",
"no_reply_needed": false,
"confidence": "medium",
"recommendation": {
"action": "create_ticket",
"label": "Escalate to Monotree",
"text": "This sounds like a fault in the app rather than a question. Send the first steps, and escalate it to Monotree if they do not help.",
"unverified": [
"Whether it happens on every phone or only one kind."
]
},
"questions": [],
"answers": [],
"note": null,
"escalation": null,
"sources": [],
"error": null,
"outcome": "superseded",
"created_at": "2026-11-14T12:43:10Z",
"finished_at": "2026-11-14T12:43:10Z"
}
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Simulate a customer's message
/support/threads/simulate
support:write Sandbox only. Plays a message as if someone at one of your sandbox customers wrote it, through the same door real messages come in by: it lands in that person's open or waiting thread, reopens one closed within reopen_days, or starts a new thread; the assistant drafts; the automatic reply goes out when your sandbox desk is offline; and support.message.received (and support.thread.created for a new thread) are sent to your sandbox endpoints. The same name and email again is the same person writing again. Nothing in the sandbox is ever delivered to anyone.
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
customer
required
string
external_ref: and your own reference.
at most 140 characters
channel
required
string
one of chat, email
name
required
string
email again (or, without one, the same name) is the same person.
at most 250 characters
email
string, nullable
email.
at most 250 characters
role
string
one of Super admin, Admin, Editor, Manager, Manager | Editor · default Admin
subject
string, nullable
email: the subject of a new thread.
at most 250 characters
body
required
string
bug, error or ne marche pas make it a bug with a proposed escalation, nobody or personne ne make it urgent, and a bare Thanks or Merci needs no reply.
at most 10000 characters
Response · 201 The thread the message landed in, whole.
id
string
object
string
channel
string
chat: their Support room in the Monotree app. email: mail to your support address.
one of chat, email
status
string
open waits for you, waiting waits for the customer. closed is done; dismissed was never one to answer (spam, a mistake, an automatic mail).
one of open, waiting, closed, dismissed
view
string
status, or snoozed for an open or waiting thread put aside until snoozed_until. Never followup: a thread under that view keeps its own view here.
one of open, waiting, snoozed, closed, dismissed
priority
string
normal until the assistant reads the thread or you set it; what you set stays.
one of urgent, high, normal, low
kind
string, nullable
one of question, bug, feature_request, other
subject
string, nullable
summary
string, nullable
preview
string, nullable
language
string, nullable
unread
boolean
unread: false.
customer
object, nullable
id
string
company_name
string
external_ref
string, nullable
person
object
id
string, nullable
email.
object
string
name
string
email
string, nullable
phone
string, nullable
role
string, nullable
title
string, nullable
locale
string, nullable
timezone
string, nullable
departments
array of strings
device
object, nullable
platform
string, nullable
model
string, nullable
os
string, nullable
app_version
string, nullable
last_active_on
string, nullable
verified
boolean
chat
boolean
admin
boolean
customer
object, nullable
customer.
id
string
company_name
string
assignee
object, nullable
id
string
name
string
tags
array of objects
cc
array of objects
signed
boolean
signature setting for a chat and is always true for a mail, unless set on the thread.
needs_person
object, nullable
auto on sends, did not send its draft and one of your people must look. Cleared when one of you answers.
since
string
reason
string, nullable
no_reply_needed
boolean
snoozed_until
string, nullable
resolution
string, nullable
answered, no_reply (there was nothing to answer), no_response (they went quiet), outreach (a message of yours to many people, sent from the portal). Null while it is open or waiting.
dismissed_reason
string, nullable
staff (by hand, no reason given), spam, mistake, duplicate, api (over the API, no reason given); or by the desk itself, auto (an automatic mail) or deleted (they took the message back).
rating
string, nullable
one of positive, negative
rated_at
string, nullable
reopened_count
integer
message_count
integer
started_at
string, nullable
waiting_since
string, nullable
first_response_at
string, nullable
last_message_at
string, nullable
closed_at
string, nullable
updated_at
string, nullable
messages
array of objects
has_earlier_messages
boolean
messages.
notes
array of objects
history
array of objects
escalations
array of objects
draft
object, nullable
id
string
object
string
status
string
queued and running: the assistant is at it. ready: written. failed: it could not be written; see error. cancelled: given up.
one of queued, running, ready, failed, cancelled
round
integer
version
integer
trigger
string
one of new, followup, redraft, manual, release
stale
boolean
body
string, nullable
language
string, nullable
summary
string, nullable
kind
string, nullable
question, bug, feature_request or other.
no_reply_needed
boolean
confidence
string, nullable
one of high, medium, low
recommendation
object, nullable
action
string
send: send the draft. ask_customer: ask the customer for more. create_ticket: escalate to Monotree. close: close without answering. escalate: hand to Monotree now.
one of send, ask_customer, create_ticket, close, escalate
label
string
text
string
unverified
array of strings
questions
array of objects
answers.
answers
array of objects
note
string, nullable
escalation
object, nullable
category
string
bug, feature_request or investigation.
title
string
description
string
tags
array of strings
sources
array of objects
error
string, nullable
status is failed.
outcome
string, nullable
sent_unchanged, edited, replaced: it was sent, as written, changed, or mostly rewritten. discarded: put aside. superseded: an answer went out another way, or a draft for their next turn replaced it. no_reply_accepted: the thread was closed on it.
one of sent_unchanged, edited, replaced, discarded, superseded, no_reply_accepted
created_at
string, nullable
finished_at
string, nullable
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
sandbox_only: the token is a live one; only a sandbox token can simulate a message. Or insufficient_ability.
not_found: no such sandbox customer.
idempotency_in_progress: a call with the same Idempotency-Key is still running.
validation_error: a field is missing or not allowed; email is needed for the email channel. idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: more than 60 simulated messages in an hour, 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/simulate \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer": "external_ref:org_48213",
"channel": "chat",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"role": "Manager",
"body": "Bonjour, mon invitation ne marche pas."
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/support/threads/simulate', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'customer' => 'external_ref:org_48213',
'channel' => 'chat',
'name' => 'Sophie Garnier',
'email' => 'sophie@boulangeriemartin.example',
'role' => 'Manager',
'body' => 'Bonjour, mon invitation ne marche pas.',
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/threads/simulate', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"customer": "external_ref:org_48213",
"channel": "chat",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"role": "Manager",
"body": "Bonjour, mon invitation ne marche pas."
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/support/threads/simulate",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"customer": "external_ref:org_48213",
"channel": "chat",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"role": "Manager",
"body": "Bonjour, mon invitation ne marche pas."
},
)
data = response.json(){
"id": "sth_01m7d1ajq9w7ak2vnnp8hfdwj8",
"object": "support_thread",
"channel": "chat",
"status": "waiting",
"view": "waiting",
"priority": "high",
"kind": "bug",
"subject": null,
"summary": null,
"preview": "Bonjour, mon invitation ne marche pas.",
"language": "fr",
"unread": false,
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"company_name": "Boulangerie Martin",
"external_ref": "org_48213"
},
"person": {
"id": "per_132",
"object": "support_person",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"phone": null,
"role": "Manager",
"title": null,
"locale": "fr",
"timezone": null,
"departments": [],
"device": null,
"last_active_on": null,
"verified": true,
"chat": true,
"customer": null
},
"assignee": {
"id": "sel_5",
"name": "Emma Dubois"
},
"tags": [
{
"id": 1,
"name": "Invitations",
"color": "#0e7490"
}
],
"cc": [],
"signed": true,
"needs_person": null,
"no_reply_needed": false,
"snoozed_until": null,
"resolution": null,
"dismissed_reason": null,
"rating": null,
"rated_at": null,
"reopened_count": 0,
"message_count": 2,
"started_at": "2026-11-14T12:43:10Z",
"waiting_since": null,
"first_response_at": "2026-11-14T12:43:21Z",
"last_message_at": "2026-11-14T12:43:21Z",
"closed_at": null,
"updated_at": "2026-11-14T12:44:09Z",
"messages": [
{
"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_earlier_messages": false,
"notes": [
{
"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"
}
],
"history": [
{
"type": "opened",
"by": null,
"details": null,
"at": "2026-11-14T12:43:10Z"
},
{
"type": "assigned",
"by": "API · Back office, production",
"details": {
"assignee": "Emma Dubois"
},
"at": "2026-11-14T12:44:09Z"
}
],
"escalations": [
{
"id": "esc_01m7d1cbwj6agthjesfk7198t7",
"title": "Invitation link opens a blank page",
"category": "bug",
"status": "sent",
"relation": "created",
"released_in": null,
"follow_up_due": false,
"followed_up_at": null,
"follow_up_outcome": null
}
],
"draft": {
"id": "drf_227",
"object": "support_draft",
"status": "ready",
"round": 1,
"version": 1,
"trigger": "new",
"stale": false,
"body": "Bonjour Sophie,\n\nMerci pour votre message.\n\nEssayez d'abord de vous déconnecter puis de vous reconnecter, et vérifiez que l'application Monotree est à jour.",
"language": "fr",
"summary": null,
"kind": "bug",
"no_reply_needed": false,
"confidence": "medium",
"recommendation": {
"action": "create_ticket",
"label": "Escalate to Monotree",
"text": "This sounds like a fault in the app rather than a question. Send the first steps, and escalate it to Monotree if they do not help.",
"unverified": [
"Whether it happens on every phone or only one kind."
]
},
"questions": [],
"answers": [],
"note": null,
"escalation": null,
"sources": [],
"error": null,
"outcome": "superseded",
"created_at": "2026-11-14T12:43:10Z",
"finished_at": "2026-11-14T12:43:10Z"
}
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Get a support thread
/support/threads/{thread}
support:read The thread whole: its latest 50 messages oldest first, its notes, its history (who did what, when), what was escalated to Monotree from it, and the assistant's latest draft. Where has_earlier_messages is true, List messages has the ones before. Reading a thread over the API does not mark it read.
Parameters
thread
required
string · path
Response · 200 The thread.
id
string
object
string
channel
string
chat: their Support room in the Monotree app. email: mail to your support address.
one of chat, email
status
string
open waits for you, waiting waits for the customer. closed is done; dismissed was never one to answer (spam, a mistake, an automatic mail).
one of open, waiting, closed, dismissed
view
string
status, or snoozed for an open or waiting thread put aside until snoozed_until. Never followup: a thread under that view keeps its own view here.
one of open, waiting, snoozed, closed, dismissed
priority
string
normal until the assistant reads the thread or you set it; what you set stays.
one of urgent, high, normal, low
kind
string, nullable
one of question, bug, feature_request, other
subject
string, nullable
summary
string, nullable
preview
string, nullable
language
string, nullable
unread
boolean
unread: false.
customer
object, nullable
id
string
company_name
string
external_ref
string, nullable
person
object
id
string, nullable
email.
object
string
name
string
email
string, nullable
phone
string, nullable
role
string, nullable
title
string, nullable
locale
string, nullable
timezone
string, nullable
departments
array of strings
device
object, nullable
platform
string, nullable
model
string, nullable
os
string, nullable
app_version
string, nullable
last_active_on
string, nullable
verified
boolean
chat
boolean
admin
boolean
customer
object, nullable
customer.
id
string
company_name
string
assignee
object, nullable
id
string
name
string
tags
array of objects
cc
array of objects
signed
boolean
signature setting for a chat and is always true for a mail, unless set on the thread.
needs_person
object, nullable
auto on sends, did not send its draft and one of your people must look. Cleared when one of you answers.
since
string
reason
string, nullable
no_reply_needed
boolean
snoozed_until
string, nullable
resolution
string, nullable
answered, no_reply (there was nothing to answer), no_response (they went quiet), outreach (a message of yours to many people, sent from the portal). Null while it is open or waiting.
dismissed_reason
string, nullable
staff (by hand, no reason given), spam, mistake, duplicate, api (over the API, no reason given); or by the desk itself, auto (an automatic mail) or deleted (they took the message back).
rating
string, nullable
one of positive, negative
rated_at
string, nullable
reopened_count
integer
message_count
integer
started_at
string, nullable
waiting_since
string, nullable
first_response_at
string, nullable
last_message_at
string, nullable
closed_at
string, nullable
updated_at
string, nullable
messages
array of objects
has_earlier_messages
boolean
messages.
notes
array of objects
history
array of objects
escalations
array of objects
draft
object, nullable
id
string
object
string
status
string
queued and running: the assistant is at it. ready: written. failed: it could not be written; see error. cancelled: given up.
one of queued, running, ready, failed, cancelled
round
integer
version
integer
trigger
string
one of new, followup, redraft, manual, release
stale
boolean
body
string, nullable
language
string, nullable
summary
string, nullable
kind
string, nullable
question, bug, feature_request or other.
no_reply_needed
boolean
confidence
string, nullable
one of high, medium, low
recommendation
object, nullable
action
string
send: send the draft. ask_customer: ask the customer for more. create_ticket: escalate to Monotree. close: close without answering. escalate: hand to Monotree now.
one of send, ask_customer, create_ticket, close, escalate
label
string
text
string
unverified
array of strings
questions
array of objects
answers.
answers
array of objects
note
string, nullable
escalation
object, nullable
category
string
bug, feature_request or investigation.
title
string
description
string
tags
array of strings
sources
array of objects
error
string, nullable
status is failed.
outcome
string, nullable
sent_unchanged, edited, replaced: it was sent, as written, changed, or mostly rewritten. discarded: put aside. superseded: an answer went out another way, or a draft for their next turn replaced it. no_reply_accepted: the thread was closed on it.
one of sent_unchanged, edited, replaced, discarded, superseded, no_reply_accepted
created_at
string, nullable
finished_at
string, nullable
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 for 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/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8 \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8', [
'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', {
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",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "sth_01m7d1ajq9w7ak2vnnp8hfdwj8",
"object": "support_thread",
"channel": "chat",
"status": "waiting",
"view": "waiting",
"priority": "high",
"kind": "bug",
"subject": null,
"summary": null,
"preview": "Bonjour, mon invitation ne marche pas.",
"language": "fr",
"unread": false,
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"company_name": "Boulangerie Martin",
"external_ref": "org_48213"
},
"person": {
"id": "per_132",
"object": "support_person",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"phone": null,
"role": "Manager",
"title": null,
"locale": "fr",
"timezone": null,
"departments": [],
"device": null,
"last_active_on": null,
"verified": true,
"chat": true,
"customer": null
},
"assignee": {
"id": "sel_5",
"name": "Emma Dubois"
},
"tags": [
{
"id": 1,
"name": "Invitations",
"color": "#0e7490"
}
],
"cc": [],
"signed": true,
"needs_person": null,
"no_reply_needed": false,
"snoozed_until": null,
"resolution": null,
"dismissed_reason": null,
"rating": null,
"rated_at": null,
"reopened_count": 0,
"message_count": 2,
"started_at": "2026-11-14T12:43:10Z",
"waiting_since": null,
"first_response_at": "2026-11-14T12:43:21Z",
"last_message_at": "2026-11-14T12:43:21Z",
"closed_at": null,
"updated_at": "2026-11-14T12:44:09Z",
"messages": [
{
"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_earlier_messages": false,
"notes": [
{
"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"
}
],
"history": [
{
"type": "opened",
"by": null,
"details": null,
"at": "2026-11-14T12:43:10Z"
},
{
"type": "assigned",
"by": "API · Back office, production",
"details": {
"assignee": "Emma Dubois"
},
"at": "2026-11-14T12:44:09Z"
}
],
"escalations": [
{
"id": "esc_01m7d1cbwj6agthjesfk7198t7",
"title": "Invitation link opens a blank page",
"category": "bug",
"status": "sent",
"relation": "created",
"released_in": null,
"follow_up_due": false,
"followed_up_at": null,
"follow_up_outcome": null
}
],
"draft": {
"id": "drf_227",
"object": "support_draft",
"status": "ready",
"round": 1,
"version": 1,
"trigger": "new",
"stale": false,
"body": "Bonjour Sophie,\n\nMerci pour votre message.\n\nEssayez d'abord de vous déconnecter puis de vous reconnecter, et vérifiez que l'application Monotree est à jour.",
"language": "fr",
"summary": null,
"kind": "bug",
"no_reply_needed": false,
"confidence": "medium",
"recommendation": {
"action": "create_ticket",
"label": "Escalate to Monotree",
"text": "This sounds like a fault in the app rather than a question. Send the first steps, and escalate it to Monotree if they do not help.",
"unverified": [
"Whether it happens on every phone or only one kind."
]
},
"questions": [],
"answers": [],
"note": null,
"escalation": null,
"sources": [],
"error": null,
"outcome": "superseded",
"created_at": "2026-11-14T12:43:10Z",
"finished_at": "2026-11-14T12:43:10Z"
}
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Change a support thread
/support/threads/{thread}
support:write Close, dismiss or reopen it, give it to one of your people, set its priority, kind and tags, put it aside until later, or tie its sender to a customer. Send only what changes. Closing a chat asks the customer under your last answer whether it helped (if ask_rating is on and you answered in the last 7 days). Each change shows in the thread's history under the token's name and sends its own support.thread.updated event. The call changes all of it or nothing: when one field is refused (404, 409 or 422), no other field is changed and no event is sent.
Parameters
thread
required
string · path
Request body
status
string
closed closes an open or waiting thread as answered. dismissed dismisses it. open reopens a closed or dismissed thread. A thread becomes waiting only by an answer.
one of open, closed, dismissed
reason
string
status: dismissed: why.
one of staff, spam, mistake, duplicate, api · default api
assignee
string, nullable
sel_…, or external_ref: and your reference for them), or null for nobody. With a sandbox token, a test seller.
at most 140 characters
priority
string
one of urgent, high, normal, low
kind
string, nullable
one of question, bug, feature_request, other
tags
array
snoozed_until
string, nullable
customer
string
external_ref: and your own reference. A chat is tied to the company it came from.
at most 140 characters
signed
boolean
unread
boolean
false once you have shown their messages to someone, to mark the thread read. true is refused.
one of ``
cc
array of strings
cc you leave out is taken off; an address that was not there is not added.
Response · 200 The thread whole, as it now stands.
id
string
object
string
channel
string
chat: their Support room in the Monotree app. email: mail to your support address.
one of chat, email
status
string
open waits for you, waiting waits for the customer. closed is done; dismissed was never one to answer (spam, a mistake, an automatic mail).
one of open, waiting, closed, dismissed
view
string
status, or snoozed for an open or waiting thread put aside until snoozed_until. Never followup: a thread under that view keeps its own view here.
one of open, waiting, snoozed, closed, dismissed
priority
string
normal until the assistant reads the thread or you set it; what you set stays.
one of urgent, high, normal, low
kind
string, nullable
one of question, bug, feature_request, other
subject
string, nullable
summary
string, nullable
preview
string, nullable
language
string, nullable
unread
boolean
unread: false.
customer
object, nullable
id
string
company_name
string
external_ref
string, nullable
person
object
id
string, nullable
email.
object
string
name
string
email
string, nullable
phone
string, nullable
role
string, nullable
title
string, nullable
locale
string, nullable
timezone
string, nullable
departments
array of strings
device
object, nullable
platform
string, nullable
model
string, nullable
os
string, nullable
app_version
string, nullable
last_active_on
string, nullable
verified
boolean
chat
boolean
admin
boolean
customer
object, nullable
customer.
id
string
company_name
string
assignee
object, nullable
id
string
name
string
tags
array of objects
cc
array of objects
signed
boolean
signature setting for a chat and is always true for a mail, unless set on the thread.
needs_person
object, nullable
auto on sends, did not send its draft and one of your people must look. Cleared when one of you answers.
since
string
reason
string, nullable
no_reply_needed
boolean
snoozed_until
string, nullable
resolution
string, nullable
answered, no_reply (there was nothing to answer), no_response (they went quiet), outreach (a message of yours to many people, sent from the portal). Null while it is open or waiting.
dismissed_reason
string, nullable
staff (by hand, no reason given), spam, mistake, duplicate, api (over the API, no reason given); or by the desk itself, auto (an automatic mail) or deleted (they took the message back).
rating
string, nullable
one of positive, negative
rated_at
string, nullable
reopened_count
integer
message_count
integer
started_at
string, nullable
waiting_since
string, nullable
first_response_at
string, nullable
last_message_at
string, nullable
closed_at
string, nullable
updated_at
string, nullable
messages
array of objects
has_earlier_messages
boolean
messages.
notes
array of objects
history
array of objects
escalations
array of objects
draft
object, nullable
id
string
object
string
status
string
queued and running: the assistant is at it. ready: written. failed: it could not be written; see error. cancelled: given up.
one of queued, running, ready, failed, cancelled
round
integer
version
integer
trigger
string
one of new, followup, redraft, manual, release
stale
boolean
body
string, nullable
language
string, nullable
summary
string, nullable
kind
string, nullable
question, bug, feature_request or other.
no_reply_needed
boolean
confidence
string, nullable
one of high, medium, low
recommendation
object, nullable
action
string
send: send the draft. ask_customer: ask the customer for more. create_ticket: escalate to Monotree. close: close without answering. escalate: hand to Monotree now.
one of send, ask_customer, create_ticket, close, escalate
label
string
text
string
unverified
array of strings
questions
array of objects
answers.
answers
array of objects
note
string, nullable
escalation
object, nullable
category
string
bug, feature_request or investigation.
title
string
description
string
tags
array of strings
sources
array of objects
error
string, nullable
status is failed.
outcome
string, nullable
sent_unchanged, edited, replaced: it was sent, as written, changed, or mostly rewritten. discarded: put aside. superseded: an answer went out another way, or a draft for their next turn replaced it. no_reply_accepted: the thread was closed on it.
one of sent_unchanged, edited, replaced, discarded, superseded, no_reply_accepted
created_at
string, nullable
finished_at
string, nullable
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, seller (assignee) or customer.
invalid_state: snoozed_until is in the past or the thread is closed or dismissed; status: closed was sent for a dismissed thread (reopen it first; closing a closed thread changes nothing and answers 200); or customer was sent for a chat, which stays with the company it came from.
validation_error: a value is not allowed, a tag does not exist, or unread is not false.
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 PATCH https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8 \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assignee": "sel_5",
"priority": "high",
"tags": [
"Invitations",
"Login"
],
"snoozed_until": "2026-11-20T08:00:00Z"
}'$client = new GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'assignee' => 'sel_5',
'priority' => 'high',
'tags' => [
'Invitations',
'Login',
],
'snoozed_until' => '2026-11-20T08:00:00Z',
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"assignee": "sel_5",
"priority": "high",
"tags": [
"Invitations",
"Login"
],
"snoozed_until": "2026-11-20T08:00:00Z"
}),
});
const data = await response.json();import os
import requests
response = requests.patch(
"https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"assignee": "sel_5",
"priority": "high",
"tags": [
"Invitations",
"Login"
],
"snoozed_until": "2026-11-20T08:00:00Z"
},
)
data = response.json(){
"id": "sth_01m7d1ajq9w7ak2vnnp8hfdwj8",
"object": "support_thread",
"channel": "chat",
"status": "waiting",
"view": "waiting",
"priority": "high",
"kind": "bug",
"subject": null,
"summary": null,
"preview": "Bonjour, mon invitation ne marche pas.",
"language": "fr",
"unread": false,
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"company_name": "Boulangerie Martin",
"external_ref": "org_48213"
},
"person": {
"id": "per_132",
"object": "support_person",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"phone": null,
"role": "Manager",
"title": null,
"locale": "fr",
"timezone": null,
"departments": [],
"device": null,
"last_active_on": null,
"verified": true,
"chat": true,
"customer": null
},
"assignee": {
"id": "sel_5",
"name": "Emma Dubois"
},
"tags": [
{
"id": 1,
"name": "Invitations",
"color": "#0e7490"
}
],
"cc": [],
"signed": true,
"needs_person": null,
"no_reply_needed": false,
"snoozed_until": null,
"resolution": null,
"dismissed_reason": null,
"rating": null,
"rated_at": null,
"reopened_count": 0,
"message_count": 2,
"started_at": "2026-11-14T12:43:10Z",
"waiting_since": null,
"first_response_at": "2026-11-14T12:43:21Z",
"last_message_at": "2026-11-14T12:43:21Z",
"closed_at": null,
"updated_at": "2026-11-14T12:44:09Z",
"messages": [
{
"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_earlier_messages": false,
"notes": [
{
"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"
}
],
"history": [
{
"type": "opened",
"by": null,
"details": null,
"at": "2026-11-14T12:43:10Z"
},
{
"type": "assigned",
"by": "API · Back office, production",
"details": {
"assignee": "Emma Dubois"
},
"at": "2026-11-14T12:44:09Z"
}
],
"escalations": [
{
"id": "esc_01m7d1cbwj6agthjesfk7198t7",
"title": "Invitation link opens a blank page",
"category": "bug",
"status": "sent",
"relation": "created",
"released_in": null,
"follow_up_due": false,
"followed_up_at": null,
"follow_up_outcome": null
}
],
"draft": {
"id": "drf_227",
"object": "support_draft",
"status": "ready",
"round": 1,
"version": 1,
"trigger": "new",
"stale": false,
"body": "Bonjour Sophie,\n\nMerci pour votre message.\n\nEssayez d'abord de vous déconnecter puis de vous reconnecter, et vérifiez que l'application Monotree est à jour.",
"language": "fr",
"summary": null,
"kind": "bug",
"no_reply_needed": false,
"confidence": "medium",
"recommendation": {
"action": "create_ticket",
"label": "Escalate to Monotree",
"text": "This sounds like a fault in the app rather than a question. Send the first steps, and escalate it to Monotree if they do not help.",
"unverified": [
"Whether it happens on every phone or only one kind."
]
},
"questions": [],
"answers": [],
"note": null,
"escalation": null,
"sources": [],
"error": null,
"outcome": "superseded",
"created_at": "2026-11-14T12:43:10Z",
"finished_at": "2026-11-14T12:43:10Z"
}
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Delete a support thread
/support/threads/{thread}
support:configure Removes the thread for good, with its messages, notes, drafts and the files sent with your answers. A last support.thread.updated with change: deleted is sent. In the portal only an admin can do this, so it needs support:configure. To take a thread out of the way and keep it, dismiss it instead.
Parameters
thread
required
string · path
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 for 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 -X DELETE https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8 \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8', [
'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', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.delete(
"https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8",
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.
Merge a thread into another
/support/threads/{thread}/merge
support:write One conversation that became two threads is made one again: the messages, notes, history, drafts, tags and escalations of this thread go over to into, and this thread is gone (its ID then answers 404). The thread that stays keeps its own current draft; the drafts that come over count as earlier rounds that were not used (superseded). Only two threads of the same person can be merged. The thread that stays is open if their last message has no answer, and sends support.thread.updated with change: merged.
Parameters
thread
required
string · path
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
into
required
string
at most 40 characters
Response · 200 The thread that stayed, whole.
id
string
object
string
channel
string
chat: their Support room in the Monotree app. email: mail to your support address.
one of chat, email
status
string
open waits for you, waiting waits for the customer. closed is done; dismissed was never one to answer (spam, a mistake, an automatic mail).
one of open, waiting, closed, dismissed
view
string
status, or snoozed for an open or waiting thread put aside until snoozed_until. Never followup: a thread under that view keeps its own view here.
one of open, waiting, snoozed, closed, dismissed
priority
string
normal until the assistant reads the thread or you set it; what you set stays.
one of urgent, high, normal, low
kind
string, nullable
one of question, bug, feature_request, other
subject
string, nullable
summary
string, nullable
preview
string, nullable
language
string, nullable
unread
boolean
unread: false.
customer
object, nullable
id
string
company_name
string
external_ref
string, nullable
person
object
id
string, nullable
email.
object
string
name
string
email
string, nullable
phone
string, nullable
role
string, nullable
title
string, nullable
locale
string, nullable
timezone
string, nullable
departments
array of strings
device
object, nullable
platform
string, nullable
model
string, nullable
os
string, nullable
app_version
string, nullable
last_active_on
string, nullable
verified
boolean
chat
boolean
admin
boolean
customer
object, nullable
customer.
id
string
company_name
string
assignee
object, nullable
id
string
name
string
tags
array of objects
cc
array of objects
signed
boolean
signature setting for a chat and is always true for a mail, unless set on the thread.
needs_person
object, nullable
auto on sends, did not send its draft and one of your people must look. Cleared when one of you answers.
since
string
reason
string, nullable
no_reply_needed
boolean
snoozed_until
string, nullable
resolution
string, nullable
answered, no_reply (there was nothing to answer), no_response (they went quiet), outreach (a message of yours to many people, sent from the portal). Null while it is open or waiting.
dismissed_reason
string, nullable
staff (by hand, no reason given), spam, mistake, duplicate, api (over the API, no reason given); or by the desk itself, auto (an automatic mail) or deleted (they took the message back).
rating
string, nullable
one of positive, negative
rated_at
string, nullable
reopened_count
integer
message_count
integer
started_at
string, nullable
waiting_since
string, nullable
first_response_at
string, nullable
last_message_at
string, nullable
closed_at
string, nullable
updated_at
string, nullable
messages
array of objects
has_earlier_messages
boolean
messages.
notes
array of objects
history
array of objects
escalations
array of objects
draft
object, nullable
id
string
object
string
status
string
queued and running: the assistant is at it. ready: written. failed: it could not be written; see error. cancelled: given up.
one of queued, running, ready, failed, cancelled
round
integer
version
integer
trigger
string
one of new, followup, redraft, manual, release
stale
boolean
body
string, nullable
language
string, nullable
summary
string, nullable
kind
string, nullable
question, bug, feature_request or other.
no_reply_needed
boolean
confidence
string, nullable
one of high, medium, low
recommendation
object, nullable
action
string
send: send the draft. ask_customer: ask the customer for more. create_ticket: escalate to Monotree. close: close without answering. escalate: hand to Monotree now.
one of send, ask_customer, create_ticket, close, escalate
label
string
text
string
unverified
array of strings
questions
array of objects
answers.
answers
array of objects
note
string, nullable
escalation
object, nullable
category
string
bug, feature_request or investigation.
title
string
description
string
tags
array of strings
sources
array of objects
error
string, nullable
status is failed.
outcome
string, nullable
sent_unchanged, edited, replaced: it was sent, as written, changed, or mostly rewritten. discarded: put aside. superseded: an answer went out another way, or a draft for their next turn replaced it. no_reply_accepted: the thread was closed on it.
one of sent_unchanged, edited, replaced, discarded, superseded, no_reply_accepted
created_at
string, nullable
finished_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: one of the two threads does not exist for your company and mode.
invalid_state: the two threads are of different people, or are the same thread. idempotency_in_progress: a call with the same Idempotency-Key is still running.
validation_error: into is missing. 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/merge \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"into": "sth_01m7d1eq5nqnr07hphj298061a"
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/merge', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'into' => 'sth_01m7d1eq5nqnr07hphj298061a',
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/merge', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"into": "sth_01m7d1eq5nqnr07hphj298061a"
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/merge",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"into": "sth_01m7d1eq5nqnr07hphj298061a"
},
)
data = response.json(){
"id": "sth_01m7d1ajq9w7ak2vnnp8hfdwj8",
"object": "support_thread",
"channel": "chat",
"status": "waiting",
"view": "waiting",
"priority": "high",
"kind": "bug",
"subject": null,
"summary": null,
"preview": "Bonjour, mon invitation ne marche pas.",
"language": "fr",
"unread": false,
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"company_name": "Boulangerie Martin",
"external_ref": "org_48213"
},
"person": {
"id": "per_132",
"object": "support_person",
"name": "Sophie Garnier",
"email": "sophie@boulangeriemartin.example",
"phone": null,
"role": "Manager",
"title": null,
"locale": "fr",
"timezone": null,
"departments": [],
"device": null,
"last_active_on": null,
"verified": true,
"chat": true,
"customer": null
},
"assignee": {
"id": "sel_5",
"name": "Emma Dubois"
},
"tags": [
{
"id": 1,
"name": "Invitations",
"color": "#0e7490"
}
],
"cc": [],
"signed": true,
"needs_person": null,
"no_reply_needed": false,
"snoozed_until": null,
"resolution": null,
"dismissed_reason": null,
"rating": null,
"rated_at": null,
"reopened_count": 0,
"message_count": 2,
"started_at": "2026-11-14T12:43:10Z",
"waiting_since": null,
"first_response_at": "2026-11-14T12:43:21Z",
"last_message_at": "2026-11-14T12:43:21Z",
"closed_at": null,
"updated_at": "2026-11-14T12:44:09Z",
"messages": [
{
"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_earlier_messages": false,
"notes": [
{
"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"
}
],
"history": [
{
"type": "opened",
"by": null,
"details": null,
"at": "2026-11-14T12:43:10Z"
},
{
"type": "assigned",
"by": "API · Back office, production",
"details": {
"assignee": "Emma Dubois"
},
"at": "2026-11-14T12:44:09Z"
}
],
"escalations": [
{
"id": "esc_01m7d1cbwj6agthjesfk7198t7",
"title": "Invitation link opens a blank page",
"category": "bug",
"status": "sent",
"relation": "created",
"released_in": null,
"follow_up_due": false,
"followed_up_at": null,
"follow_up_outcome": null
}
],
"draft": {
"id": "drf_227",
"object": "support_draft",
"status": "ready",
"round": 1,
"version": 1,
"trigger": "new",
"stale": false,
"body": "Bonjour Sophie,\n\nMerci pour votre message.\n\nEssayez d'abord de vous déconnecter puis de vous reconnecter, et vérifiez que l'application Monotree est à jour.",
"language": "fr",
"summary": null,
"kind": "bug",
"no_reply_needed": false,
"confidence": "medium",
"recommendation": {
"action": "create_ticket",
"label": "Escalate to Monotree",
"text": "This sounds like a fault in the app rather than a question. Send the first steps, and escalate it to Monotree if they do not help.",
"unverified": [
"Whether it happens on every phone or only one kind."
]
},
"questions": [],
"answers": [],
"note": null,
"escalation": null,
"sources": [],
"error": null,
"outcome": "superseded",
"created_at": "2026-11-14T12:43:10Z",
"finished_at": "2026-11-14T12:43:10Z"
}
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.