Send Notifications to Mini App Users

​

Overview

Frames v2 enables developers to send notifications to users who have added the mini app to their Farcaster client and enabled notifications.

Neynar provides a simple way to manage approved notification tokens, send notifications, handle notification permission revokes, and mini app “remove” events.

Mini app analytics will automatically populate once you use Neynar for notifications.

​

Set up Notifications

​

Step 1: Add events webhook URL to Mini App Manifest

​

(a) Locate the Neynar frame events webhook URL

The Neynar mini app events webhook URL is on the Neynar app page. Navigate to dev.neynar.com/app and then click on the app.

It should be in this format -https://api.neynar.com/f/app/<your_client_id>/event. See the highlighted URL in the image below.

​

(b) Set this URL in the mini app manifest

Frame servers must provide a JSON manifest file on their domain at the well-known URI. for example https://your-frame-domain.com/.well-known/farcaster.json.

Set the Neynar frame events URL as the webhookUrl to the Frame Config object inside the manifest. Here’s an example manifest

{
  "accountAssociation": {
    "header": "eyJmaWQiOjE5MSwidHlwZSI6ImN1c3RvZHkiLCJrZXkiOiIweDNhNmRkNTY5ZEU4NEM5MTgyOEZjNDJEQ0UyMGY1QjgyN0UwRUY1QzUifQ",
    "payload": "eyJkb21haW4iOiIxYmNlLTczLTcwLTE2OC0yMDUubmdyb2stZnJlZS5hcHAifQ",
    "signature": "MHg1ZDU1MzFiZWQwNGZjYTc5NjllNDIzNmY1OTY0ZGU1NDMwNjE1YTdkOTE3OWNhZjE1YjQ5M2MxYWQyNWUzMTIyM2NkMmViNWQyMjFhZjkxYTYzM2NkNWU3NDczNmQzYmE4NjI4MmFiMTU4Y2JhNGY0ZWRkOTQ3ODlkNmM2OTJlNDFi"
  },
  "frame": {
    "version": "4.2.0",
    "name": "Your Frame Name",
    "iconUrl": "https://your-frame-domain.com/icon.png",
    "splashImageUrl": "https://your-frame-domain.com/splash.png",
    "splashBackgroundColor": "#f7f7f7",
    "homeUrl": "https://your-frame-domain.com",
    "webhookUrl": "https://api.neynar.com/f/app/<your_client_id>/event"
  }
}

​

Step 2: Prompt users to add your Mini App

​

(a) Install the @farcaster/frame-sdk

yarn add @farcaster/frame-sdk

​

(b) Prompt the user

import sdk from "@farcaster/frame-sdk";

const result = await sdk.actions.addFrame();

The result type is:

export type FrameNotificationDetails = {
  url: string;
  token: string;
};

export type AddFrameResult =
  | {
      added: true;
      notificationDetails?: FrameNotificationDetails;
    }
  | {
      added: false;
      reason: 'invalid_domain_manifest' | 'rejected_by_user';
    };

If added is true and notificationDetails is a valid object, then the client should have called POST to the Neynar frame events webhook URL with the same details.

Neynar will manage all mini app add/remove & notifications enabled/disabled events delivered on this events webhook.

​

Step 3: Send a notification to users

Notifications can be broadcast to all your mini app users with notifications enabled or to a limited set of FIDs. Notifications can also be filtered so that only users meeting certain criteria receive the notification.

The target_fids parameter is the starting point for all filtering. Pass an empty array for target_fids to start with the set of all FIDs with notifications enabled for your app, or manually define target_fids to list specific FIDs.

The following example uses the @neynar/nodejs-sdk to send notifications to users and includes a set of filtering criteria.

const targetFids = []; // target all relevant users
const filters = {
  exclude_fids: [420, 69], // do not send to these FIDs
  following_fid: 3, // only send to users following this FID
  minimum_user_score: 0.5, // only send to users with score >= this value
  near_location: { // only send to users near a certain point
    latitude: 34.052235,
    longitude: -118.243683,
    radius: 50000, // distance in meters from the lat/log point (optional, defaults to 50km)
  }
};
const notification = {
  title: "🪐",
  body: "It's time to savor farcaster",
  target_url: "https://your-frame-domain.com/notification-destination",
};

client.publishFrameNotifications({ targetFids, filters, notification }).then((response) => {
  console.log("response:", response);
});

Additional documentation on the API and its body parameters can be found at /reference/publish-frame-notifications

​

Step 4: Check analytics

Notification analytics will automatically show in your developer portal once you start using Neynar for frame notifications.

​

FAQ