tencent cloud

Open APIs
Last updated: 2025-11-26 15:36:18
Open APIs
Last updated: 2025-11-26 15:36:18

Login

login

This API is called using wx.login(Object object).
Feature description: This API is used to obtain a login credential, which can then be used to retrieve user login session information.
Note:
For version v2 (supported only on SaaS), refer to the practical tutorial. This API can be called directly in the IDE (minimum supported version: 2.1.111).
The version v1 needs to be jointly tested with the superapp. The content returned on real devices is provided by the superapp, and can be customized. In the IDE, you can mock the return value on the mock panel.
For version control rules, see apiVersion .
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
success
function
-
False
Callback function for successful API calls.
fail
function
-
False
Callback function for failed API calls.
complete
function
-
False
Callback function executed after API call ends (regardless of success or failure).
object.success callback function parameter:Object res
Property
Type
Description
code
string
User login credential (valid for five minutes). Developers need to call jscode2session on the server, and use the code to retrieve openid and session_key.
object.fail callback function parameter:Object err
Property
Type
Description
errMsg
string
Error message.
errno
Number
An error code. For details of error codes, see Error Code.
Example:
wx.login({
success (res) {
if (res.code) {
// Initiate a network request.
wx.request({
url: 'https://example.com/onLogin',
data: {
code: res.code
}
})
} else {
console.log('Login failed!' + res.errMsg)
}
}
})

getAuthCode

This API is called using wx.getAuthCode(Object object).
Feature description: This API provides an experimental feature that retrieves an authorization code through pre-defined scopes. It requires negotiation between the mini program and the superapp for implementation.
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
success
function
-
False
Callback function for successful API calls.
fail
function
-
False
Callback function for failed API calls.
complete
function
-
False
Callback function executed after API call ends (regardless of success or failure).
Example
wx.getAuthCode({
scopes:["CUSTOM_SCOPE_X","CUSTOM_SCOPE_Y"],
success (res) {
if (res.code) {
// Initiate a network request.
wx.request({
url: 'https://example.com/onLogin',
data: {
code: res.code
}
})
} else {
console.log('Login failed!' + res.errMsg)
}
}
})

checkSession

This API is called using wx.checkSession(Object object).
Feature description: This API is used to check whether the login session has expired.
Note:
For version v2 (supported only on SaaS), refer to the practical tutorial. This API can be called directly in the IDE (minimum supported version: 2.1.111).
The session_key is unique. At any given time, a user can have only one valid session_key while using the mini program.
The user login session obtained through the wx.login has a certain validity period. Developers can call the wx.checkSession to check if the current user login session is still valid.
wx.checkSession checks the session_key corresponding to the last code obtained. A successful call indicates that the session_key has not expired, while a failed call indicates that the session_key has expired.
If the login session has expired, developers can call wx.login again to obtain a new user login session.
The version v1 needs to be jointly tested with the superapp. The content returned on real devices is provided by the superapp, and can be customized. In the IDE, you can mock the return value on the mock panel.
For version control rules, see apiVersion .
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
success
function
-
False
Callback function for successful API calls.
fail
function
-
False
Callback function for failed API calls.
complete
function
-
False
Callback function executed after API call ends (regardless of success or failure).
Example:
wx.checkSession({
success () {
// The session_key has not expired and remains valid for this lifecycle.
},
fail () {
// The session_key has expired, and the login process needs to be executed again.
wx.login() // Log in again.
}
})

User information

Note:
APIs related to account information are supported in mini programs but not in mini games.

getUserProfile

This API is called using wx.getUserProfile(Object object).
Feature description: This API is currently not supported in IDE and needs to be jointly tested with the superapp. The content returned on real devices is provided by the superapp, and can be customized.
In the IDE, you can mock the return value on the mock panel.
This API is used to retrieve user information.
Return value:Object object.
Property
Type
Default value
‍Required
Description
lang
string
en
False
The language used to display the user information. Valid values:
en: English
zh_CN: Simplified Chinese
zh_TW: Traditional Chinese
desc
string
-
True
Describes the purpose of retrieving user information. Up to 30 characters.
success
function
-
False
Callback function for successful API calls.
fail
function
-
False
Callback function for failed API calls.
complete
function
-
False
Callback function executed after API call ends (regardless of success or failure).

getUserInfo

This API is called using wx.getUserInfo(Object object).
Feature description: This API is currently not supported in IDE and needs to be jointly tested with the superapp. The content returned on real devices is provided by the superapp, and can be customized.
In the IDE, you can mock the return value on the mock panel.
This API is used to retrieve user information. It distinguishes between initial calls (requiring user authorization via the <button open-type="getUserInfo"/> component) and post-authorization calls (using wx.getUserInfo directly).
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
lang
string
en
False
The language used to display the user information. Valid values:
en: English
zh_CN: Simplified Chinese
zh_TW: Traditional Chinese
success
function
-
False
Callback function for successful API calls.
fail
function
-
False
Callback function for failed API calls.
complete
function
-
False
Callback function executed after API call ends (regardless of success or failure).
object.success callback function parameter: Object res
Property
Type
Description
userInfo
UserInfo
User information object.
Example
Example for the mini program user information component (user authorization)
<!-- To display only the user's profile photo and nickname, use the <open-data /> component. -->
<open-data type="userAvatarUrl"></open-data>
<open-data type="userNickName"></open-data>
<!-- Use the button for login authorization -->
<button wx:if="{{canIUse}}" open-type="getUserInfo" bindgetuserinfo="bindGetUserInfo">Authorize login</button>
<view wx:else>Please upgrade the superapp version</view>

Page({
data: {
canIUse: wx.canIUse('button.open-type.getUserInfo')
},
onLoad: function() {
// Check whether userAvatarUrl is authorized.
wx.getSetting({
success (res){
if (res.authSetting['scope.userInfo']) {
// Already authorized, can directly call getUserInfo to get the user profile photo and nickname.
wx.getUserInfo({
success: function(res) {
console.log(res.userInfo)
}
})
}
}
})
},
bindGetUserInfo (e) {
console.log(e.detail.userInfo)
}
})
Example:
// This must be called only after the user has granted authorization.
wx.getUserInfo({
success: function(res) {
var userInfo = res.userInfo
var nickName = userInfo.nickName
var avatarUrl = userInfo.avatarUrl
}
})

userInfo

Feature description:This API is used to retrieve user information. When customizing the returned content, it is recommended to include the following properties to support the mini program's subsequent business logic processing.
Parameter and description:
Property
Type
Description
nickName
string
User’s nickname.
avatarUrl
string
The URL of the user's profile photo. The last number in the URL represents the size of the square profile photo (0, 46, 64, 96, 132 are available to choose from. 0 represents a 640 × 640 profile photo, 46 represents a 46 × 46 profile photo, and so on. The default value is 132.) This field is left blank if the user has no profile photo. If the user changes the profile photo, the original profile photo URL will become invalid.
gender
number
User's gender. This will no longer be returned. Valid values:
0: Unknown
1: Male
2: Female
country
string
The user’s country. This will no longer be returned.
province
string
The user's province. This will no longer be returned.
city
string
The user's city. This will no longer be returned.
language
string
The language used to display the country, province, and city. It will always return "zh_CN". Valid values:
en: English
zh_CN: Simplified Chinese
zh_TW: Traditional Chinese

chooseAvatar

This API is called using <button open-type="chooseAvatar" bind:chooseavatar="onChooseAvatar"> ... </button>.
Feature description: The IDE currently supports returning mock data for superapp user’s profile photo. The content returned on real devices is provided by the superapp.
Return value:The URL of profile photo. Example
Example
wxml
javascript
<button open-type="chooseAvatar" bind:chooseavatar="onChooseAvatar">
<image src="{{userHead}}" class="userHead" mode="aspectFill" />
</button>
Page({
data: {
userHead: defaultAvatar,
},
onChooseAvatar(e) {
console.log('onChooseAvatar===', e)
const { avatarUrl } = e.detail;
if (avatarUrl) {
this.setData({
userHead: avatarUrl,
})
}
},
})

getNickName

This API is called using <input type="nickname" class="value" placeholder="Please enter the nickname" />.
Feature description: The IDE currently supports returning mock data for superapp user’s nickname. The content returned on real devices is provided by the superapp.
Return value:User’s nickname.Example
Example
wxml
<view class="settingItem">
<text class="caption">Nickname</text>
<input type="nickname" class="value" placeholder="Please enter the nickname" />
</view>

Sensitive information

getPhoneNumber

This API is called using <button open-type="getPhoneNumber" bindgetphonenumber="handleGetPhoneNumber"> ... </button>.
Feature description: The IDE currently supports returning mock data for superapp user’s phone number. The content returned on real devices is provided by the superapp.
Return value:code Example
Example
wxml
javascript
<button
class="button"
type="default"
size="mini"
open-type="getPhoneNumber"
bindgetphonenumber="handleGetPhoneNumber">
Get the phone number
</button>
Page({
handleGetPhoneNumber(e) {
const { code, errMsg } = e.detail
if (code) {
// Initiate a network request to retrieve the phone number from the backend.
wx.request({
url: 'https://example.com/getPhoneNumber',
data: {code},
success: res => console.log('phone:', res)
})
} else {
console.error(errMsg)
}
},
});

getEmailAddress

This API is called using <button open-type="getEmailAddress" bindgetemailaddress="handleGetEmailAddress"> ... </button>.
Feature description: The IDE currently supports returning mock data for superapp user’s email address. The content returned on real devices is provided by the superapp.
Return value:code Example
Example
wxml
javascript
<button
class="button"
type="default"
size="mini"
open-type="getEmailAddress"
bindgetemailaddress="handleGetEmailAddress">
Get the email address
</button>
Page({
handleGetEmailAddress(e) {
const { code, errMsg } = e.detail
if (code) {
// Initiate a network request to retrieve the email address from the backend.
wx.request({
url: 'https://example.com/getEmail',
data: {code},
success: res => console.log('mail:', res)
})
} else {
console.error(errMsg)
}
},
});


Payment

requestPayment

This API is called using wx.requestPayment(Object object).
Feature description:This API initiates payment in the superapp. The superapp must have payment capabilities and complete the payment process integration. We recommend developers refer to our Payment and Merchant Practical Tutorial for API implementation. It requires the collaboration between superapp and mini program developers to effectively ensure data security and payment scalability.
Note: Generally, the parameters timeStamp, nonceStr, package, signType, and paySign should be generated by the mini program backend. The values are returned when the mini program frontend calls the backend order API, and then used to call wx.requestPayment to initiate the payment process.
Parameter and description: Object object.
Property
Type
Default value
‍Required
Description
timeStamp
string
-
True
Timestamp in seconds since 1970-01-01 00:00:00, representing the current time.
nonceStr
string
-
True
Random string, up to 32 characters long.
package
string
-
True
The prepay_id parameter value returned from the unified order API, formatted as: prepay_id=***.
signType
string
-
True
Signature algorithm, should match the value used during backend ordering, typically: RSA.
paySign
string
-
True
Signature. For details, see Mini Program Payment Practical Tutorial
success
function
-
False
Callback function for successful API calls.
fail
function
-
False
Callback function for failed API calls.
complete
function
-
False
Callback function executed after API call ends (regardless of success or failure).
Example:
wx.requestPayment({
timeStamp: '',
nonceStr: '',
package: '',
signType: 'RSA',
paySign: '',
success (res) {
/* res is typically returned by the superapp to the mini program frontend, with its structure customized by the superapp.
* Upon successful payment, res.errMsg will be 'requestPayment:ok'.
* It is recommended for the mini program to call the backend API to confirm payment status in the success callback to ensure payment callback information is synchronized with the mini program backend.
*/
if(res.errMsg === 'resquestPayment:ok'){
// send request to miniprogram backend to comfirm payment state
}
},
fail (err) {
// The error message is usually returned by the superapp to the mini program frontend, and the mini program frontend should provide appropriate user guidance after the error occurs.
}
})
If the user’s system already provides a mature and reliable payment process, the developers can customize the payment flow by combining this API with custom APIs.


Message subscription

requestSubscribeMessage

This API is called using wx.requestSubscribeMessage(Object object).
Feature description:This API triggers the mini program's subscription message page in the superapp and returns the user's subscription operation result. You can learn the user’s subscription status for related template messages using wx.getSetting .
Note:
Supported only on SaaS.
One-time template IDs and permanent template IDs cannot be used simultaneously.
In a single authorization call, each tmplId corresponding to a template title must be unique; if duplicates are found, only one will be retained.
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
tmplIds
Array
-
True
Array of message template IDs to subscribe to. A maximum of 3 messages can be subscribed to in one call. Template IDs are configured in the console under Mini program management - Message subscription. Each tmplId must correspond to a unique template title, otherwise duplicates will be filtered out.
success
function
-
False
Callback function for successful API calls.
fail
function
-
False
Callback function for failed API calls.
complete
function
-
False
Callback function executed after API call ends (regardless of success or failure).
object.success callback function parameter:Object res
Property
Type
Description
errMsg
String
The value of errMsg is 'requestSubscribeMessage:ok' when the API is called successfully.
[TEMPLATE_ID: string]
String
[TEMPLATE_ID] is a dynamic key representing the template ID. The value can be 'accept', 'reject', 'ban', or 'filter'.
'accept': The user agreed to subscribe to the message corresponding to this template ID.
'reject': The user refused to subscribe to the message corresponding to this template ID.
'ban': The template has been banned by the backend.
'filter': The template was filtered out by the backend due to duplicate titles.
For example, { errMsg: "requestSubscribeMessage:ok", zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: "accept"} indicates that the user has agreed to subscribe to the message zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE.
object.fail callback function parameter:Object err
Property
Type
Description
errMsg
String
Error message when the API call fails.
errno
Number
Error code when the API call fails.
Error code
errCode
errMsg
Description
10001
TmplIds can't be empty
The tmplIds parameter is empty.
10002
Request list fail
Network error. Failed to request the message list.
10003
Request subscribe fail
Network error. Failed to send the subscription request.
20001
No template data return, verify the template id exist
No template data, usually because the template ID does not exist or does not match the template type.
20002
Templates type must be same
The template messages include both temporary and permanent types.
20003
Templates count out of max bounds
The number of template messages exceeds the limit.
20004
The main switch is switched off
The user has turned off the main switch, preventing subscriptions.
20005
This mini program was banned from subscribing messages
The mini program is banned from subscribing to messages.
20013
Reject DeviceMsg Template
Subscription to device messages using this API is not allowed.
Example:
wx.requestSubscribeMessage({
tmplIds: [''],
success: (res) => {
console.log('requestSubscribeMessage===success', res)
}
})


Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback