/v2/messages/sendInbox

POST /v2/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 are focused 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"

authClientId

String 

No

The unqiue auth client ID

Max. length: 128 characters.

"202016726873874774774xxxx"

requestId

String 

Yes

The unique ID to identify a request at a transaction.

It is idempotent, which 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 messages once.

Max. length: 128 characters.

"20191127190741010007013213123xxxx"

templateCode

String 

Yes

A unique code to distinguish different content templates.

Max. length: 256 characters.

"TP_5800000001xxxx"

templates

Array<ContentTemplate>

Yes

A list of content templates of inbox messages to send. The maximum array size is five.

[

       {

           "templateParameters": {

               "who": "string to represent a name, e.g. XiaoMing"

           },

           "language": "en-US"

       }

   ]

extendInfo

String

No

The extension information that wallets and merchants want to describe.

Max. length: 4096 characters.

copy
{
    "memo": "memo"
}

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 unique ID to identify a message.

Max. length: 258 characters.

"20201235900212xxxx"

extendInfo

String

No

The extension information that wallets and merchants want to describe.

Max. length: 4096 characters.

copy
{
    "memo": "memo"
}

Result process logic

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

resultStatus

Description 

S

It means that sending inbox messages via access tokens is successful.

The corresponding result.resultCode is "SUCCESS" and the  result.resultMessage  is "Success".

U

It means an unknown exception occurs on the 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 are various 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

INVALID_ACCESS_TOKEN

The access token is invalid.

Restart the OAuth again or refresh the token and try again.

F

INVALID_AUTH_CLIENT

The authentication client ID is invalid.

The authClientId is the app ID for mini programs. Check if the appId is correct; if yes, contact your service provider.

F

USER_STATUS_ERROR

The user account status is wrong.

The user account might be locked or unregistered.

F

VERIFY_REQUEST_ID_INVALID

The request ID is invalid.

Check the format of the request IDand try again.

Sample

/v2/messages/sendInbox
  1. Merchants send a request to send inbox messages to wallets by an access token.
  2. Wallets returns a messsageId to merchants.

Request

copy
{
    "accessToken": "2019112719074101000700000077771xxxx",
    "authClientId": "202016726873874774774xxxx",
    "requestId": "20191127190741010007013213123xxxx",
    "templateCode": "TP_5800000001xxxx",
    "templates": [
        {
            "templateParameters": {
                "who": "string to represent a name"
            },
            "language": "en-US"
        }
    ],
    "extendInfo": "This is additional information"
}

Response

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