Get Player Inbox
horizon_get_inboxReads a player's targeted messages and eligible project broadcasts, returning inbox entries, counts, cursors, and a polling interval for notifications or refresh.
Instructions
Reads targeted messages and eligible project broadcasts, counters and server polling interval. Use when: displaying notifications or refreshing on open, explicit action or the returned polling cadence; Inbox has no WebSocket topic. Not for: choosing rewards or writing messages from the player client. Requires: userId and the player's session: sign in with horizon_signin_email or horizon_signin_anonymous and pass its accessToken as sessionToken. Side effects: None (read only). Returns: {userId,cursor,revision,broadcastRevision,serverTime,pollAfterSeconds,unchanged,entries,counts,limits}. unchanged=true has empty entries: keep the cached entries. A changed snapshot replaces them completely. Entries of type item_gift and item_gift_return carry attachment.itemGift {giftId,instanceId,itemKey,direction}; decline an offer with horizon_decline_item_gift. Errors: 409 STATE_CONFLICT: retry the same entry ID. UNCLAIMED_REWARD: claim before removal. MAX_BALANCE_REACHED/DAILY_LIMIT_REACHED/INVENTORY_FULL leaves the reward or original item unclaimed. ENTRY_NOT_FOUND after removal/cleanup never grants again. 401 means the session is missing or expired: sign in again and retry with the new accessToken. 403 for a session means the token belongs to another user: pass the userId that signed in. Needs HORIZON_API_KEY. Every failure returns an error result (isError) with the HTTP status and body: a 401 that horizon_test_connection also returns means HORIZON_API_KEY is wrong, 429 means the account's per-minute rate limit was reached (wait a minute, then retry).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"userId": "<userId>",
"sessionToken": "<sessionToken>"
},
"name": "horizon_get_inbox"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Opaque cursor from this same player/project; omit for a full snapshot | |
| userId | Yes | Player UUID belonging to the selected project and player session | |
| sessionToken | Yes | Player accessToken, sent only as Authorization Bearer |