Concepts
The support desk
Read and answer what your customers write to support from your own helpdesk, with notes, files, the assistant's drafts, escalations to Monotree and events for everything that happens.
Your customers' people write to support from the Support room in their Monotree app, or by mail to your support address. You answer them first; Monotree is your second line. Almost everything the Support page in the portal does goes through the API too, so you can run the desk from your own helpdesk system. What still needs the portal lists the rest.
A token needs one of three abilities:
| Ability | Lets the token |
|---|---|
support:read |
Read threads, messages, files, drafts, escalations, tags, people and the desk's numbers. |
support:write |
Answer, add notes, change and merge threads, use drafts, escalate. |
support:configure |
Read and change the desk's settings, its presence and the assistant's memory, and delete a thread. |
The model
A support thread is one matter with one person at a customer: their messages, your answers, and what came of it. A message is theirs (direction: in) or an answer from your desk (out). A note is for your own people only.
A thread has a channel: chat (their Support room) or email. It has a status:
status |
Means |
|---|---|
open |
It waits for you: their last message has no answer yet. |
waiting |
It waits for the customer: your desk answered last. |
closed |
Done. When the customer writes again within the desk's reopen_days it opens again; after that a new thread starts. A waiting thread that hears nothing for the desk's idle_close_days is closed by itself, with resolution: no_response. |
dismissed |
Never one to answer: spam, a mistake, a duplicate. It never opens again by itself. |
A thread moves by itself: an answer makes it waiting, a message of theirs makes it open. You close, dismiss and reopen it.
To snooze a thread is to put it aside until a time you choose. It keeps its status, but leaves the lists of open and waiting threads until then, or until the customer writes.
The Support page shows threads in views, and the list takes the same six as view:
view |
Threads |
|---|---|
open |
open, not snoozed. |
waiting |
waiting, not snoozed. |
snoozed |
open or waiting, put aside until later. |
followup |
Any thread with an escalation Monotree has released and nobody has followed up. |
closed |
closed. |
dismissed |
dismissed. |
Each thread says where it shows in its own view field: its status, or snoozed. A thread never says followup there; ask the list for that view.
The IDs: a thread is sth_…, a message msg_…, an escalation esc_…, a person per_…, a draft drf_…, a note note_…, a file att_…, a fact of the assistant's memory mem_…. A tag has a number.
Reading threads
curl "https://partners.monotree.com/api/v1/support/threads?view=open" \
-H "Authorization: Bearer $MONOTREE_TOKEN"The thread last written in comes first (by last_message_at). Without view you get every thread. status filters on the thread's own status instead: status=open includes the open threads that are snoozed, view=open leaves them out. Sent together, both must hold. Narrow the list with channel, assignee (sel_…, none or me), kind, priority, tag, customer (an ID, or external_ref: and your own reference) q (text to find, at least 2 characters: in the subject, the summary, the latest words of the thread, the name or address of who wrote, and their company; not in older messages) and updated_since (a time in ISO 8601). A customer or assignee that does not exist answers 404, not an empty list. The list is paged with limit and cursor like every other; a thread written in while you page moves to the top and is not met twice.
A thread in the list comes without its messages:
{
"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", "role": "Manager", "locale": "fr", "device": null, "verified": true, "chat": true, "…": "…" },
"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"
}priority, kind, summary, language and tags are filled in by the assistant when it reads the thread; a priority, kind or tags you set yourself stay as you set them.
Get a support thread adds the rest: its latest 50 messages oldest first, the notes, the history (who did what, when), the escalations and the assistant's latest draft. Where has_earlier_messages is true, List messages walks further back with before and the id of the first message you have. With after and the id of the last one it gives what is new. That list has no cursor.
A message says who wrote it and, for an answer, how far it got:
{
"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"
}author.type is customer, seller (one of your people in the portal), api (a token), assistant (the assistant sending its own draft) or system (the automatic reply while the desk is offline, which has kind: auto). send_state and the outer delivered_at are older fields: read delivery instead.
To keep a copy in step, listen to the events, or ask the list with updated_since.
Answering
curl -X POST https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/messages \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"body": "Bonjour Sophie, voici le guide.", "last_seen_message": "msg_01m7d1ajqgwbvenrpw7gz6xn25"}'The answer is 201 with the whole thread, your answer last in messages. It goes to their Support room or by mail, as the thread came, and the thread becomes waiting. A closed thread opens again with it; a dismissed thread must be reopened first (409).
Monotree delivers the answer. delivery.state goes from sending to sent (Monotree has it) and delivered, or to failed with an error; then Send a failed answer again hands the same message over once more.
last_seen_message is optional and worth sending: the id of the latest message of theirs (direction: in) your agent had read. If that is no longer their latest message, nothing is sent and you get 409:
{ "error": { "type": "invalid_state", "message": "They have written again since you started. Read it first, then send." } }Read the thread again, show the new message, and send with its id.
An answer over the API is written by the token (author.type: api), not by one of your people: it assigns the thread to nobody and is not signed with a first name.
Files
Send files with an answer in the same JSON body, base64 encoded: up to 8 files, together at most 25 MB before encoding (more answers 422). Each file is an object with name and content and nothing else. body can be left out when there are files.
Only these kinds of file are taken, told by the ending of the name: pdf, png, jpg, jpeg, gif, webp, heic, txt, csv, doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp, rtf, mp4, mov, m4a and mp3. The content must be what the ending says: a page named .png or a program named .pdf is refused, and so is a .txt or .csv that holds HTML. Everything else answers 422, archives such as zip too (nothing looks inside one). A name is kept without control characters and without spaces or dots at its ends, and cut to 120 characters.
Files have limits of their own: 30 answers with files an hour, and 500 MB of files a day, both per mode. Over either the answer is 429 rate_limited.
In a thread by mail every answer is a mail, so answers there have a limit of their own: 20 an hour to one thread and 200 an hour in all. A mail also goes to every address on copy of the thread (cc, at most 10: the first ten of the customer's mail are kept), and each of them counts as one recipient: 60 recipients an hour for one thread and 1,000 an hour for all your threads by mail, whoever sends, the portal included. Answers by chat are limited to 600 an hour per mode.
{
"body": "Voici le guide.",
"attachments": [{ "name": "guide.pdf", "content": "JVBERi0xLjQK…" }]
}Every message lists its files as attachments, each with id, name, mime, size and url. For a file sent with an answer, url is Download an attachment: fetch it with your token.
curl -L https://partners.monotree.com/api/v1/support/attachments/att_2 \
-H "Authorization: Bearer $MONOTREE_TOKEN" -o guide.pdfA file the customer sent is kept by Monotree, and url is that address; the same call with the file's att_… ID redirects there.
Notes
A note is for your own people. The customer never sees it, and it does not change the thread's status.
curl -X POST https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/notes \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"body": "Called the manager; she will try again on Monday."}'{
"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"
}Notes come back in the thread's notes. A note cannot be changed or removed.
Changing a thread
PATCH the thread with only what changes:
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"]}'| Field | Does |
|---|---|
status |
closed closes it, dismissed dismisses it (with a reason: spam, mistake, duplicate, staff; api when left out), open reopens it. |
assignee |
Gives it to one of your people (sel_…, or external_ref: and your reference); null to nobody. |
priority |
urgent, high, normal or low. |
kind |
question, bug, feature_request, other, or null. |
tags |
The tags it has from now on, each by its name (a string of up to 60 characters) or its id (an integer). The list replaces the one before. |
snoozed_until |
Puts an open or waiting thread aside until a time still to come; null wakes it. |
customer |
Ties the sender of a mail to one of your customers, with every thread of theirs. |
signed |
Whether answers in this thread end with the first name of who wrote them. |
unread |
false marks it read. Reading a thread over the API does not. |
cc |
The addresses that stay on copy of a mail thread. You can take addresses off, not add them. |
Tags are the product areas of the Monotree app. The list is the same for every partner, and you cannot add to it.
What a token does shows in the thread's history under its name, and each change sends its own support.thread.updated event:
{ "type": "snoozed", "by": "API · Back office, production", "details": { "until": "2026-11-20T08:00:00+00:00" }, "at": "2026-11-14T12:43:57Z" }One PATCH changes all of it or nothing. When a field is refused (a snoozed_until in the past, a customer on a chat, a tag that does not exist), no other field of the call is changed and no event is sent.
Two threads of the same person that are one conversation can be merged: everything in the one goes over to the other, and the first is gone. The thread that stays keeps its own draft of the assistant; the drafts of the other come along as earlier rounds that were not used (outcome superseded). Deleting a thread removes it for good and needs support:configure; to keep it and take it out of the way, dismiss it.
Writing first
You can also start a thread:
- by
chat, to one of a customer's people who has written to support in their app before (List people you can write to). Where that person has an open or waiting chat thread, your message goes into it; - by
email, to an address. It always starts a new thread.
A token can only write by email to someone it has a reason to know. email must be one of:
- the address of someone at one of your customers who has written to you before (there is a message from them in a thread);
- the address of the admin Monotree invited at one of your customers that is live or suspended, exactly as it was invited. That is the admin of the customer's setup, or the one of the last change of admin that Monotree has applied (
customer.applied), or of the last invitation that was sent again. An admin address you changed a moment ago does not count until then, and the admin of a draft never does: it is only what someone typed.
Nobody else: not a colleague at the admin's mail domain, and not an address you name a customer for. Any other address answers 409 with the type invalid_state, and nothing is sent. Naming a customer narrows the check to that customer. A sandbox token must always name the customer.
List people you can write to with customer gives that invited admin first, flagged admin: true, also at a new customer where nobody has written yet: their id is null until there is a thread with them, and you write to them with channel: email and their email. People of a customer that is cancelled, deleted or not live yet are not listed.
The same rule holds for going on in a mail thread. When a customer's admin changes, a thread a token started with the admin before is no way to keep writing to that address: an answer, a draft sent or an answer sent again by a token answers 409 invalid_state when the thread's address has never written in and is no longer the admin Monotree invited. Write to the new admin, or answer from the portal. A token can change admin.email of a submitted customer three times a day (429 after that).
In the portal a seller writes by the same rule. An admin of your company can also write to a new person at a customer they name, and to anyone at the mail domain of the invited admin (never a domain anyone can have an address at, such as gmail.com).
The thread waits for the customer (waiting).
The assistant
The assistant is Monotree's AI support agent. When a customer writes, it reads the thread, sets its kind, priority, summary, language and tags, and writes a draft of an answer from the Monotree help centre and what you taught it. A draft is only a proposal: nothing is sent unless you send it, or you set the desk's auto to sends.
The latest draft is on the thread as 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": [
{ "q": "Should the answer ask which phone they use now, or only if the first step does not help?", "options": ["Ask now", "Only if the first step does not help"] }
],
"answers": [],
"note": null,
"escalation": { "category": "bug", "title": "Bonjour, mon invitation ne marche pas.", "description": "Reported in support:\n\n> Bonjour, mon invitation ne marche pas.", "tags": [] },
"sources": [],
"error": null,
"outcome": null,
"created_at": "2026-11-14T12:43:10Z",
"finished_at": "2026-11-14T12:43:10Z"
}A draft waits for you while its status is ready and its outcome is null. stale means the customer wrote again after it was drafted. A round is one turn of the customer; a version is one try within it. Four things can be done with a draft:
| You want to | Call | The draft's outcome |
|---|---|---|
Send it, as it is or with body as you changed it |
Send a draft | sent_unchanged, edited, or replaced where little of it was left |
Get another version: pick among the options of its questions in answers (each q and a at most 500 characters), say what to change in note, or both |
Ask for a draft with from |
stays null until one version is sent |
| Not use it | Put a draft aside | discarded |
Agree there is nothing to answer, where it says no_reply_needed |
Agree there is nothing to answer, which closes the thread | no_reply_accepted |
When you answer the thread yourself instead, the drafts that waited become superseded. The thread's draft can therefore be one that is done with: check outcome.
Ask for a draft without from asks for one where there is none. A draft may come back queued or running: support.thread.updated with change: drafted says when the assistant is done, and the draft is then ready, or failed with an error.
curl -X POST https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/drafts \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"from": "drf_228", "note": "Shorter, please.", "answers": [{"q": "Should the answer ask which phone they use now, or only if the first step does not help?", "a": "Ask now"}]}'How much it does by itself
The desk's auto setting says:
auto |
The assistant |
|---|---|
off |
Drafts for the messages of a thread until your desk has answered once. After that, only when you ask. |
drafts |
Drafts for every message of theirs. |
sends |
Also sends a draft it is highly sure of, as author.type: assistant. Any other draft waits for a person, and the thread says why in needs_person. It sends at most 3 answers by itself in one thread in 24 hours and 5 to one person in all their threads, none to a sender who is not verified or not tied to a customer, and none to someone at a customer that is not live: those wait for a person too. |
With auto_draft off it drafts only when you ask.
Teaching it
The assistant reads its memory before every draft: facts about how you work, each with a name, a description (a line that says what it is about) and a body (the fact). Teach it a fact:
curl -X POST https://partners.monotree.com/api/v1/support/memories \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name": "Employees are added by the admin", "description": "Employees are added by the customer'\''s admin", "body": "Only the admin of a customer can add employees: Users, then Invite. Support never adds them."}'{
"id": "mem_6",
"object": "support_memory",
"name": "employees-are-added-by-the-admin",
"description": "Employees are added by the customer's admin",
"body": "Only the admin of a customer can add employees: Users, then Invite. Support never adds them.",
"status": "remembered",
"thread": null,
"created_at": "2026-11-14T12:45:47Z",
"approved_at": "2026-11-14T12:45:47Z"
}The name is kept in lower case with dashes. Instead of writing the fact, you can send from_message with one of your answers: the assistant proposes what it would remember of it. The proposal comes back with status: proposed and counts once you agree to it with Change a fact (an empty body is enough); Forget a fact turns it down. Where the assistant finds nothing worth keeping you get 409 with the type nothing_to_learn.
Escalating to Monotree
Monotree is your second line. When a thread needs it (a bug, a feature request, or an investigation into a customer's data), escalate it:
curl -X POST https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/escalations \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"title": "Invitation link opens a blank page", "category": "bug", "description": "On Android 14 the link in the invitation mail opens a blank page.", "tags": [1]}'{
"id": "esc_01m7d1cbwj6agthjesfk7198t7",
"object": "support_escalation",
"category": "bug",
"title": "Invitation link opens a blank page",
"description": "On Android 14 the link in the invitation mail opens a blank page.",
"tags": ["Invitations"],
"status": "sent",
"released_in": null,
"customer": { "id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8", "company_name": "Boulangerie Martin", "external_ref": "org_48213" },
"threads": [
{ "id": "sth_01m7d1ajq9w7ak2vnnp8hfdwj8", "relation": "created", "follow_up_due": false, "followed_up_at": null, "follow_up_outcome": null }
],
"created_at": "2026-11-14T12:44:09Z",
"fixed_at": null,
"released_at": null
}category is bug, feature_request or investigation. tags takes the ids of tags here, and the escalation shows their names. The thread must belong to a customer, and keeps its status: escalating does not answer the customer. Where the assistant's draft has an escalation, it has written the title and description out for you.
An escalation has a status:
status |
Means |
|---|---|
sent |
It waits for Monotree to pick it up. |
received |
Monotree has it. |
fixed |
It is fixed, and not yet shipped. |
released |
It has shipped; released_in names the release. Follow up on its threads. |
declined |
Monotree will not do it. |
When a second customer reports the same thing, do not send it twice: Find similar escalations, and escalate with only duplicate_of to add the thread to the one already sent. The thread then shows in the escalation's threads with relation: duplicate.
Once an escalation is released, every thread it came from has follow_up_due: true and shows under view=followup until you follow up on it: told: true when the customer was told it has shipped, false when nobody needs telling. With draft: true the assistant drafts the message that tells them, for you to send.
curl -X POST https://partners.monotree.com/api/v1/support/threads/sth_01m7d1ajq9w7ak2vnnp8hfdwj8/escalations/esc_01m7d1cbwj6agthjesfk7198t7/follow-up \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"told": true, "draft": true}'Desk settings
The desk's settings are those of the Settings tab:
| Setting | Type | Default | Means |
|---|---|---|---|
auto_draft |
boolean | true |
The assistant drafts when a customer writes. |
auto |
off, drafts, sends |
off |
How much the assistant does by itself. |
auto_reply |
boolean | true |
A thread that starts while the desk is offline gets auto_reply_text, once. Not sent while auto is sends. |
auto_reply_text |
string, 1 to 600 characters | "Thanks for your message. We are closed right now and will answer {next_open}." | {next_open} becomes when the desk opens next. |
timezone |
IANA time zone name | Europe/Paris |
The time zone of hours. |
hours |
object with mon to sun |
09:00 to 18:00, Monday to Friday | Per day ["09:00", "18:00"] (opens, closes, on the 24 hour clock), or null for a closed day. |
holidays |
FR, ES, IT, BE, DK or null |
FR |
The country whose public holidays the desk is closed on. |
holidays_extra |
list of dates (2026-12-24), at most 60 |
[] |
More days the desk is closed. |
staff_language |
en, fr, es, it, de, nl, da |
en |
The language your people read the assistant's advice in. |
reopen_days |
integer, 0 to 90 | 7 |
A closed thread opens again when the customer writes within this many days. 0: always a new thread. |
idle_close_days |
integer, 1 to 90 | 7 |
After how many days without a message a thread that waits for the customer is closed by itself, with resolution: no_response. Checked once a day. A snoozed thread is left alone until it wakes. |
signature |
boolean | true |
Chat answers of your people end with their first name. Mail always does. |
ask_rating |
boolean | true |
When a chat is closed, the customer is asked whether the answer helped. |
debug |
boolean | false |
The portal shows how the assistant worked on a draft. |
Change them with a PATCH. A field left out is untouched. In hours, send only the days that change; null closes a day:
curl -X PATCH https://partners.monotree.com/api/v1/support/settings \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"auto": "drafts", "reopen_days": 14, "hours": {"fri": ["08:00", "16:00"]}}'A value that is not valid is refused with 422 and nothing is changed.
Whether the desk is online follows the office hours and holidays. Switch it to answer outside them, or to go offline inside them:
curl -X POST https://partners.monotree.com/api/v1/support/presence \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"online": true}'{
"object": "support_presence",
"online": true,
"forced": "online",
"forced_until": "2026-11-14T13:45:37Z",
"forced_by": "API · Back office, production",
"changes_at": "2026-11-16T08:00:00Z"
}A forced state ends by itself at forced_until: online after an hour, offline when the desk opens next. {"online": null} follows the hours again. changes_at is when the office hours next open or close.
Get support stats gives the desk's numbers over a period, as the Stats tab shows them. Each row of a breakdown has a key that stays the same (a code such as chat or under_1h, or an ID such as cus_… or sel_…) and a label in English to show.
Events for support
Subscribe a webhook endpoint to hear what happens instead of asking. The same events fire whether something was done in the portal or over the API, and List events has them too.
| Event | Sent when | data holds |
|---|---|---|
support.thread.created |
A thread started: someone at a customer wrote, or you wrote first. | thread |
support.message.received |
Someone at a customer wrote. | thread, message |
support.message.sent |
An answer left your desk: yours, the assistant's, or the automatic reply. | thread, message |
support.message.delivered |
Monotree delivered an answer. | thread, message |
support.message.failed |
An answer could not be delivered; message.delivery.error says why. |
thread, message |
support.thread.updated |
The thread changed. | thread, change, and details where there is more to say |
support.thread.rated |
The customer said whether the answer helped; see thread.rating. |
thread |
support.escalation.created |
A thread was escalated. | escalation |
support.escalation.updated |
Monotree picked an escalation up, fixed, released or declined it, or another thread was added to it. | escalation |
thread is the thread as in the list, without messages. message and escalation are as the API shows them.
change on support.thread.updated is one of closed, dismissed, reopened, assigned, priority, kind, tags, snoozed, woken, matched (its sender was tied to a customer), merged, noted, drafted (the assistant finished a draft), followed_up, urgent, human (the assistant left it to a person), auto_sent (the assistant sent its draft) and deleted. The list is open: let a value you do not know pass. details is there for some: resolution for closed, reason for dismissed, assignee for assigned, priority, until for snoozed, from for merged, escalation (its ID) and outcome for followed_up, assistant (its name) for auto_sent and human.
{
"id": "evt_01m7d1b8fsks114shtqqw1xrfj",
"object": "event",
"type": "support.message.received",
"api_version": "1.0.0",
"created_at": "2026-11-14T12:43:33Z",
"sandbox": true,
"actor": { "type": "customer", "name": "Sophie Garnier" },
"data": {
"thread": { "id": "sth_01m7d1ajq9w7ak2vnnp8hfdwj8", "object": "support_thread", "status": "open", "…": "…" },
"message": {
"id": "msg_01m7d1b8f34d98pr5q1mnbdcpt",
"object": "support_message",
"direction": "in",
"kind": "message",
"author": { "type": "customer", "name": "Sophie Garnier" },
"body": "Cela ne marche toujours pas, erreur sur Android.",
"attachments": [],
"delivery": null,
"…": "…"
}
}
}actor says who did it, as type and name: a token, a user (a person in the portal), the assistant (it sent its own draft, or left a thread to a person), or system. On support.message.sent it is whoever wrote the answer, and on support.message.received it is customer with the name of the person who wrote. On support.message.delivered and support.message.failed it is system, as Monotree reports the delivery.
Changes to the settings, the presence and the assistant's memory send no events, and neither do marking a thread read, signed and cc.
Testing in the sandbox
A sandbox token sees only the threads of sandbox customers. Nobody writes to a sandbox customer, so the token can play their part:
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."}'The message comes in as a real one does: a thread opens, the assistant drafts, the automatic reply goes out if your sandbox desk is offline, and support.thread.created and support.message.received are sent to your sandbox endpoints. The answer is 201 with the whole thread. Call it again with the same name and email and the same person writes again, in the same thread while it is open or waiting. A live token gets 403 with the type sandbox_only.
In the sandbox:
- an answer is never delivered to anyone. It is marked
deliveredat once, sosupport.message.sentis sent, andsupport.message.deliveredandsupport.message.failednever are; - an escalation never reaches Monotree. It stays
sent, so thefollowupview andsupport.escalation.updatedfor a new status cannot be tried; - the desk has settings, presence and an assistant's memory of its own, so a test never changes your real desk;
- sellers are test sellers:
assigneetakes those a sandbox token made; - a mail you start needs
customer, since a sandbox token only writes to its sandbox customers; - the assistant's drafts are scripted examples, not written by a model, and are
readyat once. A few words steer them:bug,errororne marche pasin the message give a bug with a proposedescalation;nobodyorpersonne nemake it urgent; a message that is onlyThanksorMercigives a draft withno_reply_needed; a redraft whosenotehas the wordshortgives a shorter text.
What still needs the portal
These have no endpoint:
- Writing to many people at once. The portal can send one message to everyone with a chosen role at chosen customers; the API starts one thread at a time.
- Translations. The portal can translate a customer's message into your people's language. The API gives the message as it was written.
- How the assistant worked. The steps the assistant took for a draft show in the portal only (with
debugon). - Warnings on a fact. The portal flags a fact of the assistant's memory that holds a link, an email address, something that looks like a secret, or a customer's name. The API keeps the fact without a word.
- Adding people on copy.
cccan be shortened, not added to, in the portal too: the addresses come from the customer's mail. - Changing or removing a message, a note or a tag. Nobody can, in the portal either.