Sending notifications | AIUI | Rokid

The notification API lets third-party systems send agent messages to a specific user's Rokid Glasses. A notification can display text only or open a registered AIUI page …

Sending notifications

The notification API lets third-party systems send agent messages to a specific user's Rokid Glasses. A notification can display text only or open a registered AIUI page with parameters when selected.

Prerequisites

Prepare the following information before calling the API:

  • The SK for the account that owns the agent, available from the Rokid account token page.
  • The target user's account ID. The user must have a Glasses device bound to the account.
  • The agent ID that identifies the notification source.
  • A unique message ID generated by the sender for tracing and deduplication.

Use the npm package

import { CloudIntegration } from '@yodaos-pkg/cloud-integration'

const cloud = new CloudIntegration({
  token: process.env.ROKID_SK,
})

const response = await cloud.sendNotification({
  messageId: 'message-unique-id',
  accountId: 'target-account-id',
  message: {
    agentId: 'agent-id',
    content: 'You have a new agent notification.',
  },
})

console.log(response.data.success)

sendNotification() returns the complete response when the service reports code === 1 and data.success === true. Invalid input throws CloudIntegrationValidationError. Network, HTTP, response parsing, and server-side business failures throw CloudIntegrationError.

Use HTTP or curl

When the Node.js package is not suitable, send JSON directly to:

POST https://rcs.rokid.com/metis/callback/message
curl --location 'https://rcs.rokid.com/metis/callback/message' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ROKID_SK}" \
  --data '{
    "message_id": "message-unique-id",
    "account_id": "target-account-id",
    "message": {
      "agent_id": "agent-id",
      "content": "You have a new agent notification."
    }
  }'

The Authorization header must use the Bearer <SK> format. Each request sends one message to one user.

Open a page from a notification

Add tool under message to open a page when the notification is selected:

await cloud.sendNotification({
  messageId: 'outfit-message-id',
  accountId: 'target-account-id',
  message: {
    agentId: 'agent-id',
    content: 'View outfit suggestions',
    tool: {
      name: 'pages/cloth/index',
      parameters: {
        type: 'object',
        properties: {
          field: 'value',
        },
      },
    },
  },
})

tool.name must exactly match an AIUI page route registered in app.json. tool.parameters.type is always object. Values in properties are passed through unchanged, so the destination page's input schema should declare the corresponding fields.

Response

Example success response:

{
  "code": 1,
  "msg": "success",
  "timestamp": 1783343622284,
  "uuid": "e804768e6c6249ea96de06acf74f4fe1",
  "data": {
    "success": true
  }
}

Treat the push as failed when code is not 1 or data.success is not true. Use msg and uuid to diagnose the request.