Skip to Content
🎉 Welcome to Delivery Chat Documentation
V1Rest APIConversations

Conversations

Conversations are the top-level container for chat interactions. A visitor creates a conversation, an operator accepts it, and messages flow between them.

Visitor Identity

Every request requires an X-Visitor-Id header containing a UUID v4 that identifies the visitor across sessions.

Generate it once and persist it in localStorage:

function getVisitorId() {
  const stored = localStorage.getItem("dc_visitor_id");
  if (stored) return stored;
 
  const id = crypto.randomUUID();
  localStorage.setItem("dc_visitor_id", id);
  return id;
}
 
const visitorId = getVisitorId();

The server automatically creates an anonymous user on the first request. Subsequent requests with the same UUID are recognized as the same visitor — including their conversation history.

⚠️

Persistence

If the visitor clears their localStorage, a new UUID is generated and their previous conversation history is no longer accessible from the client side.

Conversation Lifecycle

StatusDescription
pendingCreated by visitor, waiting for an operator to accept
activeAccepted by an operator, messages can be exchanged
closedResolved by the operator

Create a Conversation

POST /api/v1/conversations

Creates a new conversation. The visitor is automatically added as the first participant. Operators see the conversation appear in their queue in real-time.

Request Body

FieldTypeRequiredDescription
subjectstringNoSubject line (1–500 chars)

cURL Example

curl -X POST https://api.deliverychat.online/api/v1/conversations \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "X-App-Id: your-app-id" \
  -H "X-Visitor-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Origin: https://your-domain.com" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Help with my order"}'

Response — 201 Created

{
  "conversation": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending",
    "subject": "Help with my order",
    "participants": [
      {
        "userId": "550e8400-e29b-41d4-a716-446655440000",
        "role": "visitor",
        "joinedAt": "2025-01-15T10:30:00.000Z"
      }
    ],
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Errors

StatusErrorWhen
400bad_requestMissing or invalid request body
401unauthorizedInvalid API key or App ID
429rate_limit_exceededRate limit exceeded

List Conversations

GET /api/v1/conversations

Returns conversations where the visitor is an active participant, ordered by most recently updated.

Query Parameters

ParameterTypeDefaultDescription
limitinteger20Items per page (1–100)
offsetinteger0Items to skip

cURL Example

curl "https://api.deliverychat.online/api/v1/conversations?limit=10&offset=0" \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "X-App-Id: your-app-id" \
  -H "X-Visitor-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Origin: https://your-domain.com"

Response — 200 OK

{
  "conversations": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "active",
      "subject": "Help with my order",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:35:00.000Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Get a Conversation

GET /api/v1/conversations/:id

Returns a single conversation with its participant list. Returns 404 if the conversation doesn’t exist or the visitor is not a participant.

cURL Example

curl https://api.deliverychat.online/api/v1/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "X-App-Id: your-app-id" \
  -H "X-Visitor-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Origin: https://your-domain.com"

Response — 200 OK

{
  "conversation": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "active",
    "subject": "Help with my order",
    "assignedTo": "operator-uuid",
    "participants": [
      { "userId": "550e8400-...", "role": "visitor", "joinedAt": "2025-01-15T10:30:00.000Z" },
      { "userId": "operator-uuid", "role": "operator", "joinedAt": "2025-01-15T10:31:00.000Z" }
    ],
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:35:00.000Z"
  }
}

Errors

StatusErrorWhen
404not_foundConversation not found or visitor is not a participant

Mark as Read

POST /api/v1/conversations/:id/read

Marks the conversation as read up to a specific message. Updates the visitor’s lastReadMessageId.

Request Body

FieldTypeRequiredDescription
messageIdstring (UUID)YesID of the last message the visitor has read

cURL Example

curl -X POST https://api.deliverychat.online/api/v1/conversations/conv-uuid/read \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "X-App-Id: your-app-id" \
  -H "X-Visitor-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"messageId": "msg-uuid"}'

Response — 200 OK

{
  "success": true
}

Get Unread Count

GET /api/v1/conversations/:id/unread

Returns the number of staff-sent messages since the visitor’s last read position.

cURL Example

curl https://api.deliverychat.online/api/v1/conversations/conv-uuid/unread \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "X-App-Id: your-app-id" \
  -H "X-Visitor-Id: 550e8400-e29b-41d4-a716-446655440000"

Response — 200 OK

{
  "unreadCount": 3
}

Errors

StatusErrorWhen
404not_foundConversation not found or visitor is not a participant
Last updated on
Message FormatsErrors & Rate Limiting