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.

    Commissioning Tool

    Use the RESTful API online commissioning tool to commission this API.

    Reference

    Configuring Profiles (v4/profile/portrait_set).

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help