Send Notifications to Frame Users

​

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.

Frame analytics will automatically populate once you use Neynar for notifications.

​

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 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