The bell: a user's unread notifications

GET

/v1/notifications/unread

Like /inbox, unread only. With a secret key and no user_id, the project’s unread direct notifications (broadcasts are read per person, so they are not in that list). On a project whose require_user_hash is off, a browser call without a hash is still answered the old way, with meta.identity_verification: "off" and a warning.

Auth: Publishable key from the browser, with user_id and user_hash = HMAC-SHA256(signing secret, user_id) as lowercase hex, in the X-Nordva-User-Hash header or a user_hash parameter. A secret key may name any user_id and needs no hash. A wrong or missing hash answers USER_HASH_INVALID (403).

Rate limits: a browser call counts against 120 requests a minute per IP address (not the key’s budget), and the bell reads (/inbox, /unread, /unread/count) share a per-user hourly budget: Free 180, Indie 540, Builder 720 (RATE_LIMITED, 429, with Retry-After).

CORS: Access-Control-Allow-Origin: *.

Authorizations

• PublishableApiKey
• SecretApiKey

Parameters

Query Parameters

user_id

string

<= 256 characters

user_hash

string

The same hash, when a header is inconvenient.

limit

integer

default: 20 >= 1 <= 100

since

string format: date-time

Header Parameters

X-Nordva-User-Hash

string

HMAC-SHA256(signing secret, user_id), lowercase hex.

Responses

200

Unread notifications

object

data

object

notifications

Array<object>

What the bell needs. read, clicked and archived are this user’s.

object

id

string

title

string

body

string

action_url

string | null

icon

string

Allowed values: check warning info error

category

A short name the bell can show as a tab, such as billing.

string | null

/^[a-z][a-z0-9_-]{0,23}$/

actions

Up to two buttons. Each url is an http(s) URL or a path on your own site.

Array<object>

<= 2 items

object

label

required

string

<= 40 characters

url

required

string

<= 2048 characters

data

Anything your page needs with the item (at most 2,048 bytes as JSON). Never shown; the bell widget passes it in its events.

object | null

created_at

When it showed (the scheduled time for a scheduled one).

string format: date-time

read

boolean

read_at

string | null

clicked

boolean

archived

boolean

broadcast

boolean

changelog

Posted by a changelog entry; the widget labels it “What’s new”.

boolean

pinned

boolean

reactions

What this user can react with, in order, with everyone’s counts; null when it takes no reactions.

array | null

object

name

string

emoji

string

count

integer

my_reaction

This user’s reaction.

string | null

unread_count

When a user_id is given.

integer

poll_interval_seconds

integer

error

null

meta

object

400

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties

401

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties

403

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties

429

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties