Open Chat API

Real-time chat API for ShopChill — connecting shops and customers with full Socket.IO support, multi-tenant isolation, and webhook callbacks.

v2.0 Express Socket.IO MongoDB REST
Base URL
http://localhost:3000
Version
2.0.0
Auth
Access Token
Format
JSON
Base URL http://localhost:3000

Authentication

All protected endpoints require an Authorization header with your access token obtained from POST /v2/auth/register.

HTTP Header 
Authorization: your_access_token_here

Auth

v2
POST /v2/auth/register Create account & get access token Public ▶
Body Parameters
NameTypeRequiredDescription
username string required 3–50 chars, alphanumeric, - or _
email string required Valid email address
Request
JSON
{
  "username": "partner_shop",
  "email": "[email protected]"
}
Response
201 Created
400 / 409 Error
JSON
{
  "status": true,
  "code": "0000",
  "message": "User registered successfully",
  "data": {
    "username": "partner_shop",
    "email": "[email protected]",
    "access_token": "Xk9mP2...100chars",
    "created_at": "2024-05-14T10:00:00.000Z"
  }
}
JSON
{
  "status": false,
  "code": "1006",
  "message": "User already exists with this username or email"
}
POST /v2/auth/webhook Register webhook URL Auth ▶
Body Parameters
NameTypeRequiredDescription
webhook_url string required Valid HTTPS URL to receive chat events
Request
JSON
{
  "webhook_url": "https://your-server.com/webhook/chat"
}
Response · 200
JSON
{
  "status": true,
  "code": "0000",
  "message": "Webhook registered successfully",
  "data": { "webhook_url": "https://your-server.com/webhook/chat" }
}
GET /v2/auth/me Get current user info Auth ▶
Response · 200
JSON
{
  "status": true,
  "code": "0000",
  "message": "Current user info",
  "data": {
    "username": "partner_shop",
    "email": "[email protected]",
    "webhook_url": "https://your-server.com/webhook/chat",
    "created_at": "2024-05-14T10:00:00.000Z"
  }
}

Chat

v2
GET /v2/chats/rooms/:type/:id List chatrooms by shop or user Auth ▶
Path Parameters
NameTypeValuesDescription
type string shop user Filter by shop or user side
id string — shop_id or user_id
Response · 200
JSON
{
  "status": true,
  "code": "0000",
  "data": [
    {
      "_id": "664a1b2c3d4e5f6a7b8c9d0e",
      "username": "partner_shop",
      "shop_id": "shop_001",
      "user_id": "cust_123",
      "shop_name": "My Shop",
      "user_name": "John Doe",
      "message": "Hello!",
      "shop_unread": 0,
      "user_unread": 2,
      "lasted_message_at": "2024-05-14T10:30:00.000Z"
    }
  ]
}
GET /v2/chats/room/:room_id Get single chatroom details Auth ▶
Path Parameters
NameTypeRequiredDescription
room_id ObjectId required 24-char MongoDB ObjectId
Response · 200
JSON
{
  "status": true,
  "code": "0000",
  "message": "Chatroom details",
  "data": { /* full chatroom object */ }
}
GET /v2/chats/messages/:room_id Get all messages in a room Auth ▶
Path Parameters
NameTypeRequiredDescription
room_id ObjectId required Room must belong to your username
Response · 200
JSON
{
  "status": true,
  "code": "0000",
  "data": [
    {
      "_id": "664a...",
      "room_id": "664a1b2c3d4e5f6a7b8c9d0e",
      "sender_by": "shop",
      "sender_id": "shop_001",
      "sender_name": "My Shop",
      "message": "Hello! How can I help?",
      "type": "text",
      "created_at": "2024-05-14T10:30:00.000Z"
    }
  ]
}
POST /v2/chats/send Send a message to an existing room Auth ▶
Body Parameters
NameTypeRequiredDescription
room_idObjectIdrequiredTarget chatroom
sender_bystringrequiredshop or user
sender_idstringrequiredshop_id or user_id
sender_namestringrequiredDisplay name
messagestringrequired1–5000 characters
typestringoptionaltext image file audio — default: text
Request
JSON
{
  "room_id": "664a1b2c3d4e5f6a7b8c9d0e",
  "sender_by": "shop",
  "sender_id": "shop_001",
  "sender_name": "My Shop",
  "message": "Hello! How can I help you today?",
  "type": "text"
}
Response · 201
JSON
{
  "status": true,
  "code": "0000",
  "message": "Message sent successfully",
  "data": {
    "message_id": "664b2c3d4e5f6a7b8c9d0e1f",
    "room_id": "664a1b2c3d4e5f6a7b8c9d0e",
    "sender_by": "shop",
    "message": "Hello! How can I help you today?",
    "created_at": "2024-05-14T10:30:00.000Z"
  }
}
POST /v2/chats/reply Reply in an existing chatroom Auth ▶

Same parameters as POST /v2/chats/send. Both endpoints behave identically — /reply is provided as a semantic alias.

Body Parameters
NameTypeRequiredDescription
room_idObjectIdrequiredTarget chatroom
sender_bystringrequiredshop or user
sender_idstringrequiredshop_id or user_id
sender_namestringrequiredDisplay name
messagestringrequired1–5000 characters
typestringoptionaldefault: text
POST /v2/chats/mark-read Mark room as read & reset unread count Auth ▶
Body Parameters
NameTypeRequiredDescription
room_idObjectIdrequiredTarget chatroom
typestringrequiredshop or user
Request
JSON
{ "room_id": "664a1b2c3d4e5f6a7b8c9d0e", "type": "shop" }
Response · 200
JSON
{
  "status": true,
  "code": "0000",
  "message": "Room marked as read",
  "data": { "room_id": "664a...", "type": "shop", "unread_count": 0 }
}
POST /v2/chats/broadcast Send message to ALL customers of a shop Auth ▶
Body Parameters
NameTypeRequiredDescription
shop_idstringrequiredTarget shop
messagestringrequiredMessage to broadcast
sender_namestringoptionalFalls back to shop_name in DB
typestringoptionaldefault: text
Request
JSON
{
  "shop_id": "shop_001",
  "sender_name": "My Shop",
  "message": "🎉 Flash sale! 50% off today only!",
  "type": "text"
}
Response · 200
JSON
{
  "status": true,
  "code": "0000",
  "message": "Broadcast sent to 24 chatrooms",
  "data": {
    "broadcast_count": 24,
    "messages": [ /* array of sent message objects */ ]
  }
}

Notify

v2
POST /v2/notify/all Emit socket event to all connected clients Auth ▶
Body Parameters
NameTypeRequiredDescription
eventstringrequiredSocket event name
dataobjectrequiredPayload to send
Request
JSON
{
  "event": "shop:announcement",
  "data": { "message": "System maintenance in 5 mins" }
}
POST /v2/notify/user Emit socket event to specific socket ID Auth ▶
Body Parameters
NameTypeRequiredDescription
socket_idstringrequiredTarget socket ID
eventstringrequiredSocket event name
dataobjectrequiredPayload to send

Socket.IO Events

Client → Server (emit)
join-roomJoin a chatroom by room_id
leave-roomLeave a chatroom
sendSend message payload
onlineAnnounce user/shop online
offlineAnnounce user/shop offline
user-registerRegister user by user_id
Server → Client (listen)
{username}_{room_id}New message in room
{username}_{by}_{id}Directed message to user/shop
user:statusUser online/offline status
shop:statusShop online/offline status
user:readUser read confirmation
shop:readShop read confirmation

Error Codes

0000
HTTP 200 / 201
Success
1000
HTTP 400
Invalid or missing parameters
1004
HTTP 404
Resource not found
1005
HTTP 404
No matching records found
1006
HTTP 409
Already exists (duplicate)
4000
HTTP 400
Partner verification failed
4001
HTTP 401
Unauthorized — invalid or missing token
4003
HTTP 403
Forbidden — room does not belong to you
5000
HTTP 500
Internal server error

Legacy v1 Endpoints deprecated

These endpoints are kept for backward compatibility. New integrations should use the v2 API above.

MethodPathDescription
POST/autorize/createCreate user
POST/autorize/webhookRegister webhook
GET/getdt-chatrooms/:type/:idList chatrooms
GET/getdt-chatroom/:shop_id/:user_idSingle chatroom
GET/getdt-chats/:type/:room_idGet messages
GET/chats/readed/:type/:room_idMark as read
POST/chatrooms/updateUpdate room info
POST/chats/replyReply in room
POST/chats/broadcastBroadcast message
POST/api/notifyNotify all sockets
POST/api/notify-userNotify specific socket