Create User Group

Overview

Create a User Group. A user group is a virtual user that represents a team or organizational unit. After adding the group ID to the members or invitees list of a chat room, all members within the group can send and receive messages in that chat room.

Important: A User Group is a different concept from a Group Chat Room. A user group is a virtual user identity that can be added to a chat room as a single user, and all members within the group share access to that chat room.

API Endpoint

Create a User Group

Create a new user group in the system.

POST /admin/groups

Headers

Request Body

Example Request

JavaScript (axios)

const response = await axios.post(
  "https://your-app.imkit.io/admin/groups",
  {
    _id: "group_customer_service",
    nickname: "客服團隊",
    avatarUrl: "https://example.com/team-avatar.png",
    members: ["agent001", "agent002", "agent003"]
  },
  {
    headers: {
      "IM-API-KEY": process.env.IM_API_KEY,
      "Content-Type": "application/json; charset=utf-8"
    }
  }
);

cURL

curl -X POST "https://your-app.imkit.io/admin/groups" \
  -H "IM-API-KEY: your_api_key" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "_id": "group_customer_service",
    "nickname": "客服團隊",
    "avatarUrl": "https://example.com/team-avatar.png",
    "members": ["agent001", "agent002", "agent003"]
  }'

Response

Success Response (200 OK)

Example Response

{
  "RC": 0,
  "RM": "OK",
  "result": {
    "_id": "group_customer_service",
    "nickname": "客服團隊",
    "avatarUrl": "https://example.com/team-avatar.png",
    "members": ["agent001", "agent002", "agent003"],
    "createdAt": "2026-04-11T08:30:00.000Z",
    "updatedAt": "2026-04-11T08:30:00.000Z"
  }
}

Error Response

401 Unauthorized - Invalid API key

{
  "RC": 401,
  "RM": "Unauthorized",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}

400 Bad Request - Missing required parameters

{
  "RC": 400,
  "RM": "Bad Request",
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "nickname is required"
  }
}

409 Conflict - Group ID already exists

{
  "RC": 409,
  "RM": "Conflict",
  "error": {
    "code": "GROUP_ALREADY_EXISTS",
    "message": "A group with this ID already exists"
  }
}

Use Cases

Team Management

• Customer Service Team: Create a customer service group, add the group to customer service chat rooms, and team members can take turns handling customer messages
• Department Groups: Create groups for each department to conveniently manage chat room permissions on a department basis

Organizational Structure

• Project Teams: Create groups for projects so that all project members automatically gain access to related chat rooms
• Cross-Department Collaboration: Create cross-department groups to simplify member management for multi-user chat rooms

Notes

• User Group vs Group Chat Room: A user group is a virtual user representing a set of actual users. It is a completely different concept from a Group Chat Room
• Adding to Chat Rooms: After creating a group, the group ID must be added to the members or invitees list of a chat room for group members to access that chat room
• Shared Access: All members within the group share access to chat rooms joined under the group identity
• Member ID Validity: The Client IDs in the members array must be existing users in the system
• Server-Side Only: This endpoint requires IM-API-KEY authentication and is for server-side use only