Skip to main content

Server Integration Overview

You can integrate the IM service on your application server (App Server) to build a comprehensive and rich business experience.

The IM Server API supports sending requests from your application's server (App Server) to the IM server, such as connecting app users to the IM service (Register User) and sending messages. Some service management interfaces and advanced features are only available in the IM Server API, such as System Notification, Broadcast to Online Users, Create Group, Block User, etc. For a detailed description of the API's full functionality, debugging tools, and considerations, please refer to the API List.

The IM service provides multiple server callbacks to synchronize certain data and statuses from the IM service to your designated backend service, such as user online status changes and chatroom status changes. You can control whether messages are sent to recipients through parameters in the callback response body. All server callbacks need to be configured with callback URLs and enabled separately in the Console. For more details, see Server Callbacks.

Interaction Diagram​

tip

All Server API interfaces must be called through the App Server. Never call Server API interfaces directly from the client to avoid issues such as App Secret leakage.

(width=500)

This article will use Register User as an example to help you quickly understand how to use the Server API interface.

tip

One of the main functions of the IM Server API is Register User. You must call this interface from the App backend to exchange the App's user ID for a Token, allowing the App user to connect to the IM service.

Prerequisites​

Before you start calling the Server API interfaces, ensure that:

  • You have created an application in the Console and obtained a valid App Key / App Secret for the development environment or production environment.
  • You have prepared your client and set up relevant business scenarios. For example, after calling the Server API interface Register User, you can use the obtained Token to establish an IM connection on your client.
  • It is recommended that you familiarize yourself with the Default Behavior and Configuration of the IM Server API in advance to ensure a smoother integration experience.

Calling Methods​

After creating an application in the Console, you can create IM Server API requests. It is recommended to use the HTTPS protocol to send requests for traffic encryption.

Each user using the IM service needs to hold an authentication token (Token) from the IM service. Here’s an example request to obtain a Token:

POST /user/getToken.json HTTP/1.1
Host: api.rong-api.com
App-Key: your-own-app-key
Nonce: 14314
Timestamp: 1408710653000
Signature: 30be0bbca9c9b2e27578701e9fda2358a814c88f
Content-Type: application/x-www-form-urlencoded
Content-Length: 78

userId=jlk456j5&name=Ironman&portraitUri=http%3A%2F%2Fabc.com%2Fmyportrait.jpg

When building an API request, pay attention to the following:

  • HTTP Method: All interfaces in the current version of the IM Server API use POST requests.
  • Host: The domain name of the IM Server API. The IM service provides two domain names for domestic applications. It is recommended that you implement a domain name switching mechanism. For more details, see Server API Domain.
  • App-Key: The App Key for the development or production environment of your application. You can create and manage applications and obtain the App Key in the Console.
  • Nonce: A random number, no more than 18 characters.
  • Timestamp: A timestamp in milliseconds from January 1, 1970, 00:00:00 UTC.
  • Signature: This needs to be calculated. Log in to the Console, obtain the App Secret corresponding to your application/environment’s App Key (i.e., the App-Key field above), concatenate App Secret + Nonce + Timestamp into a string, and perform an SHA1 hash calculation. For more details, see API Request Signature.
  • Content-Type: Generally application/x-www-form-urlencoded, with some exceptions. For more details, see Data Format.

After sending the request, the response data in application/json format will be returned, including:

  • Status Code: An HTTP status code indicating success or failure. 200 indicates a successful request. For detailed information about HTTP error codes, please refer to Status Codes.
  • Result Data: The data or result of the operation you requested. For some operations, the response message may be empty.

Data Format​

The IM Server API interfaces generally use the application/x-www-form-urlencoded format to send data.

Please note that the following interfaces use the application/json format to send data:

  • Send One-to-One Chat Template Message: /message/private/publish_template.json
  • Send System Notification Template Message to a Single User: /message/system/publish_template.json
  • Send Ultra Group Message: /message/ultragroup/publish.json
  • Set Tag for a Single User: /user/tag/set.json
  • Set Tags for Multiple Users: /user/tag/batch/set.json
  • Push-only Notification: /push.json
  • Push-only Notification for a Single User: /push/user.json
Last updated on