To meet the needs of user channel promotion analysis and user account linking, Weixin Official Accounts Platform provides an API for generating QR codes with parameters. You can use this API to obtain multiple QR codes with different scene values. After a user scans the QR code, the relevant event will be pushed to the Official Account.
QR codes are divided into the following two types:
- Temporary QR codes, whose maximum expiration time is 30 days (i.e. 2,592,000 seconds) upon generation. You can generate a huge number of temporary QR codes, link them with accounts, and use them in business scenarios that do not require permanent storage of QR codes.
- Permanent QR codes, which never expire. You can generate a maximum of 100,000 permanent QR codes and use them to link with accounts and collect the information of user sources.
When a user scans a QR code with a scene value, the following two events may be pushed:
If the user has not followed the Official Account, they can follow it, and then Weixin will push the Official Account following event with the scene value to the developer.
If the user has followed the Official Account, they can scan the QR code to start a chat, and then Weixin will also push the scan event with the scene value to the developer.
To get a QR code with parameters, create a QR code ticket, and then exchange it for a QR code from the specified URL.
Creating a QR code ticket
During creation, a developer-set parameter (scene_id) is required to describe the process of creating a ticket for a temporary or permanent QR code.
Temporary QR code request description
HTTP request method: POST
URL: https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=TOKEN
POST data format: json
POST data example: {"expire_seconds": 604800, "action_name": "QR_SCENE", "action_info": {"scene": {"scene_id": 123}}}
Or you can use the following POST data to create a QR code parameter as a string:
{"expire_seconds": 604800, "action_name": "QR_STR_SCENE", "action_info": {"scene": {"scene_str": "test"}}}
Permanent QR code request description
HTTP request method: POST
URL: https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=TOKEN
POST data format: json
POST data example: {"action_name": "QR_LIMIT_SCENE", "action_info": {"scene": {"scene_id": 123}}}
Or you can use the following POST data to create a QR code parameter as a string:
{"action_name": "QR_LIMIT_STR_SCENE", "action_info": {"scene": {"scene_str": "test"}}}
Parameters
| Parameter | Description |
|---|---|
| expire_seconds | The validity period of the QR code, in seconds. The maximum value is 2592000 (that is, 30 days). If this field is left empty, the validity period is 30 seconds by default. |
| action_name | The type of the QR code. QR_SCENE is a temporary integer parameter value. QR_STR_SCENE is a temporary string parameter value. QR_LIMIT_SCENE is a permanent integer parameter value. QR_LIMIT_STR_SCENE is a permanent string parameter value. |
| action_info | The details of the QR code |
| scene_id | The ID of the scene value. For a temporary QR code, it is a 32-bit non-zero integer. For a permanent QR code, the value ranges from 1 to 100000. |
| scene_str | The ID of the scene value in string format. It ranges from 1 to 64. |
Response Description
The JSON return result for a successful request:
{"ticket":"gQH47joAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL2taZ2Z3TVRtNzJXV1Brb3ZhYmJJAAIEZ23sUwMEmm
3sUw==","expire_seconds":60,"url":"http://weixin.qq.com/q/kZgfwMTm72WWPkovabbI"}
| Parameter | Description |
|---|---|
| ticket | The ticket of the QR code. It is used to exchange for the QR code within the effective time. |
| expire_seconds | The validity period of the QR code, in seconds. The maximum value is 2592000 (that is, 30 days). |
| url | The URL obtained by resolving the QR code image. Developers can generate the required QR code image based on this URL. |
Exchanging the ticket for the QR code
Developers can exchange the ticket for the QR code image. Note that this API can be called without login.
Request Description
HTTP GET Request (use the HTTPS protocol) https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET
Note: The ticket must be URL-encoded.
Response Description
If the ticket is correct, the HTTP response code 200 is returned. The QR code is displayed as an image. You can directly display or download the image.
An example of HTTP header is as follows:
Accept-Ranges:bytes
Cache-control:max-age=604800
Connection:keep-alive
Content-Length:28026
Content-Type:image/jpg
Date:Wed, 16 Oct 2013 06:37:10 GMT
Expires:Wed, 23 Oct 2013 14:37:10 +0800
Server:nginx/1.4.1
If the ticket is incorrect/invalid, the HTTP response code 400 is returned.