Basic Integration

Overview

This guide walks you through the basic integration process with IMKIT. After completing the “Quick Start” to obtain your API Key and Chat Server URL, you can follow these three steps to quickly create users, create a chat room, and start your first conversation.

Prerequisites

Please confirm you have completed the following preparations:

Item	Description	How to Obtain
API Key	Backend API authentication key (`IM-API-KEY`)	IMKIT Dashboard
Client Key	Client-side connection key (`IM-CLIENT-KEY`)	IMKIT Dashboard
Chat Server URL	Your Chat Server URL	IMKIT Dashboard

Step 1: Create Users

Create IMKIT users for the users in your system via the API and obtain access tokens.

POST /admin/clients

Headers

Parameter	Type	Required	Description
`IM-API-KEY`	string	✅	Your platform API key
`Content-Type`	string	✅	`application/json; charset=utf-8`

Create User A

const axios = require("axios");
 
const BASE_URL = "https://your-app.imkit.io";
const API_KEY = process.env.IM_API_KEY;
 
// Create User A and obtain Token
const userA = await axios.post(
  `${BASE_URL}/admin/clients`,
  {
    _id: "user-a",
    nickname: "Alice",
    avatarUrl: "https://example.com/alice.jpg",
    issueAccessToken: true,
  },
  {
    headers: {
      "IM-API-KEY": API_KEY,
      "Content-Type": "application/json; charset=utf-8",
    },
  }
);
 
const tokenA = userA.data.result.token;
console.log("User A Token:", tokenA);

Create User B

// Create User B and obtain Token
const userB = await axios.post(
  `${BASE_URL}/admin/clients`,
  {
    _id: "user-b",
    nickname: "Bob",
    avatarUrl: "https://example.com/bob.jpg",
    issueAccessToken: true,
  },
  {
    headers: {
      "IM-API-KEY": API_KEY,
      "Content-Type": "application/json; charset=utf-8",
    },
  }
);
 
const tokenB = userB.data.result.token;
console.log("User B Token:", tokenB);

Example Response

{
  "RC": 0,
  "RM": "OK",
  "result": {
    "_id": "user-a",
    "nickname": "Alice",
    "avatarUrl": "https://example.com/alice.jpg",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expirationDate": "2026-04-17T00:00:00.000Z",
    "lastLoginTimeMS": 1712700000000
  }
}

Please securely pass the obtained Token to the frontend for use with the SDK or Web URL.

Step 2: Create a Chat Room

Create a chat room and add User A and User B as members.

POST /rooms/

Headers

Parameter	Type	Required	Description
`IM-API-KEY`	string	✅	Your platform API key
`Content-Type`	string	✅	`application/json; charset=utf-8`

Example Request

// Create a one-on-one chat room
const room = await axios.post(
  `${BASE_URL}/rooms/`,
  {
    roomType: "direct",
    members: ["user-a", "user-b"],
  },
  {
    headers: {
      "IM-API-KEY": API_KEY,
      "Content-Type": "application/json; charset=utf-8",
    },
  }
);
 
const roomId = room.data.result._id;
console.log("Chat Room ID:", roomId);

To create a group chat room, change roomType to "group" and add more members:

// Create a group chat room
const groupRoom = await axios.post(
  `${BASE_URL}/rooms/`,
  {
    name: "Project Discussion Group",
    roomType: "group",
    members: ["user-a", "user-b", "user-c"],
  },
  {
    headers: {
      "IM-API-KEY": API_KEY,
      "Content-Type": "application/json; charset=utf-8",
    },
  }
);

Example Response

{
  "RC": 0,
  "RM": "OK",
  "result": {
    "_id": "6073a1b2c3d4e5f6a7b8c9d0",
    "roomType": "direct",
    "members": ["user-a", "user-b"],
    "status": 1,
    "createdTimeMS": 1712700000000
  }
}

Step 3: Start a Conversation

After the chat room is created, pass the user’s Token into the Web URL to start a conversation.

Using the Web SDK

Embed the IMKIT Web SDK in your web page and initialize it with the user’s Token:

<div id="imkit-container"></div>
<script src="https://cdn.imkit.io/sdk/web/latest/imkit.min.js"></script>
<script>
  window.IMKitUI.init({
    domain: "https://your-app.imkit.io",
    clientKey: "YOUR_CLIENT_KEY",
    token: "USER_TOKEN",
  });
</script>

Using Web URL

If you have obtained the Web URL provided by IMKIT, you can directly pass the user Token as a parameter:

https://your-app.imkit.io/chat?token=USER_TOKEN

You can embed this URL in your application via an iframe or direct navigation.

Complete Integration Flow

Below is a complete backend integration example covering the full process of creating two users and one chat room:

const axios = require("axios");
 
const BASE_URL = "https://your-app.imkit.io";
const API_KEY = process.env.IM_API_KEY;
 
const headers = {
  "IM-API-KEY": API_KEY,
  "Content-Type": "application/json; charset=utf-8",
};
 
async function setupChat() {
  // 1. Create User A
  const userA = await axios.post(
    `${BASE_URL}/admin/clients`,
    { _id: "user-a", nickname: "Alice", issueAccessToken: true },
    { headers }
  );
 
  // 2. Create User B
  const userB = await axios.post(
    `${BASE_URL}/admin/clients`,
    { _id: "user-b", nickname: "Bob", issueAccessToken: true },
    { headers }
  );
 
  // 3. Create Chat Room
  const room = await axios.post(
    `${BASE_URL}/rooms/`,
    { roomType: "direct", members: ["user-a", "user-b"] },
    { headers }
  );
 
  return {
    tokenA: userA.data.result.token,
    tokenB: userB.data.result.token,
    roomId: room.data.result._id,
  };
}
 
setupChat().then((result) => {
  console.log("Integration complete!");
  console.log("User A Token:", result.tokenA);
  console.log("User B Token:", result.tokenB);
  console.log("Chat Room ID:", result.roomId);
});

Next Steps

After completing the basic integration, you can explore further:

Authentication — Learn the detailed usage of API Key and Client Key
User Management — More user management features
Chat Room Management — Advanced chat room operations
Messaging — Send and manage messages via API
Webhook — Receive chat room events for automated workflows

Quick Start API Key