Chat API

Manage chat sessions, send messages, and handle agent presence.

POST/api/v1/chat/sessions

Create a new chat session for a visitor.

Authentication

Include your API key in the X-API-Key header. Get your key at app.reechdesk.com/settings.

body parameters

Name	Type	Required	Description
entityId	string	required	Entity the chat belongs to
visitorName	string	optional	Visitor display name
visitorEmail	string	optional	Visitor email for follow-up

curl -X POST https://your-domain.com/api/v1/chat/sessions \
  -H "X-API-Key: rd_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "cashmatrix",
    "visitorName": "Jane Doe",
    "visitorEmail": "jane@example.com"
  }'

Request

json

{
  "entityId": "cashmatrix",
  "visitorName": "Jane Doe",
  "visitorEmail": "jane@example.com"
}

Response201

json

{
  "id": "sess_xyz789",
  "entityId": "cashmatrix",
  "status": "ACTIVE",
  "visitorName": "Jane Doe",
  "createdAt": "2026-06-21T10:00:00Z"
}

POST/api/v1/chat/sessions/:id/messages

Send a message in a chat session.

Authentication

Include your API key in the X-API-Key header. Get your key at app.reechdesk.com/settings.

path parameters

Name	Type	Required	Description
id	string	required	Chat session ID

body parameters

Name	Type	Required	Description
body	string	required	Message content
senderType	string	required	Sender type: visitor, agent, or system
senderId	string	required	ID of the sender

curl -X POST https://your-domain.com/api/v1/chat/sessions/sess_xyz789/messages \
  -H "X-API-Key: rd_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi, I need help with my order",
    "senderType": "visitor",
    "senderId": "visitor_abc123"
  }'

Request

json

{
  "body": "Hi, I need help with my order",
  "senderType": "visitor",
  "senderId": "visitor_abc123"
}

Response201

json

{
  "id": "msg_001",
  "body": "Hi, I need help with my order",
  "senderType": "visitor",
  "createdAt": "2026-06-21T10:00:00Z"
}

Agent replies trigger email

When an agent sends a message, the visitor automatically receives an email notification with the message content and a "Continue in Chat" link.

GET/api/v1/chat/sessions/:id

Get a chat session with its messages.

Authentication

Include your API key in the X-API-Key header. Get your key at app.reechdesk.com/settings.

path parameters

Name	Type	Required	Description
id	string	required	Chat session ID

curl -H "X-API-Key: rd_test_your_key" \
  https://your-domain.com/api/v1/chat/sessions/sess_xyz789

Response200

json

{
  "id": "sess_xyz789",
  "status": "ACTIVE",
  "visitorName": "Jane Doe",
  "messages": [
    {
      "id": "msg_001",
      "body": "Hi, I need help with my order",
      "senderType": "visitor",
      "createdAt": "2026-06-21T10:00:00Z"
    },
    {
      "id": "msg_002",
      "body": "Sure! Can you share your order number?",
      "senderType": "agent",
      "senderName": "John Agent",
      "createdAt": "2026-06-21T10:01:00Z"
    }
  ]
}

POST/api/v1/chat/agent-presence

Authentication

Include your API key in the X-API-Key header. Get your key at app.reechdesk.com/settings.

body parameters

Name	Type	Required	Description
userId	string	required	Agent user ID
name	string	required	Agent display name
email	string	required	Agent email address
role	string	required	Agent role (AGENT, ADMIN)
visibility	string	optional	Visibility: PUBLIC (default) or PRIVATE

curl -X POST https://your-domain.com/api/v1/chat/agent-presence \
  -H "X-API-Key: rd_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_agent123",
    "name": "John Agent",
    "email": "agent@cashmatrix.com",
    "role": "AGENT",
    "visibility": "PUBLIC"
  }'

Request

json

{
  "userId": "usr_agent123",
  "name": "John Agent",
  "email": "agent@cashmatrix.com",
  "role": "AGENT",
  "visibility": "PUBLIC"
}

Response200

json

{
  "online": true,
  "lastSeen": "2026-06-21T10:00:00Z"
}

Presence TTL

Agent presence expires after 30 seconds. Agents must send a heartbeat every 15 seconds to stay online.

DELETE/api/v1/chat/agent-presence/:userId

Remove agent presence (go offline).

Authentication

Include your API key in the X-API-Key header. Get your key at app.reechdesk.com/settings.

path parameters

Name	Type	Required	Description
userId	string	required	Agent user ID

curl -X DELETE \
  -H "X-API-Key: rd_test_your_key" \
  https://your-domain.com/api/v1/chat/agent-presence/usr_agent123

Response200

json

{
  "removed": true
}