Documentation

Recent Pages

Pulling Profiles

Last updated: 2020-07-02 16:21:02

Feature Description

This API is used to pull profile fields of friends and other users.
This API can pull standard profile fields and custom profile fields.
We recommend that profile fields of no more than 100 users are pulled each time to prevent a response packet failure due to excessive data.
Ensure that all accounts in the request are imported into the IM console. Otherwise, an error will be displayed at the IM backend.

Call Description

Sample request URL

https://console.tim.qq.com/v4/profile/portrait_get?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

Request parameters

The following table only describes the parameters that are modified when this API is called. For more information about other parameters, please see RESTful API Overview.

Parameter	Description
v4/profile/portrait_get	The request API.
sdkappid	The SDKAppID assigned by the IM console when an application is created.
identifier	The value must be the app admin account. For more information, please see App Admin.
usersig	The signature generated by the app admin account. For more information about the operation, please see Generating UserSig.
random	A random 32-bit unsigned integer ranging from 0 to 4294967295.

Maximum call frequency

200 times/second

Sample request packet

Read a profile field of a user.

{
  "To_Account":["id1"],
  "TagList":
  [
      "Tag_Profile_IM_Nick"
  ]
}

Read multiple profile fields of a user.

{
  "To_Account":["id1"],
  "TagList":
  [
      "Tag_Profile_IM_Nick",
      "Tag_Profile_IM_AllowType",
      "Tag_Profile_IM_SelfSignature",
      "Tag_Profile_Custom_Test"
  ]
}

Read a profile field of multiple users.

{
  "To_Account":["id1","id2","id3"],
  "TagList":
  [
      "Tag_Profile_IM_Nick"
  ]
}

Read multiple profile fields of multiple users.

{
  "To_Account":["id1","id2","id3","id4"],
  "TagList":
  [
      "Tag_Profile_IM_Nick",
      "Tag_Profile_IM_AllowType",
      "Tag_Profile_IM_SelfSignature",
      "Tag_Profile_Custom_Test"
  ]
}

Request packet fields

Field	Type	Property	Description
To_Account	Array	Required	The UserID of users whose profile fields need to be pulled. Note: profile fields of no more than 100 users can be pulled each time to prevent a response packet failure due to excessive data.
TagList	Array	Required	The tag of a profile field to be pulled. Supported fields include: 1. Standard profile fields. For more information, please see Standard Profile Fields. 2. Custom profile fields. For more information, please see Custom profile fields.

Sample response packet body

Read a profile field of a user.

{
  "UserProfileItem":
  [
      {
          "To_Account":"id1",
          "ProfileItem":
          [
              {
                  "Tag":"Tag_Profile_IM_Nick",
                  "Value":"NickNameTest1"
              }
          ],
          "ResultCode":0,
          "ResultInfo":""
      }
  ],
  "ActionStatus":"OK",
  "ErrorCode":0,
  "ErrorInfo":"",
  "ErrorDisplay":""
}

Read multiple profile fields of a user.

{
  "UserProfileItem":
  [
      {
          "To_Account":"id1",
          "ProfileItem":
          [
              {
                  "Tag":"Tag_Profile_IM_Nick",
                  "Value":"NickNameTest1"
              },
              {
                  "Tag":"Tag_Profile_IM_AllowType",
                  "Value":"AllowType_Type_NeedConfirm"
              },
              {
                  "Tag":"Tag_Profile_IM_SelfSignature",
                  "Value":"I'm Test1"
              },
              {
                  "Tag":"Tag_Profile_Custom_Test",
                  "Value":"Custom Data1"
              }
          ],
          "ResultCode":0,
          "ResultInfo":""
      }
  ],
  "ActionStatus":"OK",
  "ErrorCode":0,
  "ErrorInfo":"",
  "ErrorDisplay":""
}

Read a profile field of multiple users.

{
  "UserProfileItem":
  [
      {
          "To_Account":"id1",
          "ProfileItem":
          [
              {
                  "Tag":"Tag_Profile_IM_Nick",
                  "Value":"NickNameTest1"
              }
          ],
          "ResultCode":0,
          "ResultInfo":""
      },
      {
          "To_Account":"id2",
          "ProfileItem":
          [
              {
                  "Tag":"Tag_Profile_IM_Nick",
                  "Value":"NickNameTest2"
              }
          ],
          "ResultCode":0,
          "ResultInfo":""
      },
      {
          "To_Account":"id3",
          "ProfileItem":
          [
              {
                  "Tag":"Tag_Profile_IM_Nick",
                  "Value":"NickNameTest3"
              }
          ],
          "ResultCode":0,
          "ResultInfo":""
      }
  ],
  "ActionStatus":"OK",
  "ErrorCode":0,
  "ErrorInfo":"",
  "ErrorDisplay":""
}

Read multiple profile fields of multiple users.

{
  "UserProfileItem":
  [
      {
          "To_Account":"id1",
          "ProfileItem":
          [
              {
                  "Tag":"Tag_Profile_IM_Nick",
                  "Value":"NickNameTest1"
              },
              {
                  "Tag":"Tag_Profile_IM_AllowType",
                  "Value":"AllowType_Type_NeedConfirm"
              },
              {
                  "Tag":"Tag_Profile_IM_SelfSignature",
                  "Value":"I'm Test1"
              },
              {
                  "Tag":"Tag_Profile_Custom_Test",
                  "Value":"Custom Data1"
              }
          ],
          "ResultCode":0,
          "ResultInfo":""
      },
      {
          "To_Account":"id2",
          "ProfileItem":
          [
              {
                  "Tag":"Tag_Profile_IM_Nick",
                  "Value":"NickNameTest2"
              },
              {
                  "Tag":"Tag_Profile_IM_AllowType",
                  "Value":"AllowType_Type_DenyAny"
              },
              {
                  "Tag":"Tag_Profile_IM_SelfSignature",
                  "Value":"I'm Test2"
              },
              {
                  "Tag":"Tag_Profile_Custom_Test",
                  "Value":"Custom Data2"
              }
          ],
          "ResultCode":0,
          "ResultInfo":""
      },
      {
          "To_Account":"id3",
          "ProfileItem":
          [
              {
                  "Tag":"Tag_Profile_IM_Nick",
                  "Value":"NickNameTest3"
              },
              {
                  "Tag":"Tag_Profile_IM_AllowType",
                  "Value":"AllowType_Type_AllowAny"
              },
              {
                  "Tag":"Tag_Profile_IM_SelfSignature",
                  "Value":"I'm Test3"
              },
              {
                  "Tag":"Tag_Profile_Custom_Test",
                  "Value":"Custom Data3"
              }
          ],
          "ResultCode":0,
          "ResultInfo":""
      },
      {
          "To_Account":"id4",
          "ResultCode":40006,
          "ResultInfo":"Err_Profile_PortraitGet_Read_Custom_Data_Fail"
      }
  ],
  "Fail_Account":["id4"],
  "ActionStatus":"OK",
  "ErrorCode":0,
  "ErrorInfo":"",
  "ErrorDisplay":""
}

Response fields

Field	Type	Description
UserProfileItem	Array	Structured information of the returned user profile.
To_Account	String	UserID of a user.
ProfileItem	Array	The returned user profile object array. Each object in the array contains a tag and a value.
Tag	String	The returned profile object name. The profile objects include: 1. Standard profile fields. For more information, please see Standard Profile Fields 2. Custom profile fields. For more information, please see Custom Profile Fields.
Value	uint64_t/string/bytes	The value of a pulled profile object. For more information, please see Profile Fields.
ResultCode	Integer	The processing result of To_Account. 0: succeeded. Other values: failed.
ResultInfo	String	The error description of To_Account. If processing is successful, the field is null.
Fail_Account	Array	A list of UserIDs that failed to be processed. This field is returned only when there is at least one failed user.
ActionStatus	String	The request processing result. OK: succeeded. FAIL: failed.
ErrorCode	Integer	The error code. 0: succeeded. Other values: failed.
ErrorInfo	String	The error information.
ErrorDisplay	String	Detailed information displayed on the client.

Error Codes

Unless a network error (such as error 502) occurs, the HTTP return code for this API is always 200. ErrorCode and ErrorInfo in the response packet represent the actual error code and error information.
For public error codes 60000 to 79999, please see Error Codes.
The following table describes the error codes specific to this API.

Error Code	Description
40001	Request parameter error. Check the request parameter based on the error description.
40002	Request parameter error. To_Account is not specified.
40003	The requested user account does not exist.
40004	The request requires app admin permissions.
40006	Internal server error. Please try again later.
40007	You have no permission to read profile fields. For more information, please see Profile Fields.
40009	The tag of a profile field does not exist.