Send a notification to a user

​

Delivers a notification to a single user as an inbox item, with a live push if the user is currently connected. Works for users who have never connected (the inbox is created lazily). No batching and no external destinations in v1 — delivery is to the Portal inbox only.

Send an idempotency-key header to make the send idempotent: the same key always returns the same item id and creates the item at most once.

Path Parameters

  • userId
    Type: string
    required

    A user id (the sub you minted the token with, or an id you add as a member).

Headers

  • idempotency-key
    Type: string

    Optional. The same key returns the same item id and creates the item at most once.

Body·

required
application/json
  • type
    Type: string
    required

    Userland notification type (for example ticket.assigned, mention).

  • data

    Optional userland payload, opaque to the platform.

  • title
    Type: string

    Optional human-readable title.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/users/{userId}/notifications
curl https://api.useportal.co/v1/users/u_456/notifications \
  --request POST \
  --header 'idempotency-key: 4d2a1f0c-8b7e-4c1a-9d3f-2a1b0c3d4e5f' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "type": "ticket.assigned",
  "title": "Ticket",
  "data": {
    "ticketId": "128",
    "channelId": "tkt-128"
  }
}'
The created item id
{
  "id": "ntf_4d2a1f0c-8b7e-4c1a-9d3f-2a1b0c3d4e5f"
}

Notification delivered. The id is the inbox item id (or the idempotency key, if you supplied one).