OpenIMDocs

Type at least two characters to search titles and routes.

EN

Language

ENEnglishEnglish docs简中简体中文中文文档
Browse Platform API
Platform API

Prepare to use the API

Copy

Before calling the OpenIM Platform API, configure the base address, common request headers, authentication tokens, and request body conventions.

Note: Call Platform API endpoints from your backend and handle authentication, auditing, and errors there. Never expose an administrator token or management endpoint directly to a client.

Base URL

Use the API address of your OpenIM deployment as the base URL. Replace {API_ADDRESS} in endpoint examples with your OpenIM API gateway or server address.

{API_ADDRESS}

For example, POST {API_ADDRESS}/user/get_users sends a request to /user/get_users in the current environment. In production, allow only trusted backend services to access management endpoints.

Request headers

Most OpenIM management REST APIs use JSON request bodies. Unless an endpoint states otherwise, include these headers.

HeaderRequiredDescription
Content-TypeYesUse application/json; charset=utf-8 for JSON requests.
operationIDYesGlobally unique trace ID. Generate a new value for each request so that backend and OpenIM logs can be correlated.
tokenManagement endpointsAPP administrator token. A small number of bootstrap endpoints, such as user creation, may not require it; follow the endpoint page.

Authentication

Platform API endpoints must be called by a server. This can be your own business backend or the OpenIM Chat Server. The server stores the OpenIM API address, administrator account, and administrator credential (secret), and handles token acquisition, caching, renewal, and auditing.

Management API calls

First call Get an administrator token with the administrator account and secret. Include the returned APP administrator token in the token header when creating users or groups, sending server-side messages, importing relationships, or performing administrative operations.

Client login

After a user registers, signs in with a password, or completes third-party authentication, the client must not receive the administrator token. Once the business identity has been verified, your backend or the OpenIM Chat Server calls Get a user token and returns that IM token to the client for OpenIM SDK login.

A typical integration flow is:

  1. Configure the OpenIM API address, administrator account, and secret on your backend or OpenIM Chat Server.
  2. Call Get an administrator token.
  3. Use the administrator token to call user, group, message, relationship, and other management APIs.
  4. After a user signs in to your business system, call Get a user token and return the IM token to the client.

Request body

The documented OpenIM Platform API endpoints use POST requests to fixed paths and place business parameters in a JSON request body. Do not move pagination, user IDs, group IDs, or message fields into URL query parameters.

When a field value is itself a URL, such as an avatar, file, or object storage address, submit the original string as a JSON field.