User Profile via Web
Back

From WeChat Official Account Admin Platform
Jump to: navigation, search

Developers can obtain a user's profile information or execute service logic via this API when a user visits a third-party web page for an official account on WeChat.

Web-based Authorization Callback Domain Name

1. Before requesting a user's web-based authorization, the developer should configure an authorization callback domain name on the WeChat Official Account Admin Platform ( Developer Center > API Privileges > Webpage Account > Obtain the user's basic information > Edit ). Note that a domain name (string type), not a URL should be entered, so do not add http:// .
2. The callback domain name must be set to a complete domain name. For example, if the domain name is www.qq.com, after configuration, URLs under this domain name including http://www.qq.com/music.html and http://www.qq.com/login.html would be able to support WeChat OAuth2.0-based authentication. However, http://pay.qq.com, http://music.qq.com, and http://qq.com would not be supported for web-based authentication.
3. If an official account authorizes a third-party to manage web-based authentication, the official account does not need any setting.

Scope Setting

1. If scope is set to snsapi_base, only a user's OpenID may be obtained. The authorization will occur silently and redirection page occurs automatically. In this case, users will be automatically redirected to the configured callback page (business page).
2. If scope is set to snsapi_userinfo, a user's basic information may be obtained. However, users must first confirm their authorization. After users give permission, developers can obtain the user's basic information.
3. Note that the "User Profile" API obtains a user's profile information based on their OpenID only after the user and the official account have exchanged messages or the user has followed the official account. The "User Profile" API and many other API calls may only be called after a user has followed the official account. 

Web Authorization Access Token and Common Access Token

1. Web authorization done via the OAuth 2.0 protocol. After a user has given permission, the official account will receive a special API calling certificate (web authorization access_token). Based on this access token, the official account may call APIs and obtain the user's basic information.
2. If other APIs are to be called, a common access_token must be first obtained by calling the "Access Token" API on Basic Support.

Silent Authorization

1. Silent authorization is used when the authentication scope is set to snsapi_base. Users will be unaffected by silent authorization.
2. When users have followed an official account and enter the authorization webpage of this official account via its chat window or custom menu, silent authorization will prevail over manual authorization even when the authorization scope is set to snsapi_userinfo.

Web-based authorization is as follows:

1. Direct users to a web-based authorization page to obtain a user's authorization. Authorization results in a code.
2. After user authorization is provided, receive a web authorization access token based on the code (not the one mentioned in the Basic Support pages).
3. Update the web authorization access token if required. 
4. Obtain user information based on the web authorization access token and OpenID. 

Contents

Get a code

Ensure that the official account has the permissions for the authorization scope (the scope parameter). The default scope parameter includes snsapi_base and snsapi_userinfo when a service account has advanced APIs. Then guide the user to open the link below:

https://open.weixin.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect

If you cannot open this link, check whether the parameters are correct and you have the permission for the scope parameter.

Two links are provided below for your reference (please open them in your WeChat client)

Scope = snsapi_base
https://open.weixin.qq.com/connect/oauth2/authorize?appid=wx520c15f417810387&redirect_uri=http%3A%2F%2Fchong.qq.com%2Fphp%2Findex.php%3Fd%3D%26c%3DwxAdapter%26m%3DmobileDeal%26showwxpaytitle%3D1%26vb2ctag%3D4_2030_5_1194_60&response_type=code&scope=snsapi_base&state=123#wechat_redirect
Scope = snsapi_userinfo
https://open.weixin.qq.com/connect/oauth2/authorize?appid=wxf0e81c3bee622d60&redirect_uri=http%3A%2F%2Fnba.bluewebgame.com%2Foauth_response.php&response_type=code&scope=snsapi_userinfo&state=STATE#wechat_redirect

Parameter Description

Parameter Required Description
appid Yes The unique ID of the official account
redirect_uri Yes Callback redirection URL after authorization
response_type Yes Code
scope Yes App authorization scope. snsapi_base: No authorization page is prompted, redirect occurs, and only the user OpenID can be obtained.

snsapi_userinfo: prompts the authorization page, enabling you to obtain a user's nickname, gender and city via the OpenID. For a non-follower, you can also obtain information if the user gives permission.

state No This parameter is included in the link after redirection. The developer can set a random value.
#wechat_redirect No This parameter can be left empty when opening the link in WeChat. This parameter is required for 302 redirection.

An example of the authorization page when the scope parameter is equal to the snsapi_userinfo is as follows:

3.jpg

If the user gives authorization permission, the page redirects to redirect_uri/?code=CODE&state=STATE. Otherwise, only the state parameter is included in the URL, such as redirect_uri?state=STATE.

Code description: 
The code is the certificate for obtaining the access token and is therefore different for each authorization. A code can only be used once and expires after 5 minutes if it is not used.

Obtain access token by the code

Note that the access token here for web authorization obtained by the code is not the one mentioned in the Basis Support pages. If the scope parameter is snsapi_base, both access token and OpenID are obtained in this step.

Request Description

Request the following link to obtain access token after you receive the code:
https://api.wechat.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code


Parameter Description

Parameter Required Description
appid Yes The unique ID of the official account
secret Yes The appsecret of the official account
code Yes The code parameter obtained in the first step
grant_type Yes authorization_code

Return Description

An example of a successful JSON response is as follows:

{
   "access_token":"ACCESS_TOKEN",
   "expires_in":7200,
   "refresh_token":"REFRESH_TOKEN",
   "openid":"OPENID",
   "scope":"SCOPE"
}


Parameter Description
access_token The certificate for calling the web authorization API. Note: this access token is not the one mentioned in the Basis Support pages.
expires_in The certificate validity time (unit: second)
refresh_token Update access token
openid The unique ID of the user.

Non-follower visiting the web pages of an official account can also generate a unique OpenID.

scope User authorization scope, separated by comma (,)

An example of an unsuccessful JSON response (caused by an invalid code) is as follows:

{"errcode":40029,"errmsg":"invalid code"}

Return Codes

Update the access token if required

An access token is valid for a short period, but you can update it on expiry using refresh_token. A refresh_token can be valid for 7/30/60/90 days, and the user needs to perform authorization again after the refresh_token expires.

Request Description

Request the following link to obtain access token after you get the refresh_token in the second step:
https://api.wechat.com/sns/oauth2/refresh_token?appid=APPID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN


Parameter Required Description
appid Yes The unique ID of the official account
grant_type Yes refresh_token
refresh_token Yes The refresh token obtained by the access token

Return Description An example of a successful JSON response is as follows:

{
   "access_token":"ACCESS_TOKEN",
   "expires_in":7200,
   "refresh_token":"REFRESH_TOKEN",
   "openid":"OPENID",
   "scope":"SCOPE"
}
Parameter Description
access_token The certificate for calling the web authorization API. Note: this access token is not the one mentioned in the Basis Support pages.
expires_in The validity time of the certificate (unit: second)
refresh token Update access token
openid The unique ID of the user
scope User authorization scope, which is separated by a comma (,)

An example of an unsuccessful JSON response (caused by an invalid code) is as follows:

{"errcode":40029,"errmsg":"invalid code"}

Return Codes

Obtain user info (scope=snsapi_userinfo)

If the scope is snsapi_userinfo, the developer can obtain user info using the access token and OpenID.

Request Description

HTTP request method: GET (Use Https protocol)
https://api.wechat.com/sns/userinfo?access_token=ACCESS_TOKEN&openid=OPENID

Parameter Description

Parameter Description
access_token The certificate for calling the web authorization API. Note: this access token is not the one mentioned in the Basis Support pages.
openid The unique ID of the user

Return Description An example of a successful JSON response is as follows:

{
   "openid":" OPENID",
   " nickname": NICKNAME,
   "sex":"1",
   "province":"PROVINCE"
   "city":"CITY",
   "country":"COUNTRY",
   "headimgurl":    "http://wx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/46", 
   "privilege":[
   "PRIVILEGE1"
   "PRIVILEGE2"
   ]
}
Parameter Description
openid The unique ID of the user
nickname User's nickname
sex

1: Male 2: Female 0: Not set

province Province
city City
country Country
headimgurl Profile photo URL. The last number in the URL shows the size of the square image, which can be 0 (640*640), 46, 64, 96 and 132. This parameter is null if the user hasn't set a profile photo.
privilege User privilege information in the JSON array format, such as "chinaunicom" for WeChat WO users

An example of an unsuccessful JSON response (caused by invalid OpenID) is as follows:

{"errcode":40003,"errmsg":" invalid openid "}

Return Codes

Appendix: Verifying an Access Token

Request Method

http: GET (using HTTPS protocol)
https://api.wechat.com/sns/auth?access_token=ACCESS_TOKEN&openid=OPENID

Parameter Description

Parameter Description
access_token Access token providing authorization for calling web-based authorization. Note: this access token is not the one mentioned in the Basic Support pages.
openid A unique ID of the user specific to the official account.

Return Description An example of a successful JSON response is as follows:

{ "errcode":0,"errmsg":"ok"}

An example of an unsuccessful JSON response is as follows:

{ "errcode":40003,"errmsg":"invalid openid"}
Developer Guide
Custom-defined Menu
WeChat JS-SDK