API Reference - Chat Threads

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108083

← Back to API Reference | Getting Started

Chat Threads

Chat Threads represent live chat conversations on your directory website. Each thread groups together one or more Chat Messages between a visitor and a site administrator. Threads track the participants, status, and origin of each conversation.

Model name in URL: chat_message_threads — DB table: chat_message_threads

The Chat Thread Object

FieldTypeDescription
thread_idintegerUnique thread ID (primary key, read-only)
thread_statusintegerThread status: 1 active/open, 0 closed
thread_tokenstringUnique token identifying this thread (referenced by chat messages)
thread_ownerstringToken or identifier of the conversation initiator (visitor)
created_atstringDate and time the thread was created (format: YYYYMMDDHHmmss)
updated_atstringDate and time the thread was last updated (format: YYYYMMDDHHmmss)
thread_respondersstringToken or identifier of the admin or responder in this thread
deleted_atstringDate and time the thread was soft-deleted (empty if not deleted)
origin_ipstringIP address of the visitor who initiated the thread
request_uristringPage URL where the chat was initiated

List Chat Threads

GET /api/v2/chat_message_threads/get

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/chat_message_threads/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "thread_id": "1",
      "thread_status": "1",
      "thread_token": "395878c8a5f3ae1802c359ec7ac85619",
      "thread_owner": "0986d338d31285f7578138137f8a7c87",
      "created_at": "20240301120000",
      "updated_at": "20240301120000",
      "thread_responders": "eed4fb943e7170dffe8ed9d96650140a",
      "deleted_at": "",
      "origin_ip": "203.0.113.42",
      "request_uri": "/contact"
    }
  ],
  "total": "4",
  "current_page": 1,
  "total_pages": 1
}

Retrieve a Chat Thread

GET /api/v2/chat_message_threads/get/{thread_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/chat_message_threads/get/1" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "thread_id": "1",
      "thread_status": "1",
      "thread_token": "395878c8a5f3ae1802c359ec7ac85619",
      "thread_owner": "0986d338d31285f7578138137f8a7c87",
      "created_at": "20240301120000",
      "updated_at": "20240301120000",
      "thread_responders": "eed4fb943e7170dffe8ed9d96650140a",
      "deleted_at": "",
      "origin_ip": "203.0.113.42",
      "request_uri": "/contact"
    }
  ],
  "total": "4",
  "current_page": 1,
  "total_pages": 1
}

Create a Chat Thread

POST /api/v2/chat_message_threads/create

Optional Parameters

ParameterTypeDescription
send_email_notificationsintegerSet to 1 to send the same conversation-started notification emails the on-site chat sends. Omitted or set to 0, the thread is created without sending any email. Defaults to 0.
Email notifications are opt-in.
Threads 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

Copy
curl -X POST "https://www.yourdomain.com/api/v2/chat_message_threads/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "thread_status=1" \
  -d "thread_token=395878c8a5f3ae1802c359ec7ac85619" \
  -d "thread_owner=0986d338d31285f7578138137f8a7c87" \
  -d "created_at=20240301120000" \
  -d "updated_at=20240301120000" \
  -d "thread_responders=eed4fb943e7170dffe8ed9d96650140a" \
  -d "origin_ip=203.0.113.42" \
  -d "request_uri=%2Fcontact" \
  -d "send_email_notifications=1"

Example Response

Copy
{
  "status": "success",
  "message": {
    "thread_id": "5",
    "thread_status": "1",
    "thread_token": "395878c8a5f3ae1802c359ec7ac85619",
    "thread_owner": "0986d338d31285f7578138137f8a7c87",
    "created_at": "20240301120000",
    "updated_at": "20240301120000",
    "thread_responders": "eed4fb943e7170dffe8ed9d96650140a",
    "deleted_at": "",
    "origin_ip": "203.0.113.42",
    "request_uri": "/contact"
  }
}

Which Emails Are Sent

With send_email_notifications=1, the endpoint sends the same emails the site sends when a member starts a conversation through the site's own chat. Recipients depend on the site's chat_messages_send_notifications setting.

Setting valueRecipientsEmail template
1 or empty (default)Sender and receiverstart-conversation-general-user and start-conversation-member
2Receiver onlystart-conversation-member
3Sender onlystart-conversation-general-user

When the site's chat_member_email_notification setting is anything other than 0, the site's own email address receives a copy of the receiver's notification.

When Nothing Is Sent

Even with send_email_notifications=1, the notification step is skipped entirely — no emails and no webhook — in these cases:

  • thread_owner or thread_responders does not resolve 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 thread row is created regardless, and the API response is the same either way.

Webhooks are separate.
The chat-messages webhook is not controlled by send_email_notifications. It fires on thread creation whether or not emails were requested, so Zapier and Make workflows behave the same as before.

Update a Chat Thread

PUT /api/v2/chat_message_threads/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/chat_message_threads/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "thread_id=5" \
  -d "thread_status=0"

Example Response

Copy
{
  "status": "success",
  "message": {
    "thread_id": "5",
    "thread_status": "0",
    "thread_token": "395878c8a5f3ae1802c359ec7ac85619",
    "thread_owner": "0986d338d31285f7578138137f8a7c87",
    "created_at": "20240301120000",
    "updated_at": "20240301120000",
    "thread_responders": "eed4fb943e7170dffe8ed9d96650140a",
    "deleted_at": "",
    "origin_ip": "203.0.113.42",
    "request_uri": "/contact"
  }
}

Delete a Chat Thread

DELETE /api/v2/chat_message_threads/delete

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/chat_message_threads/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "thread_id=5"

Example Response

Copy
{
  "status": "success",
  "message": "chat_message_threads record was deleted"
}