The Messages API provides operations for retrieving, sending, searching, synchronizing, viewing message context, tracking seen state, deleting messages, and working with internal notes.
Message endpoints support both Visitor Session and Channel JWT authentication depending on the operation.
Endpoints
| Method | Path | Purpose |
| GET | /conversations/:id/messages | Get Visitor-visible messages |
| GET | /conversations/:id/messages/dashboard | Get Agent workspace messages |
| GET | /conversations/:id/messages/sync | Incrementally synchronize messages |
| POST | /conversations/:id/messages | Send a message |
| GET | /conversations/:id/messages/search | Search message text |
| GET | /conversations/:id/messages/search-by-date | Search by date |
| GET | /conversations/:id/messages/search-combined | Search by text and/or date |
| GET | /conversations/:id/messages/:messageId/context | Get surrounding message context |
| GET | /conversations/:id/messages/:messageId/seen-by | Get users who viewed a message |
| DELETE | /conversations/:id/messages/:messageId | Delete a message |
| POST | /conversations/:id/email-submission | Capture Guest email |
| POST | /conversations/:id/end-conversation | End a chat |
| POST | /internal-notes | Create an internal note |
| GET | /internal-notes | List internal notes |
Message Retrieval
GET /conversations/:id/messages?limit=20&cursor=<CURSOR>
Supported thread parameters include:
threads
threadPageSize
limit
cursor
Send a Message
POST /conversations/:id/messages
The verified request fields include:
{
“content”: “<MESSAGE_CONTENT>”,
“mediaUrl”: “<MEDIA_URL>”,
“parentId”: “<PARENT_MESSAGE_ID>”,
“isInternalNote”: false,
“clientMsgId”: “<CLIENT_MESSAGE_ID>”
}
Not every field is required for every request. The exact validation is defined by the current CreateMessageDto.
Incremental Synchronization
GET /conversations/:id/messages/sync?sinceId=<MESSAGE_ID>
Or:
GET /conversations/:id/messages/sync?since=<ISO_TIMESTAMP>
Message Status
The audit identifies:
PENDING
SENT
DELIVERED
SEEN
FAILED
Need Help?
Email: support@ysdesk.com
Documentation: https://docs.ysplugins.com/ys-desk