• UIKit
  • SDK
  • 서버 API
Chat/
서버 API/
RESTful 인터페이스/
서버 API
  • UserSig 생성
  • RESTful 인터페이스
    • RESTful 인터페이스 개요
    • RESTful 인터페이스 목록
    • 메시지 관련
      • 메시지 보내기
        • 단일 사용자에게 1대1 메시지 보내기
        • 여러 사용자에게 1대1 메시지 보내기
        • 그룹 내 일반 메시지 보내기
        • 그룹 내 시스템 메시지 보내기
        • 라이브 방송 그룹 브로드캐스트 메시지
        • 1대1 메시지 가져오기
        • 그룹 메시지 가져오기
      • 과거 메시지
        • 과거 1대1 메시지 수정
        • 과거 그룹 메시지 수정
        • 1대1 과거 메시지 풀링
        • 그룹 과거 메시지 풀링
      • 메시지 삭제
        • 지정 사용자가 보낸 메시지 삭제하기
      • 메시지 철회
        • 1대1 메시지 철회
        • 그룹 메시지 철회
      • 읽음 확인
        • 1대1 메시지 읽음 설정
        • 그룹 메시지 읽음 확인 상세정보 풀링
        • 그룹 메시지 읽음 확인 풀링
      • 메시지 확장
        • 1대1 메시지 확장 풀링
        • 1대1 메시지 확장 설정
        • 그룹 메시지 확장 풀링
        • 그룹 메시지 확장 설정
      • 모든 사용자에게 푸시하기
        • 전원 푸시 인터페이스
        • 모든 사용자에게 푸시하기
        • 애플리케이션 속성 이름 설정
        • 애플리케이션 속성 이름 획득
        • 사용자 속성 획득
        • 사용자 속성 설정
        • 사용자 속성 삭제
        • 사용자 태그 획득
        • 사용자 태그 추가
        • 사용자 태그 삭제
        • 사용자 모든 태그 삭제
    • 대화 관련
      • 대화 목록
        • 대화 목록 풀링
      • 읽지 않은 대화 수
        • 멤버의 읽지 않은 메시지 수 설정
        • 읽지 않은 1대1 메시지 수 조회
      • 대화 삭제
        • 대화 삭제
      • 대화 그룹 태그
        • 대화 그룹 데이터 생성
        • 대화 그룹 데이터 업데이트
        • 대화 그룹 데이터 삭제
        • 대화 마크 데이터 생성 또는 업데이트
        • 대화 그룹 마크 검색
        • 대화 그룹 마크 데이터 풀링
    • 그룹 관련
      • 그룹 관리
        • 애플리케이션 내 모든 그룹 획득
        • 그룹 생성
        • 그룹 해체
        • 사용자가 가입한 그룹 획득
      • 그룹 정보
        • 그룹 정보 획득
        • 그룹 정보 수정
        • 그룹 정보 가져오기
      • 그룹 멤버 관리
        • 그룹 멤버 추가
        • 그룹 멤버 삭제
        • 그룹 멤버 금지
        • 그룹 멤버 금지 해제
        • 일괄 음소거 및 음소거 취소
        • 음소거된 그룹 멤버 목록 획득
        • 그룹 오너 변경
        • 그룹 내 사용자의 신분 조회
        • 그룹 멤버 가져오기
      • 그룹 멤버 정보
        • 그룹 멤버 정보 획득
        • 그룹 멤버 정보 수정
      • 그룹 사용자 정의 속성
        • 그룹 사용자 정의 속성 획득
        • 그룹 사용자 정의 속성 수정
        • 그룹 사용자 정의 속성 비우기
        • 그룹 사용자 정의 속성 리셋
        • 그룹 사용자 정의 속성 삭제
      • 라이브 방송 그룹 관리
        • 라이브 방송 그룹 온라인 인원수 획득
        • 라이브 방송 온라인 멤버 목록 획득
        • 라이브 방송 그룹 멤버 마크 설정
        • 금지된 멤버 목록 획득
      • 커뮤니티 관리
        • 화제 생성
        • 화제 삭제
        • 화제 정보 획득
        • 화제 정보 수정
        • 화제 정보 가져오기
      • 그룹 카운터
        • 그룹 카운터 획득
        • 그룹 카운터 업데이트
        • 그룹 카운터 삭제
    • 사용자 관리
      • 계정 관리
        • 단일 계정 가져오기
        • 다중 계정 가져오기
        • 계정 삭제
        • 계정 조회
      • 사용자 정보
        • 정보 설정
        • 정보 풀링
      • 사용자 상태
        • 계정 로그인 상태 무효화
        • 계정 온라인 상태 조회
      • 친구 관리
        • 친구 추가
        • 친구 가져오기
        • 친구 업데이트
        • 친구 삭제
        • 모든 친구 삭제
        • 친구 인증
        • 친구 풀링
        • 지정 친구 풀링
      • 친구 목록
        • 목록 추가
        • 목록 삭제
        • 풀링 목록
      • 블록리스트
        • 사용자 블록리스트 추가
        • 사용자를 블록리스트에서 제거
        • 블록리스트 풀링
        • 블록리스트 내의 사용자 인증
    • 전원 음소거 관리
      • 전원 음소거 설정
      • 전원 음소거 조회
    • 운영 및 유지관리
      • 운영 및 유지관리 데이터 풀링
      • 최신 메시지 다운로드
      • 서버 IP 주소 획득
    • 챗봇
      • 챗봇 계정 풀링
      • 챗봇 계정 생성
      • 챗봇 계정 삭제
  • 트리거
    • 콜백 개요
    • 콜백 명령 목록
    • 콜백 운영 및 유지관리
      • 인터페이스 오버클록킹 알람 콜백
    • 온라인 상태 콜백
      • 상태 변경 콜백
    • 관계망 콜백
      • 정보 업데이트 후
      • 친구 추가 전
      • 친구 추가 응답 전
      • 친구 추가 후
      • 친구 삭제 후
      • 사용자를 블록리스트에 추가한 후
      • 사용자를 블록리스트에서 제거한 후
    • 1대1 메시지 콜백
      • 1대1 메시지 보내기 전
      • 1대1 메시지 보낸 후
      • 1대1 메시지 읽음 설정 후
      • 1대1 메시지 철회 후
    • 그룹 콜백
      • 그룹 생선 전
      • 그룹 생성 후
      • 그룹 가입 신청 전
      • 사용자를 그룹에 초대하기 전
      • 사용자 그룹 가입 후
      • 멤버 탈퇴 후
      • 그룹 메시지 보내기 전
      • 그룹 메시지 보낸 후
      • 그룹 만원 후
      • 그룹 해체 후
      • 그룹 정보 변경 후
      • 그룹 메시지 회수 후 콜백
      • 라이브 방송 그룹 멤버 온라인 및 오프라인 상태 콜백
      • 그룹 메시지 보내기 이상 콜백
      • 화제 생성 전
      • 화제 생성 후
      • 화제 삭제 후
      • 화제 정보 변경 콜백
      • 그룹 멤버 정보 변경 후 콜백
      • 그룹 속성 변경 후 콜백
      • 읽음 확인 후 콜백
      • 그룹 오너 변경 후 콜백
    • 콜백 상호 인증 구성 가이드
      • Apache 상호 인증 구성
      • Nginx 상호 인증 구성
    • 챗봇 콜백
      • 챗봇 1대1 메시지 사용자 정의 콜백
이 페이지는 현재 영어로만 제공되며 한국어 버전은 곧 제공될 예정입니다. 기다려 주셔서 감사드립니다.

RESTful 인터페이스 개요

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.

Prerequisites

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.
Caution
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:
https://xxxxxx/$ver/$servicename/$command?sdkappid=$SDKAppID&identifier=$identifier&usersig=$usersig&random=99999999&contenttype=json
The descriptions and values of parameters are as follows (parameter names and parameter values are case-sensitive):
Parameter
Description
Value
https
Request protocol
The request protocol is HTTPS, and the request method is POST.
xxxxxx
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)
Silicon Valley: adminapiusa.im.qcloud.com (backup: adminapiusa.my-imcloud.com)
Jakarta: adminapiidn.im.qcloud.com (backup: adminapiidn.my-imcloud.com)
ver
Protocol version number
Always v4.
servicename
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
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.
sdkappid
App ID obtained in the Chat console
You can obtain the SDKAppID when applying for Chat SDK access.
identifier
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.
usersig
Password that corresponds to the user name.
For more information, see Generating UserSig.
random
A parameter used to identify the current request
A random 32-bit unsigned integer ranging from 0 to 4,294,967,295
contenttype
Request format
Always json.
Note
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:
Field
Type
Description
ActionStatus
String
Request result. OK: Successful. FAIL: Failed. If the request fails, the cause of failure is displayed in the ErrorInfo field.
ErrorInfo
String
Failure causes
ErrorCode
Integer
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
Description
60002
HTTP parsing error. Check the URL format of the HTTP request.
60003
JSON parsing error. Check the JSON format of the HTTP request.
60004
Account or signature error in the request URL or JSON request body.
60005
Account or signature error in the request URL or JSON request body.
60006
Invalid SDKAppID. Check the validity of SDKAppID.
60007
RESTful API call frequency limit exceeded. Reduce your request frequency.
60008
Service request timeout or HTTP request format error. Check and try again.
60009
Request resource error. Check the request URL.
60010
The request requires app admin permissions.
60011
SDKAppID request frequency exceeded. Reduce your request frequency.
60012
SDKAppID is required for RESTful APIs. Check the SDKAppID parameter in the URL.
60013
JSON parsing error in the HTTP response body.
60014
Account switching timeout.
60015
Invalid account type in the request body. Make sure that the account is in string format.
60016
The SDKAppID is disabled.
60017
The request is disabled.
60018
Too many requests. Try again later.
60019
Too many requests. Try again later.
60020
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.
60021
The source IP of the RESTful API call is invalid.

FAQs

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.
Note
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.