Overview

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

Neynar provides a simple way to manage approved notification tokens, send notifications, handle notification permission revokes, and frame "remove" events.

Set up Notifications

Step 1: Add events webhook URL to Frame Manifest

(a) Locate the Neynar frame events webhook URL

The Neynar frame 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 Frame 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 Frame

(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 frame add/remove & notifications enabled/disabled events delivered on this events webhook.

Step 3: Send a notification to users

Use the following example on the @neynar/nodejs-sdk to send notifications to your users. The API can send a notification to a max of 100 users at a time.

const targetFids = [191,194, 6131];
const notification = {
  title: "🪐",
  body: "It's time to savor farcaster",
  target_url: "https://your-frame-domain.com/notification-destination",
};

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

Additional documentation on the API and it's body parameters can be found at https://docs.neynar.com/reference/publish-frame-notifications

FAQ

How do I determine if the user has already added my frame?

The FrameContext object passed into the frame at launch time contains the added boolean and notificationDetails object. More details here

What happens if I send a notification via API to a user that has revoked notification permission?

To avoid getting rate-limited by Farcaster clients, Neynar will filter out sending notifications to disabled tokens