Direct Messages

Send a direct message to a single user's private chat, delivered by a bot user. The 1:1 room between the bot and the user is created on first use and reused afterwards, so repeated messages land in the same conversation. Resolve the target user first via the Users endpoints — for example, match by email.

This is the authenticated equivalent of a direct_message incoming webhook: use this endpoint for one-off sends from your backend, and incoming webhooks when you want a standing per-user URL.

Required scope: write:chat_messages

Endpoints

POST

/api/open/v1/users/{id}/messages

Send a direct message to the user

Send a message

curl -X POST https://customer.monotree.com/api/open/v1/users/4012/messages \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_user_id": 873,
    "text": "Hi Alex, Sam has replied to your thread. Follow up before Thursday: https://example.com/threads/123"
  }'

Field	Type	Notes
`bot_user_id`	integer	Required. The bot user that sends the message. A non-bot id returns `422`.
`text`	string	Required. The message body.
`media`	array	Optional. `{ url, type }` pairs — same rules as incoming webhook media (same type, max 10, publicly reachable URLs).

The target user ({id} in the path) must be a regular, registered user; a kiosk, bot, or unregistered id returns 404.

Response

{
  "data": {
    "id": 5512,
    "room_id": 240,
    "text": "Hi Alex, Sam has replied to your thread. Follow up before Thursday: https://example.com/threads/123",
    "bot_user_id": 873,
    "created_at": "2026-06-13T10:00:00+00:00"
  }
}