API Reference - Chat Messages
Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108082
← Back to API Reference | Getting Started
Chat Messages
Chat Messages are individual messages within a live chat conversation. Each message belongs to a chat thread (identified by thread_token) and is authored by a specific participant (identified by message_owner). The message content supports HTML. Chat Messages are created when users interact with the site's live chat widget.
chat_message_items — DB table: chat_message_itemsThe Chat Message Object
| Field | Type | Description |
|---|---|---|
message_id | integer | Unique message ID (primary key, read-only) |
message_token | string | Unique token identifying this message |
thread_token | string | Token of the chat thread this message belongs to |
message_status | integer | Message status: 0 unread, 1 read |
message_owner | string | Token or identifier of the message author |
message_content | text | HTML content of the message |
created_at | string | Date and time the message was sent (format: YYYYMMDDHHmmss) |
List Chat Messages
Example Request
curl -X GET "https://www.yourdomain.com/api/v2/chat_message_items/get?limit=25" \ -H "X-Api-Key: your-api-key-here"
Example Response
{
"status": "success",
"message": [
{
"message_id": "1",
"message_token": "c14c3df7dcf7dc2aced6a2d4a09bab9a",
"thread_token": "395878c8a5f3ae1802c359ec7ac85619",
"message_status": "0",
"message_owner": "0986d338d31285f7578138137f8a7c87",
"message_content": "Hello, how can I help you?
",
"created_at": "20240301120000"
}
],
"total": "9",
"current_page": 1,
"total_pages": 1
}Retrieve a Chat Message
Example Request
curl -X GET "https://www.yourdomain.com/api/v2/chat_message_items/get/1" \ -H "X-Api-Key: your-api-key-here"
Example Response
{
"status": "success",
"message": [
{
"message_id": "1",
"message_token": "c14c3df7dcf7dc2aced6a2d4a09bab9a",
"thread_token": "395878c8a5f3ae1802c359ec7ac85619",
"message_status": "0",
"message_owner": "0986d338d31285f7578138137f8a7c87",
"message_content": "Hello, how can I help you?
",
"created_at": "20240301120000"
}
],
"total": "9",
"current_page": 1,
"total_pages": 1
}Create a Chat Message
Optional Parameters
| Parameter | Type | Description |
|---|---|---|
send_email_notifications | integer | Set to 1 to send the same reply notification email the on-site chat sends. Omitted or set to 0, the message is created without sending any email. Defaults to 0. |
Messages created without
send_email_notifications=1 are stored silently, which is how this endpoint behaved before the parameter was added. Existing integrations keep working unchanged and do not start sending mail unexpectedly.Example Request
curl -X POST "https://www.yourdomain.com/api/v2/chat_message_items/create" \ -H "X-Api-Key: your-api-key-here" \ -d "message_token=c14c3df7dcf7dc2aced6a2d4a09bab9a" \ -d "thread_token=395878c8a5f3ae1802c359ec7ac85619" \ -d "message_status=0" \ -d "message_owner=0986d338d31285f7578138137f8a7c87" \ -d "message_content=%3Cp%3EHello%2C+how+can+I+help+you%3F%3C%2Fp%3E" \ -d "created_at=20240301120000" \ -d "send_email_notifications=1"
Example Response
{
"status": "success",
"message": {
"message_id": "10",
"message_token": "c14c3df7dcf7dc2aced6a2d4a09bab9a",
"thread_token": "395878c8a5f3ae1802c359ec7ac85619",
"message_status": "0",
"message_owner": "0986d338d31285f7578138137f8a7c87",
"message_content": "Hello, how can I help you?",
"created_at": "20240301120000"
}
}Which Emails Are Sent
With send_email_notifications=1, one email goes to the other participant in the thread — whichever member did not author this message. The conversation-reply template is used. The author of the reply never receives an email, because no sender-side template exists for replies.
Whether that email is sent at all depends on the site's chat_messages_send_notifications setting.
| Setting value | Reply notification |
|---|---|
1 or empty (default) | Sent to the other participant |
2 | Sent to the other participant |
3 | Not sent at all — this value means sender-only, and replies have no sender email |
When the site's chat_member_email_notification setting is anything other than 0, the site's own email address receives a copy.
When Nothing Is Sent
Even with send_email_notifications=1, the notification step is skipped entirely — no email and no webhook — in these cases:
thread_tokenormessage_owneris empty.- No thread matches the supplied
thread_token. The request still returnssuccess, so an integration replying to a stale or mistyped token gets a normal response and no notification. - Either participant on the thread no longer resolves to an existing member.
- The receiving member's membership plan has enable_receiving_chat_messages turned off. On plans created before that setting existed, enable_direct_messages is used instead.
The message row is created regardless, and the API response is the same either way.
The chat-messages webhook is not controlled by
send_email_notifications. It fires on reply creation whether or not emails were requested, so Zapier and Make workflows behave the same as before.Update a Chat Message
Example Request
curl -X PUT "https://www.yourdomain.com/api/v2/chat_message_items/update" \ -H "X-Api-Key: your-api-key-here" \ -d "message_id=10" \ -d "message_status=1"
Example Response
{
"status": "success",
"message": {
"message_id": "10",
"message_token": "c14c3df7dcf7dc2aced6a2d4a09bab9a",
"thread_token": "395878c8a5f3ae1802c359ec7ac85619",
"message_status": "1",
"message_owner": "0986d338d31285f7578138137f8a7c87",
"message_content": "Hello, how can I help you?",
"created_at": "20240301120000"
}
}Delete a Chat Message
Example Request
curl -X DELETE "https://www.yourdomain.com/api/v2/chat_message_items/delete" \ -H "X-Api-Key: your-api-key-here" \ -d "message_id=10"
Example Response
{
"status": "success",
"message": "chat_message_items record was deleted"
}