/v1/messages/sendInbox

2024-05-14 06:15

POST /v1/messages/sendInbox

The sendInbox API is used for merchants or Independent Software Vendors (ISV) to send inbox messages to wallets by using access tokens.

Message structure

A message consists of a header and body. The following sections focus on the body structure.

For the header structure, see:

Request

Property	Data type	Required	Description	Example
accessToken	String	Yes	An access token that is used to send inbox messages. Max. length: 128 characters.	"2019112719074101000700000077771xxxx"
requestId	String	Yes	The unqiue ID to identifiy a request at a transaction. It is idempotent, whichi means if the API call has the same result no matter how many times the API call is applied. For example, if there is the same `requestId` stored, return the stored result related to the same `requestId` . It means that the same `requestId` only sends message once. Max. length: 128 characters.	"20191127190741010007013213123xxxx"
templateCode	String	Yes	An unique code to distinguish different content templates. Max. length: 256 characters.	"MINI_APP_COMMON_INBOX"
templates	Array<ContentTemplate>	Yes	A list of content templates of inbox messages to send. The url is generated by the mini program platform.	[ { "templateParameters":{ "Title":"mini-inbox-title", "Content":"hello mini program", "Url":"mini://platformapi/startapp?_ariver_appid=888888" } } ]

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information like status and error codes.	{ "resultCode":"SUCCESS", "resultStatus":"S", "resultMessage":"success" }
messageId	String	No	The unqiue ID to identify a message. Max. length: 258 characters.	"20201235900212xxxx"
extendInfo	String	No	The additionally extensive information. Max. length: 4096 characters.	"This is additional information"

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	It means that sending inbox messages via access tokens is successful. The corresponding `result.resultCode` is "SUCCESS" and the `result.resultMessage` is "Success".
A	The request is accepted by wallets. The corresponding `result.resultCode` is "ACCEPT"; and the `result.resultMessage` varies based on different situations.
U	It means unknown exception occur on wallet side, the merchant or ISV may try again. The corresponding `result.resultCode` is "UNKNOWN_EXCEPTION" and `result.resultMessage` is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.
F	It means that sending inbox messages via access tokens fails. The corresponding `result.resultCode` and `result.resultMessage` vary based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

Common error codes: are common for all Mini Program OpenAPIs.
API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage	Further action
F	ACCESS_TOKEN_NOT_COVER_THE_SCOPE	The access token permission scope does not contain specified scope.	Check the permission for the access token and try again
F	INVALID_ACCESS_TOKEN	The access token is invalid.	Restart the OAuth again or refresh the token and try again.

Sample

The Mini Program calls the my.getAuthCode JSAPI with specific scopes(NOTIFICATION_INBOX) 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 inbox message to the user.
The E-wallet backend returns the send result, including messsageId.

Request

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

Response

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