tencent cloud


RESTful API Overview

Last updated: 2024-02-07 17:11:43
    RESTful APIs are HTTP management APIs that provide the app backend with a management entry. For more information about RESTful APIs that Chat supports, see RESTful API List. In addition to RESTful APIs, the app console also supports simple data management and one-to-one/group messaging. Developers can manage, check, and test data in the console. Even though RESTful APIs are less user-friendly, they provide powerful management capabilities. For security concerns, RESTful APIs are supported over HTTPS only.


    Before you call a RESTful API, complete the following operations:
    1. Create an app in the Chat console. For more information, see Creating and Upgrading an Application.
    2. Assign an admin account to the app. For more information, see the Configuring Account Admins section in Basic Configuration.
    To avoid unnecessary call errors, use the admin account to call a RESTful API.

    Calling Method

    Request URL

    The URL format of a RESTful API is as follows:
    The descriptions and values of parameters are as follows (parameter names and parameter values are case-sensitive):
    Request protocol
    The request protocol is HTTPS, and the request method is POST.
    Dedicated domain name
    China: console.tim.qq.com (backup: adminapi.my-imcloud.com) Singapore: adminapisgp.im.qcloud.com (backup: adminapisgp.my-imcloud.com) Seoul:adminapikr.im.qcloud.com (backup: adminapikr.my-imcloud.com) Frankfurt: adminapiger.im.qcloud.com (backup: adminapiger.my-imcloud.com) Mumbai: adminapiind.im.qcloud.com (backup: adminapiind.my-imcloud.com) Silicon Valley: adminapiusa.im.qcloud.com (backup: adminapiusa.my-imcloud.com)
    Jakarta: adminapiidn.im.qcloud.com (backup: adminapiidn.my-imcloud.com)
    Protocol version number
    Always v4.
    Internal service name. Different values of servicename correspond to different service types.
    Example:For v4/im_open_login_svc/account_import, im_open_login_svc is the servicename.For more information, see RESTful API List.
    Command word. This parameter is used with the servicename parameter to identify a specific service feature.
    Example:For v4/im_open_login_svc/account_import, account_import is the command.For more information, see RESTful API List.
    App ID obtained in the Chat console
    You can obtain the SDKAppID when applying for Chat SDK access.
    Username, which must be the app admin account when a RESTful API is called
    For more information, see the App Admin section in Login Authentication.
    Password that corresponds to the user name.
    For more information, see Generating UserSig.
    A parameter used to identify the current request
    A random 32-bit unsigned integer ranging from 0 to 4,294,967,295
    Request format
    Always json.
    When the app server calls a RESTful API, identifier must be the app admin account.
    The app can generate a UserSig for the admin account each time it calls a RESTful API or generate a fixed UserSig for reuse with period of validity.

    HTTP request body format

    RESTful APIs only support the POST method, and its request body is in JSON format. For more information about the request body format, see the detailed description of each API. Note that POST request bodies cannot be empty. Even when no information is required in a request body, the request body still needs to carry an empty JSON object ({}).

    HTTP return code

    The returned HTTP status code for RESTful APIs is always 200 unless a network error (such as error 502) occurs. The specific error code and error message are included in the HTTP response body.

    HTTP response body format

    The RESTful API response body is in the JSON format and has the following elements:
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0
    // Other RESTful API response content
    The response body must contain the ActionStatus, ErrorInfo, and ErrorCode fields. These three fields are described as follows:
    Request result. OK: Successful. FAIL: Failed. If the request fails, the cause of failure is displayed in the ErrorInfo field.
    Failure causes
    Error code. 0: Successful. Other values: Failed. For more information, see Error Codes.

    Sample Call

    The following example shows how to use the RESTful API to get all groups in an app.
    HTTPS request:
    POST /v4/group_open_http_svc/get_appid_group_list?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json HTTP/1.1
    Host: console.tim.qq.com
    Content-Length: 22
    "Limit": 2
    HTTPS response:
    HTTP/1.1 200 OK
    Server: nginx/1.7.10
    Date: Fri, 09 Oct 2015 02:59:55 GMT
    Content-Length: 156
    Connection: keep-alive
    Access-Control-Allow-Origin: *
    Access-Control-Allow-Headers: X-Requested-With
    Access-Control-Allow-Methods: POST
    "ActionStatus": "OK",
    "ErrorCode": 0,
    "GroupIdList": [
    "GroupId": "@TGS#1YTTZEAEG"
    "GroupId": "@TGS#1KVTZEAEZ"
    "TotalCount": 58530

    RESTful API Common Error Codes

    Error Code
    HTTP parsing error. Check the URL format of the HTTP request.
    JSON parsing error. Check the JSON format of the HTTP request.
    Account or signature error in the request URL or JSON request body.
    Account or signature error in the request URL or JSON request body.
    Invalid SDKAppID. Check the validity of SDKAppID.
    RESTful API call frequency limit exceeded. Reduce your request frequency.
    Service request timeout or HTTP request format error. Check and try again.
    Request resource error. Check the request URL.
    The request requires app admin permissions.
    SDKAppID request frequency exceeded. Reduce your request frequency.
    SDKAppID is required for RESTful APIs. Check the SDKAppID parameter in the URL.
    JSON parsing error in the HTTP response body.
    Account switching timeout.
    Invalid account type in the request body. Make sure that the account is in string format.
    The SDKAppID is disabled.
    The request is disabled.
    Too many requests. Try again later.
    Too many requests. Try again later.
    Your Standard edition has expired and was disabled. Log in to the purchase page and purchase it again. It will take effect in five minutes upon successful purchase.
    The source IP of the RESTful API call is invalid.


    The RESTful API request timed out and no response was received.

    1. The timeout period specified for the RESTful API in the Chat backend is three seconds. You need to specify a timeout period that is longer than three seconds.
    2. Run telnet console.tim.qq.com 443 to check whether the service port is accessible.
    3. Run curl -I https://console.tim.qq.com to check whether the status code is 200.
    4. Check whether the machine uses a private or public DNS server. If the machine uses a private DNS server, make sure that the DNS server egress is in the same region as the ISP to which the egress IP of the machine belongs.
    5. You are advised to use the "persistent connection+connection pool" mode.
    It is recommended that you use a RESTful API persistent connection to connect to the SDK. The reason is that it takes a long time to establish HTTPS non-persistent connections because each request causes TCP+TLS handshake overhead. For scenario where a standard HTTP library is used: for HTTP 1.0, the request header Connection: keep-alive needs to be specified; for HTTP 1.1, persistent connections are supported by default; for scenarios where HTTPS requests are encapsulated based on TCP, TCP connections can be reused to send and receive requests.
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support