Chat API Documentation

Our Chat API is a powerful third-party integration service that can add P2P chat and support ticket features to your website. No server-side authentication required - we handle everything!

✨ Key Features:

→ Bearer Token Auth: Secure JWT-based authentication
→ P2P Chat: Direct messaging between two users
→ Support Tickets: Customer support system
→ Admin Panel: Monitor all conversations
→ Role-Based Access: admin/superadmin/moderator/staff/user roles

Authentication (Bearer Token)

Summary:

Our API system ensures security using Bearer Tokens. You must send the token in the Authorization header of every request.

Token Retrieval Process:

Step 1: Create User

POST /api/v1/users

↓

Step 2: Get Chat Token

POST /api/v1/users/chat-token

↓

Step 3: Use token in Authorization header

Authorization: Bearer {chatToken}

Required Headers:

Header	Example	Required
Authorization	Bearer eyJhbGci...	✓
x-api-key	Your API Key	✓

User Management

Create User

POST /api/v1/users

Request Body:

{
  "resourceId": "site.com",
  "username": "john_doe",
  "email": "john@example.com",
  "role": "user",              // optional: admin/superadmin/moderator/staff/user
  "permissions": {             // optional (only for admin roles)
    "canSendMessage": true,
    "canReceiveMessage": true,
    "canDeleteMessage": true,
    "canEditMessage": false,
    "canArchiveConversation": true
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "john_doe",
    "email": "john@example.com",
    "role": "user",
    "resourceId": "site.com"
  }
}

Get Chat Token

Send user ID to get a Bearer token valid for 30 days

POST /api/v1/users/chat-token

Request Body:

{
  "userId": "507f1f77bcf86cd799439011"
}

Response:

{
  "success": true,
  "data": {
    "chatToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "username": "john_doe",
      "role": "user"
    }
  }
}

P2P Chat API

Direct chat system between two users

Create Conversation

POST /api/v1/p2p/conversations

// Request
{
  "otherParticipantId": "507f1f77bcf86cd799439012"
}

// Response
{
  "success": true,
  "data": {
    "id": "conversation_12345",
    "participantOne": "user_1",
    "participantTwo": "user_2",
    "status": "active"
  }
}

Send Message

POST /api/v1/p2p/conversations/:conversationId/messages

// Request
{
  "content": {
    "text": "How are you?"
  }
}

// Response
{
  "success": true,
  "data": {
    "id": "msg_123",
    "conversationId": "conv_123",
    "senderId": "user_1",
    "content": { "text": "..." },
    "isRead": false,
    "createdAt": "2026-02-22T10:00:00Z"
  }
}

View All Conversations

GET /api/v1/p2p/conversations?page=1&limit=20

// Response
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "conv_1",
        "participantOne": "user_1",
        "participantTwo": "user_2",
        "messageCount": 5,
        "unreadCountP1": 0,
        "unreadCountP2": 2,
        "status": "active"
      }
    ],
    "total": 10,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Read Messages and Unread Count

Mark as Read:

POST /api/v1/p2p/conversations/:conversationId/mark-as-read

Get Unread Count:

GET /api/v1/p2p/conversations/:conversationId/unread-count

Support Tickets API

Customer support and issue resolution system

Create Support Ticket

POST /api/v1/support/conversations

// Request
{
  "subject": "My payment is not working",
  "priority": "high",          // optional: low/medium/high
  "category": "billing",       // optional
  "initialMessage": "Need help..."
}

// Response
{
  "success": true,
  "data": {
    "id": "ticket_123",
    "subject": "...",
    "status": "open",
    "priority": "high",
    "messageCount": 1,
    "createdAt": "2026-02-22T10:00:00Z"
  }
}

Add Message

POST /api/v1/support/conversations/:ticketId/messages

Send support messages just like P2P

View Your Tickets

GET /api/v1/support/conversations?page=1&limit=20

Admin Panel API

Only for admin/superadmin/moderator/staff roles

⚠️ Limitation:

Users with "user" role cannot access admin panel API. Only admin and staff roles can use this application.

View All Conversations

All your P2P chats and Support tickets together

GET /api/v1/admin-panel/conversations?page=1&limit=20

Dashboard Stats

Total conversations, unread count etc.

GET /api/v1/admin-panel/stats

Specific User Conversations

View all conversations of any user (admin only)

GET /api/v1/admin-panel/users/:userId/conversations?page=1&limit=20

JavaScript/Fetch Examples

1️⃣ Create User

const response = await fetch('/api/v1/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    resourceId: 'site.com',
    username: 'john_doe',
    email: 'john@example.com'
  })
});
const { data } = await response.json();
const userId = data.id;

2️⃣ Get Chat Token

const tokenResponse = await fetch('/api/v1/users/chat-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId })
});
const { data: { chatToken } } = await tokenResponse.json();
localStorage.setItem('chatToken', chatToken);

3️⃣ Send P2P Message

const chatToken = localStorage.getItem('chatToken');
const response = await fetch(
  `/api/v1/p2p/conversations/{conversationId}/messages`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${chatToken}`,
      'x-api-key': 'your-api-key'
    },
    body: JSON.stringify({
      content: { text: 'How are you?' }
    })
  }
);
const { data } = await response.json();

Error Handling

Common Error Codes:

Code	Meaning	Solution
400	Bad Request	Check Request body
401	Unauthorized	Get Token again
403	Forbidden	Permission denied
500	Server Error	Check server logs

Error Response Format:

{
  "success": false,
  "message": "Detailed error message"
}