POST /messages
Updated Oct 1, 20262 minute read
Send a message
The first message creates the visitor and the conversation. The AI starts answering unless a person already holds the thread.
New user values overwrite old ones and omitted fields are not erased. Query strings are stripped from page URLs on arrival.
Part of Conversations.
Request body
application/json, required.
| Field | Type | Required | Description |
|---|---|---|---|
session | string | Yes | The visitor's session token. |
body | string | Yes | The message. Can be empty when the message carries attachments. |
user | object | No | Who this is, shown to your team. |
user.name | string | No | Cut to 80 characters. |
user.email | string | No | Cut to 320 characters. |
user.avatarUrl | string | No | An HTTPS URL up to 512 characters. Anything else is dropped. |
user.metadata | object | No | Your own facts about them: plan, seats, account age. The first 16 entries are kept, and keys and values are cut to 200 characters. |
context | object | No | The visitor's browser, shown beside the thread. |
context.timeZone | string | No | |
context.locale | string | No | |
context.browser | string | No | |
context.os | string | No | |
context.device | "desktop" | "tablet" | "mobile" | No | |
context.screen | string | No | |
page | object | No | Where they wrote from. Kept on the conversation's first message. |
page.url | string | Yes | |
page.title | string | No | |
page.referrer | string | No | |
attachments | object[] | No | Up to 6 files, with ids from POST /uploads. |
attachments[].id | string | Yes | |
attachments[].name | string | Yes |
Responses
| Status | Description |
|---|---|
200 | The conversation it landed in, and the message. |
400 | invalid_json: the body is not a JSON object. invalid_request: a field is missing, has the wrong type, or is unknown, and the message names the allowed fields. invalid_session: the session is not 8 to 128 characters. empty_message: no body and no attachments. message_too_long: the body is over 4,000 characters. too_many_attachments: more than 6. attachment_missing: an id is not a file from POST /uploads. attachment_wrong_type: the file is HTML, XHTML, SVG or XSLT. |
401 | missing_api_key: no bearer token. invalid_api_key: the key matches no organization or was revoked. publishable_key: a median_pk_ key was sent. An OAuth access token is refused here with invalid_api_key. |
429 | The organization's API allowance for this class of request is used up. Wait the Retry-After header's seconds. Limits depend on the plan. See rate limits. |
200 body
| Field | Type | Required | Description |
|---|---|---|---|
conversationId | string | Yes | |
messageId | string | Yes |
Example response
{
"conversationId": "js7...",
"messageId": "jd2..."
}Example request
curl -X POST https://api.median.sh/v1/messages \
-H "Authorization: Bearer $MEDIAN_KEY" \
-H "content-type: application/json" \
-d '{"session":"user_42","body":"How do I export my data?","user":{"name":"Ada","email":"ada@example.com"}}'