Sign in

v1

latestOpenAPI 3.0.42026-07-26159287356.1 KB
Frame

Send notifications

Send notifications to interactors of a mini app. By default every broadcast is delivered synchronously and returns 200 with aggregate counts. When the ASYNC_NOTIFICATIONS_ENABLED server flag is on, broadcasts with more than 100 notification tokens are queued and return 202 with a campaign_id instead; poll the campaign stats endpoint for progress. Small broadcasts always stay synchronous.

post/v2/farcaster/frame/notifications/

Request body

target_fidsinteger[]

An array of target FIDs to whom the notifications should be sent. Each FID must be a positive integer. Pass an empty array to send notifications to all FIDs with notifications enabled for the mini app.

Example request

{
  "filters": {
    "exclude_fids": [
      2,
      8988
    ],
    "following_fid": 3,
    "minimum_user_score": 0.5,
    "near_location": {
      "latitude": 37.774929,
      "longitude": -122.419418,
      "radius": 1000
    }
  },
  "notification": {
    "body": "You have received a new message in your inbox.",
    "target_url": "https://example.com/notifications",
    "title": "New Message",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "target_fids": [
    1,
    2,
    3
  ]
}

Response

Success

campaign_idstring uuid required

The unique identifier for the notification campaign.

failure_countinteger required

The number of notifications that failed to deliver.

not_attempted_countinteger required

The number of notifications not attempted (e.g., disabled tokens, invalid tokens).

retryable_fidsFid[]

List of FIDs that failed due to retryable errors (rate_limited, failed, http_error). Can be used to retry sending notifications to these users.

success_countinteger required

The number of notifications successfully delivered.

Example response

{
  "retryable_fids": [
    3
  ]
}