API

Chat

Real-time conversation endpoints for owner-customer messaging and branch manager communication.

Booki includes an in-app chat system for direct communication between owners/branch managers and customers.

Role	Base path
Owner	`/api/v1/owner/chat`
Branch Manager	`/api/v1/branch/chat`

Owners can initiate or retrieve conversations. Branch managers can view and respond to conversations assigned to their branch. Both share the same message format.

Owner Chat — `/api/v1/owner/chat`

Used by: owner-booki-web-app · Role: owner
organizationId: From JWT token (automatically scoped to the owner's organization)

GET `/api/v1/owner/chat` — List Owner Conversations

Auth: Protected (Authorization: Bearer <accessToken>) · owner
Description: Fetch all conversations for the authenticated owner.

Request

GET /api/v1/owner/chat

Response (200 OK)

{
  "items": [
    {
      "_id": "conv_507f1f77bcf86cd799439001",
      "organizationId": "507f191e810c19729de860ea",
      "customerId": "507f1f77bcf86cd799439011",
      "customerName": "John Cruz",
      "lastMessage": "Is my booking confirmed?",
      "lastMessageAt": "2026-04-20T14:30:00Z",
      "unreadCount": 2
    }
  ],
  "pages": 1,
  "pageRange": "1-1 of 1"
}

cURL Example

curl -X GET http://localhost:4001/api/v1/owner/chat \
  -H "Authorization: Bearer OWNER_TOKEN"

POST `/api/v1/owner/chat` — Get or Create Conversation

Auth: Protected (Authorization: Bearer <accessToken>) · owner
Description: Retrieve an existing conversation with a customer, or create one if it doesn't exist yet.

Request

{
  "customerId": "507f1f77bcf86cd799439011"
}

Fields:

customerId (string, required): The customer's user ID (24-hex)

Response (200 OK)

{
  "_id": "conv_507f1f77bcf86cd799439001",
  "organizationId": "507f191e810c19729de860ea",
  "customerId": "507f1f77bcf86cd799439011",
  "customerName": "John Cruz",
  "createdAt": "2026-04-01T09:00:00Z"
}

cURL Example

curl -X POST http://localhost:4001/api/v1/owner/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OWNER_TOKEN" \
  -d '{"customerId": "507f1f77bcf86cd799439011"}'

GET `/api/v1/owner/chat/:conversationId/messages` — Get Messages

Auth: Protected (Authorization: Bearer <accessToken>) · owner
Description: Retrieve all messages in a specific conversation.

Request

GET /api/v1/owner/chat/conv_507f1f77bcf86cd799439001/messages

Response (200 OK)

{
  "items": [
    {
      "_id": "msg_507f1f77bcf86cd799440001",
      "conversationId": "conv_507f1f77bcf86cd799439001",
      "senderId": "507f1f77bcf86cd799439011",
      "senderType": "customer",
      "body": "Is my booking confirmed?",
      "createdAt": "2026-04-20T14:30:00Z",
      "readAt": null
    },
    {
      "_id": "msg_507f1f77bcf86cd799440002",
      "conversationId": "conv_507f1f77bcf86cd799439001",
      "senderId": "507f191e810c19729de860ea",
      "senderType": "owner",
      "body": "Yes, your booking for April 22 at 2PM is confirmed!",
      "createdAt": "2026-04-20T14:35:00Z",
      "readAt": "2026-04-20T14:36:00Z"
    }
  ]
}

cURL Example

curl -X GET "http://localhost:4001/api/v1/owner/chat/conv_507f1f77bcf86cd799439001/messages" \
  -H "Authorization: Bearer OWNER_TOKEN"

POST `/api/v1/owner/chat/:conversationId/messages` — Send Message

Auth: Protected (Authorization: Bearer <accessToken>) · owner
Description: Send a message to a customer in a conversation.

Request

{
  "body": "Your booking for April 22 at 2PM is confirmed!"
}

Fields:

body (string, required): Message text content

Response (201 Created)

{
  "_id": "msg_507f1f77bcf86cd799440002",
  "conversationId": "conv_507f1f77bcf86cd799439001",
  "senderId": "507f191e810c19729de860ea",
  "senderType": "owner",
  "body": "Your booking for April 22 at 2PM is confirmed!",
  "createdAt": "2026-04-20T14:35:00Z"
}

cURL Example

curl -X POST "http://localhost:4001/api/v1/owner/chat/conv_507f1f77bcf86cd799439001/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OWNER_TOKEN" \
  -d '{"body": "Your booking is confirmed!"}'

PATCH `/api/v1/owner/chat/:conversationId/read` — Mark Conversation as Read

Auth: Protected (Authorization: Bearer <accessToken>) · owner
Description: Mark all unread messages in a conversation as read.

Request

PATCH /api/v1/owner/chat/conv_507f1f77bcf86cd799439001/read

No request body required.

Response (200 OK)

{
  "message": "Conversation marked as read."
}

cURL Example

curl -X PATCH "http://localhost:4001/api/v1/owner/chat/conv_507f1f77bcf86cd799439001/read" \
  -H "Authorization: Bearer OWNER_TOKEN"

DELETE `/api/v1/owner/chat/:conversationId` — Delete Conversation

Auth: Protected (Authorization: Bearer <accessToken>) · owner
Description: Permanently delete a conversation and all its messages.

Request

DELETE /api/v1/owner/chat/conv_507f1f77bcf86cd799439001

Response (200 OK)

{
  "message": "Conversation deleted successfully."
}

cURL Example

curl -X DELETE "http://localhost:4001/api/v1/owner/chat/conv_507f1f77bcf86cd799439001" \
  -H "Authorization: Bearer OWNER_TOKEN"

Branch Manager Chat — `/api/v1/branch/chat`

Used by: owner-booki-web-app · Role: branch-manager
organizationId: From JWT token (scoped to the manager's branch)

Branch managers have a read/write view of conversations in their branch. They can view, reply, and mark messages as read, but cannot delete conversations or initiate new ones.

GET `/api/v1/branch/chat` — List Branch Conversations

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager
Description: Fetch all conversations for the authenticated branch manager's branch.

Request

GET /api/v1/branch/chat

Response (200 OK)

Same structure as owner conversations — returns paginated list of conversations with unreadCount.

cURL Example

curl -X GET http://localhost:4001/api/v1/branch/chat \
  -H "Authorization: Bearer BRANCH_MANAGER_TOKEN"

GET `/api/v1/branch/chat/:conversationId/messages` — Get Messages

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager
Description: Retrieve all messages in a specific conversation.

cURL Example

curl -X GET "http://localhost:4001/api/v1/branch/chat/conv_507f1f77bcf86cd799439001/messages" \
  -H "Authorization: Bearer BRANCH_MANAGER_TOKEN"

POST `/api/v1/branch/chat/:conversationId/messages` — Send Message

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager
Description: Send a message to a customer in a conversation.

Request

{
  "body": "Hi! Your appointment has been confirmed."
}

cURL Example

curl -X POST "http://localhost:4001/api/v1/branch/chat/conv_507f1f77bcf86cd799439001/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer BRANCH_MANAGER_TOKEN" \
  -d '{"body": "Hi! Your appointment has been confirmed."}'

PATCH `/api/v1/branch/chat/:conversationId/read` — Mark as Read

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager
Description: Mark all unread messages in a conversation as read.

cURL Example

curl -X PATCH "http://localhost:4001/api/v1/branch/chat/conv_507f1f77bcf86cd799439001/read" \
  -H "Authorization: Bearer BRANCH_MANAGER_TOKEN"

Users - Profile & Settings

User profile management, email updates, password changes, and payment preferences.

Maya Payments

Maya payment endpoints: checkout sessions, webhooks, and subscription flows.