REST API Quickstart

The Delivery Chat REST API lets you create conversations, send messages, and manage chat from your own backend or client — no widget required.

Base URL

All API requests go to:


https://api.deliverychat.online/api/v1

The API key alone identifies your application and organization, but both headers are required together as a defense-in-depth check — if you accidentally use a key from a different app, the mismatch is caught immediately.

Authentication

Every request requires three headers:

Header	Value	Description
`Authorization`	`Bearer dk_live_...`	Your API key (generate one)
`X-App-Id`	`app_uuid`	Your application ID. Required alongside the API key as an explicit cross-check — even though the key alone resolves to an application server-side, passing the ID explicitly ensures a mismatched key/app combination is caught immediately.
`X-Visitor-Id`	`uuid`	Server-managed UUID identifying the end user. Generated once per visitor, stored and reused by your backend.
`Origin`	`https://your-domain.com`	The origin of your application. Used to validate requests against your registered domain.

⚠️

Keep your API key and App ID secret

Your API key and X-App-Id grant full access to your application’s chat data. Never expose them in client-side code — inject them only from your server.

Quickstart: Send Your First Message

ℹ️

Server-proxy architecture

All DeliveryChat API calls must come from your backend, not directly from the browser. Your backend acts as a proxy: it injects the credentials and forwards requests to DeliveryChat.

Browser  →  Your Backend  →  DeliveryChat API

Authorization and X-App-Id are added by your backend only — they must never reach the browser.

Get chatting in 3 steps

Get your API key and App ID

Go to your dashboard → Applications → select your app → API Keys → Create API Key.

Copy both the API key and the App ID.

Create a conversation

Your backend generates a UUID for the visitor server-side and forwards the request to DeliveryChat with all three headers injected.

javascript

// Express / Node.js proxy route
app.post('/api/chat/conversations', async (req, res) => {
const visitorId = req.session.dcVisitorId; // server-managed UUID

const response = await fetch(
  'https://api.deliverychat.online/api/v1/conversations',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer dk_live_your_api_key',
      'X-App-Id': 'your-app-id',
      'X-Visitor-Id': visitorId,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ subject: req.body.subject }),
  }
);

const data = await response.json();
res.json(data);
});

Response from DeliveryChat:

Responsejson

{
"conversation": {
  "id": "conv-uuid",
  "status": "pending",
  "subject": "Help with my order",
  "participants": [
    { "userId": "550e8400-...", "role": "visitor" }
  ],
  "createdAt": "2025-01-15T10:30:00.000Z"
}
}

Send a message

Pass the conversation ID through your proxy endpoint — your backend injects all three headers before forwarding to DeliveryChat.

javascript

// Express / Node.js proxy route
app.post('/api/chat/conversations/:id/messages', async (req, res) => {
const visitorId = req.session.dcVisitorId; // server-managed UUID

const response = await fetch(
  `https://api.deliverychat.online/api/v1/conversations/${req.params.id}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer dk_live_your_api_key',
      'X-App-Id': 'your-app-id',
      'X-Visitor-Id': visitorId,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ content: req.body.content }),
  }
);

const data = await response.json();
res.json(data);
});

Response from DeliveryChat:

Responsejson

{
"message": {
  "id": "msg-uuid",
  "conversationId": "conv-uuid",
  "senderId": "550e8400-...",
  "content": "Hi, I need help with order #1234",
  "createdAt": "2025-01-15T10:30:05.000Z"
}
}

Your message is now visible to operators in the admin dashboard — and if they're online, they'll see it in real-time via WebSocket.

Required Headers

Every request to /api/v1/* must include all three headers, injected by your backend:

Your backend proxy — inject all three headersjavascript

const response = await fetch('https://api.deliverychat.online/api/v1/conversations', {
headers: {
  'Authorization': 'Bearer dk_live_your_api_key',
  'X-App-Id': 'your-app-id',
  'X-Visitor-Id': req.session.dcVisitorId,
},
});

Managing the Visitor ID

Visitors are your end users — the people chatting through your widget or API integration. They are distinct from the admins and operators who use the DeliveryChat dashboard.

The X-Visitor-Id is a UUID (v4) that uniquely identifies an end user. On the first request with a new visitor ID, DeliveryChat automatically creates an anonymous user account for that visitor.

Default path — anonymous visitors

Generate the UUID on your server the first time a visitor makes a request, store it in a server-side session, and reuse it on every subsequent request:

Server-side UUID generation and session storagejavascript

// Express example — generate once, reuse across requests
app.use((req, res, next) => {
if (!req.session.dcVisitorId) {
  req.session.dcVisitorId = crypto.randomUUID();
}
next();
});

⚠️

Session expiry resets the visitor identity

If the server-side session expires or the visitor clears their cookies, a new UUID will be generated on their next request. The visitor will no longer have access to their prior conversation history.

💡

Optional: persist identity for authenticated users

If your users have accounts, you can map your internal userId to a dcVisitorId in your own database. On login, look up the existing mapping — or create one if it doesn’t exist — and use that UUID for all API calls. This ensures conversation history survives logout, device changes, and session expiry.

javascript

// Look up or create a dcVisitorId for an authenticated user
async function getOrCreateVisitorId(userId, db) {
const existing = await db.query(
  'SELECT dc_visitor_id FROM user_visitor_ids WHERE user_id = $1',
  [userId]
);
if (existing.rows.length > 0) return existing.rows[0].dc_visitor_id;

const newId = crypto.randomUUID();
await db.query(
  'INSERT INTO user_visitor_ids (user_id, dc_visitor_id) VALUES ($1, $2)',
  [userId, newId]
);
return newId;
}

// Use on login / session start — then store in session for the request lifecycle
req.session.dcVisitorId = await getOrCreateVisitorId(req.user.id, db);

Pagination

List endpoints support offset-based pagination:

Parameter	Type	Default	Max	Description
`limit`	integer	20	100	Number of items per page
`offset`	integer	0	—	Number of items to skip

Example:


curl "https://api.deliverychat.online/api/v1/conversations?limit=10&offset=20" \
  -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 includes pagination metadata:


{
  "conversations": [...],
  "total": 42,
  "limit": 10,
  "offset": 20
}

Next Steps

Conversations

Create, list, and manage conversations

→

Messages

Send, edit, delete, and fetch messages

→

Message Formats

Rich text (Lexical), contentHtml, and rendering guidance

→

WebSocket

Real-time messaging via WebSocket

→

Errors & Rate Limiting

Error codes, HTTP statuses, and rate limits

→