Notification Flow

This guide walks you through sending inbox notifications to SuperQi users. Before implementing notifications, ensure you have completed the authentication flow with the proper scope to obtain the user's access token.

Overview

To send notifications to users, you need:

1. Frontend: Request authorization with NOTIFICATION_INBOX scope
2. Backend: Use the access token to send inbox messages

Step 1: Frontend - Request Notification Permission

Auth Scope Requirement

When requesting user authorization, include the NOTIFICATION_INBOX scope:

my.getAuthCode({
  scopes: [
    "auth_base",
    "NOTIFICATION_INBOX", // Required for sending notifications
  ],
  success: (res) => {
    // Send res.authCode to your backend to exchange for access token
    console.log("Authorization Code:", res.authCode);
    // TODO: Implement your backend API call here
  },
  fail: (res) => {
    // Handle authorization failure
    console.error("Authorization failed:", res);
    // TODO: Implement your error handling here
  },
});

Step 2: Backend - Send Inbox Message

API Endpoint

URL: POST /v1/messages/sendInbox

Request Body

{
  "accessToken": "2019112719074101000700000077771xxxx",
  "requestId": "20191127190741010007013213123xxxx",
  "templateCode": "MINI_APP_COMMON_INBOX",
  "templates": [
    {
      "templateParameters": {
        "Title": "Notification Title",
        "Content": "Your notification message content here",
        "Url": "mini://platformapi/startapp?_ariver_appid=888888"
      }
    }
  ]
}

Request Parameters

accessToken (String, Required)

• The access token obtained from the authentication flow
• Must include NOTIFICATION_INBOX scope
• Max length: 128 characters

requestId (String, Required)

• Unique ID to identify the request
• Used for idempotence - same requestId will only send message once
• Max length: 128 characters

templateCode (String, Required)

• Template code for the notification format
• Use: "MINI_APP_COMMON_INBOX"
• Max length: 256 characters

templates (Array, Required)

• Array of content templates for the inbox message
• templateParameters:
  • Title: Notification title displayed to user
  • Content: Main notification message content
  • Url: Deep link URL generated by the mini program platform

Expected Response

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

Response Status

Common Error Codes

Notification-Specific Errors

Notification Flow Sequence

1. Frontend: Request authorization with NOTIFICATION_INBOX scope
2. User: Confirms authorization in SuperQi app
3. Backend: Exchange auth code for access token (with notification scope)
4. Backend: Send inbox message using access token
5. SuperQi: Delivers notification to user's inbox
6. User: Receives notification in SuperQi app

Best Practices