Server API Development Guide

This page is for quick integration, visit detailed documentation, or visit the Swagger page directly.

Getting started

Terminology introduction

• app_id

  app_idis the unique identity that Lanying IM generates for App when it is created and is of string type. Available from "Application Information" page in Console.

• api_endpoint

  api_endpointis the address of the API service where the app resides. Available from "Application Information" page in Console.

• access-token

  access-tokenis used for permission verification. You can generate access-token for App or select existing access-token from “Token Management” page in Console.

API profile

Lanying IM API service is based on the HTTPS security protocol, which ensures the security of data transfer when invoked. At the same time, Lanying IM API service provides access control, and it is necessary to obtain the uniqueaccess-tokento operate users, groups and other data under App legally. Involvedaccess-tokenshall be kept properly.

Before calling any Lanying IM API, please get parameter firstapi_endpoint、app_id、access-token. Parameterapp_id，access-tokenwill be used in the header of request, and unspecified request Content-Type type isapplication/json。

a generic example of the request that calls Lanying IM API (please replace the variable represented by{}with a specified value):

curl -X {METHOD} '{api_endpoint}/{URI}' \
-H "Content-Type: application/json" \
-H 'access-token: {access-token}' \
-H 'app_id: {app_id}' \

API classification

Lanying IM API is mainly divided into user API, friend API, group API, message API and push API.

• User API

  Users belong to a single App, which is the foundation of instant messaging. Only with users can we realize the functions of friends and groups. User data is divided into basic information and setting information. Basic information includes email address, mobile number, username and password. Setting information includes whether to download thumbnails and files automatically, whether to confirm the invitation to join group, etc. Generally speaking, the user API mainly involves the update of its basic information and user settings, and the related API starts with/user, followed by specific resources, ex. “GET /user/settings” to get user settings API.

• Friend API

  Friend is the relationship between users. In Lanying IM friendship design, users can set remarks for friends, set the notification method of friend messages, apply for adding friends, and blacklist a friend. Friend API provides friend information, friend application, friend list, friend blacklist and other related operations, and its API starts with/roster.

• Group API

  Groups enable multi-user communication. In Lanying IM design, the roles of group members are divided into group Owners, group Admins and group Members, and the authority levels are lowered in turn. The group Owners have all the permissions of the group, while the Admins have the permissions to operate group members and modify group information settings. According to group settings, ordinary group Members may have or not have the permissions to modify group information and invite users to join group. The functional design of group membership includes invitation to join group, application to join group, set group blacklist and group ban list. The main APIs include group data operations and group member operations. Group data operations mainly include create group, dissolve group, transfer group Owner, update group information and group settings, group announcement operation, group shared file operation; and group member operations mainly include invite user to join group, Admin process invitation, user apply to join group, user process application, set group blacklist, set group ban list, user quit group, kick user out of group, etc. APIs start with/group.

• Message API

  Message APIs are encapsulations of IM services designed to provide an easy way for messaging. Message APIs start with/message.

• PushAPI

  Push API to send Push notification to device，which starts with /push.

In general, the API requested to Lanying IM service will return an http code of 200 in case of a business error, and a Lanying IM custom error code will be returned in the response body. See the Error Code page for the specific meaning of error code.

Some of the key APIs are demonstrated with the following values, which should be replaced in your actual request.

• app_id: welovemaxim
• api_endpoint: https://api.maximtop.com
• access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg

User API

Register user

• API description

  Register a Lanying IM user for the specified App.

• Request description

  Http method: POST Resource path: /user/register/v2

• Parameter description
  • Header parameter

• Request Body parameter

• cURL request example

    curl -X POST 'https://api.maximtop.com/user/register/v2' \
    -H "Content-Type: application/json" \
    -H 'app_id: welovemaxim' \
    -d '{ "username": "test_user", "password": "asd"}'
  

• Returned result example

    {
        "code": 200,
        "data": {
            "user_id": 2302128618880,
            "auto_download": false,
            "group_confirm": false,
            "no_sounds": false,
            "no_push": false,
            "vibratory": false,
            "no_push_detail": false,
            "auth_mode": 0,
            "no_push_start_hour": 0,
            "no_push_end_hour": 0
        }
    }
  

Friend API

Add friend

• API description

  Add friend for specified user.

• Request description

  Http method: POST Resource path: /user/add_roster

• Parameter description
  • Header parameter

• Request Body parameter

• cURL request example

    curl -X POST 'https://api.maximtop.com/user/add_roster' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880' \
    -d '{ "list": [2199040544848, 2199040544992]}'
  

• Returned result example

    {
        "code": 200,
        "data": true
    }
  

Get friend list

• API description

  Get friend list of the specified user.

• Request description

  Http method: GET Resource path: /user/rosters

• Parameter description
  • Header parameter

• Request Body parameter

  None

  • cURL request example

  curl -X GET 'https://api.maximtop.com/user/rosters' \
  -H "Content-Type: application/json" \
  -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
  -H 'app_id: welovemaxim' \
  -H 'user_id: 2302128618880'
  

  • Returned result example

  {
      "code": 200,
      "data": [{
          "user_id": 2199040544848,
          "name": "a"
      }, {
          "user_id": 2199040544992,
          "name": "b"
      }]
  }
  

Group API

Create group

• API description

  Create a group with the specified user as group Owner.

• Request description

  Http method: POST Resource path: /group/create

• Parameter description
  • Header parameter

• Request Body parameter

• cURL request example

    curl -X POST 'https://api.maximtop.com/group/create' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880' \
    -d '{ "name": "g001", "description": "test-group"}'
  

• Returned result example

    {
        "code": 200,
        "data": {
            "name": "g001",
            "status": 0,
            "description": "test-group",
            "type": 0,
            "group_id": 2306414607729,
            "owner_id": 2302128618880,
            "created_at": 1569615417000,
            "updated_at": 1569615417000,
            "member_invite": true,
            "apply_approval": 1,
            "read_ack": false,
            "history_visible": false,
            "member_modify": false
        }
    }
  

Invite user to join group

• API description

  Invite user to join the group with the specified user as group Owner.

• Request description

  Http method: POST Resource path: /group/invite

• Parameter description
  • Header parameter

• Request Body parameter

• cURL request example

    curl -X POST 'https://api.maximtop.com/group/invite' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880' \
    -d '{ "group_id": 2306414607729, "user_list": [2199040544848, 2199040544992]}'
  

• Returned result example

    {
        "code": 200,
        "data": [{
            "result": "success",
            "user_id": 2199040544848
        }, {
            "result": "success",
            "user_id": 2199040544992
        }]
    }
  

Get group member list

• API description

  Get group member list, can be in pages. Pages are controlled by limit and cursor fields, limit for page size, cursor as the name suggest. cursor：If there is still member data left after fetching data on a certain page, it will return cursor field for fetching data from the next page of the cursor.

• Request description

  Http method: GET Resource path: /group/member_list

• Parameter description
  • Header parameter

• Query parameter

• cURL request example

    curl -X GET 'https://api.maximtop.com/group/member_list?group_id=2306414607729&limit=50' \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880'
  

• Returned result example

    {
        "code": 200,
        "data": [{
            "user_id": 2302128618880,
            "join_time": 1569615417000
        }, {
            "user_id": 2199040544848,
            "join_time": 1569615490000
        }, {
            "user_id": 2199040544992,
            "join_time": 1569615490000
        }],
        "version": 1569586735861
    }
  

Disband group

• API description

  Dissolve group.

• Request description

  Http method: DELETE Resource path: /group/destroy

• Parameter description
  • Header parameter

• cURL request example

    curl -X DELETE 'https://api.maximtop.com/group/destroy?group_id=2306414607729' \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880'
  

• Returned result example

    {
        "code": 200,
        "data": true
    }
  

Send message API

Admin send single chat text-message

• API description

  Send message to a specified destination, which can be sent in batches to groups or users. The specified destination is represented by targets field, list type and ids in list can only be one of user/group ids, and the both types cannot be mixed.

• Request description

  Http method: POST Resource path: /message/send

• Parameter description
  • Header parameter

• Request Body parameter

• cURL request example

    curl -X POST 'https://api.maximtop.com/message/send' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -d '{"targets":[2302128618880],"type":1,"content":"hello","content_type":0}'
  

• Returned result example

    {
        "code": 200,
        "data": true
    }
  

PushAPI

Admin SendPush notification

• API description

  Send a notification to a specific target, means PUSH to everyone in APP. You can also use Tag/Alias/PushToken/User ID to Push.

• Request description

  Http method: POST Resource path: /push/notify

• Parameter description：
  • Header parameter

• Request Body's main Parameter

• audience：Push target。Class type is string or JSONObject:

    "all", means push to all devices
    {"tag":["tag1","tag2"]} means push to devices labeled tag1 or tag2
    {"alias":["alias1","alias2"]} means push to devices with alias1 or alias2
    {"user_id":[111,222]} means push to devices with user ID 111 or 222
    {"push_token":["push_token1","push_token2"]} means push to devices with PushToken push_token1 or push_token2
    List length cannot exceed 500 when pushed with tag/alias/user ID/pushToken
  

• message:Message body pushed, the main Field is as follows，see API Details for full Field

• cURL request example

    Push text to all devices belong to APP：
    curl -X POST 'https://api.maximtop.com/push/notify' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -d '{"audience": "all","message": {"type": "text","title": "this is push title","body": "this is push body"}}'
  

    PushImage to all devices with push_token as their token1 or token2:
    curl -X POST 'https://api.maximtop.com/push/notify' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -d '{"audience": {"push_token":["token1","token2"]},"message": {"type": "image","title": "this is push title","body": "this is push body","attachment_url": "https://xxx.com/images/1.jpg"}}'
  

    Push pass-through Message to all devices tagged as beijing or shanghai，pass-through Message will no display on Notification bar:
    curl -X POST 'https://api.maximtop.com/push/notify' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -d '{"audience": {"tag":["beijing","shanghai"]},"message": {"type": "cmd","title": "this is push title","body": "this is push body","ext": {"key1": 12345, "key2": "xxx" }}}'
  

• Returned result example

    {
        "code": 200,
        "data": true
    }
  

Appendix

Error code description

• 1xxxx indicates an issue related to user/friend system
• 2xxxx indicates an issue related to group system
• 3xxxx indicates an issue related to license