Messages

sendPush

Send push messages to wallet users via access tokens.

Overview

POST /v1/messages/sendPush enables merchants or Independent Software Vendors (ISV) to send push messages to wallet users using access tokens. This API allows you to deliver push notifications, alerts, and other time-sensitive messages directly to users' devices.

The message content is customizable through templates, allowing you to include dynamic parameters such as titles, content text, and deep links to specific pages within your Mini Program.

Ensure the access token has the NOTIFICATION_PUSH scope before attempting to send messages.
The requestId is idempotent—submitting the same ID multiple times will only send the message once.
Verify the access token is valid and not expired before making the API call.

sendPush flow

The Mini Program calls the my.getAuthCode JSAPI with specific scopes(NOTIFICATION_PUSH) to request an authorization code.
The E-wallet App processes the request and displays the authorization page that needs to be authorized.
The user confirms the authorization in the super app.
The E-wallet App service calls authorization service to processes the authorization information.
The E-wallet backend verifies the authorization information, generates the authCode and returns.
The E-wallet App service returns the authCode to the Mini Program.
The Mini Program sends the authCode to the merchant backend.
The merchant backend calls the applyToken API with authCode to apply the accessToken.
The E-wallet backend returns accessToken information to the merchant backend, such as accessToken, refreshToken, etc.
The merchant backend calls this API with the accessToken to send push message to the user.
The E-wallet backend returns the send result, including messageId.

Endpoint

Method	Path
`POST`	`/v1/messages/sendPush`

API Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request header
Response header

OpenAPIs Overview.

Request

Field	Type	Required	Description	Example
`accessToken`	`string`	Yes	Access token used to send push messages. Obtain via `applyToken` with `NOTIFICATION_PUSH` scope. Max length 128 characters.	`"2019112719074101000700000077771xxxx"`
`requestId`	`string`	Yes	Unique request identifier for idempotency. Resubmitting the same `requestId` will not send duplicate messages—if the same `requestId` is stored, the stored result is returned. Max length 128 characters.	`"20191127190741010007013213123xxxx"`
`templateCode`	`string`	Yes	Unique code to distinguish different content templates. Max length 256 characters.	`"MINI_APP_COMMON_PUSH"`
`templates`	`array`	Yes	Array of content template objects for push messages. The URL is generated by the mini program platform. Each object contains `templateParameters` with `Title`, `Content`, and `Url` fields.	See structure below

Template Structure:

Each item in the templates array must include:

templateParameters.Title (string, required): The push message title
templateParameters.Content (string, required): The push message content/body
templateParameters.Url (string, required): Deep link URL to navigate within the Mini Program (format: mini://platformapi/startapp?_ariver_appid={appId})

{
  "accessToken": "2019112719074101000700000077771xxxx",
  "requestId": "20191127190741010007013213123xxxx",
  "templateCode": "MINI_APP_COMMON_PUSH",
  "templates": [
    {
      "templateParameters": {
        "Title": "mini-push-title",
        "Content": "hello mini program",
        "Url": "mini://platformapi/startapp?_ariver_appid=888888"
      }
    }
  ]
}

Response

Field	Type	Required	Description	Example
`result`	`object`	Yes	Request result containing status and error codes information.	`{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }`
`messageId`	`string`	No	Unique message identifier. Present when message is sent successfully. Max length 258 characters.	`"20201235900212xxxx"`
`extendInfo`	`string`	No	Additional extensive information. Max length 4096 characters.	`"This is additional information"`

{
  "messageId": "20201235900212xxxx",
  "extendInfo": "",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  }
}

Result Processing Logic

The result.resultStatus field indicates the result of processing a request as follows:

Status	Description
`S`	Request succeeded. Sending push messages via access tokens is successful. `resultCode` is `SUCCESS` and `resultMessage` is `success`.
`A`	Request accepted. The request is accepted by wallets. `resultCode` is `ACCEPT`; `resultMessage` varies based on different situations.
`U`	Outcome unknown. Unknown exception occurred on wallet side. The merchant or ISV may try again. `resultCode` is `UNKNOWN_EXCEPTION` and `resultMessage` is "An API calling is failed, which is caused by unknown reasons."
`F`	Request failed. Sending push messages via access tokens fails. Inspect `resultCode` and `resultMessage` which vary based on different situations. Cross-reference Error codes below.

Error Codes

API-specific error codes: are listed in the following table.

Error Code	Result Status	Message	Next Step
`ACCESS_TOKEN_NOT_COVER_THE_SCOPE`	`F`	The access token permission scope does not contain specified scope.	Check the permission for the access token and try again. Ensure the access token includes the `NOTIFICATION_PUSH` scope.
`INVALID_ACCESS_TOKEN`	`F`	The access token is invalid.	Restart the OAuth again or refresh the token and try again.
`PARAM_ILLEGAL`	`F`	Illegal parameters exist. For example, a non-numeric input, or an invalid date.	Check the templates content and try again.
`UNKNOWN_EXCEPTION`	`U`	An API calling is failed, which is caused by unknown reasons.	1. Check whether `templateCode` is `MINI_APP_COMMON_PUSH`. If it is not `MINI_APP_COMMON_PUSH`, modify it. 2. Check whether the `templateCode` value in the request parameter meets the document expectations.

sendInbox

Send inbox messages to wallet users via access tokens.

inquiryMerchantInfo

Retrieve authorized merchant details with an access token.