Skip to main content
POST
/
v2
/
farcaster
/
frame
/
notifications
/
Send notifications
curl --request POST \
  --url https://api.neynar.com/v2/farcaster/frame/notifications/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "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"
  },
  "filters": {
    "exclude_fids": [
      2,
      8988
    ],
    "following_fid": 3,
    "minimum_user_score": 0.5,
    "near_location": {
      "latitude": 37.774929,
      "longitude": -122.419418,
      "radius": 1000
    }
  },
  "target_fids": [
    1,
    2,
    3
  ]
}
'
import requests

url = "https://api.neynar.com/v2/farcaster/frame/notifications/"

payload = {
    "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"
    },
    "filters": {
        "exclude_fids": [2, 8988],
        "following_fid": 3,
        "minimum_user_score": 0.5,
        "near_location": {
            "latitude": 37.774929,
            "longitude": -122.419418,
            "radius": 1000
        }
    },
    "target_fids": [1, 2, 3]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    notification: {
      body: JSON.stringify('You have received a new message in your inbox.'),
      target_url: 'https://example.com/notifications',
      title: 'New Message',
      uuid: '123e4567-e89b-12d3-a456-426614174000'
    },
    filters: {
      exclude_fids: [2, 8988],
      following_fid: 3,
      minimum_user_score: 0.5,
      near_location: {latitude: 37.774929, longitude: -122.419418, radius: 1000}
    },
    target_fids: [1, 2, 3]
  })
};

fetch('https://api.neynar.com/v2/farcaster/frame/notifications/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.neynar.com/v2/farcaster/frame/notifications/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ],
    'filters' => [
        'exclude_fids' => [
                2,
                8988
        ],
        'following_fid' => 3,
        'minimum_user_score' => 0.5,
        'near_location' => [
                'latitude' => 37.774929,
                'longitude' => -122.419418,
                'radius' => 1000
        ]
    ],
    'target_fids' => [
        1,
        2,
        3
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.neynar.com/v2/farcaster/frame/notifications/"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.neynar.com/v2/farcaster/frame/notifications/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"notification\": {\n    \"body\": \"You have received a new message in your inbox.\",\n    \"target_url\": \"https://example.com/notifications\",\n    \"title\": \"New Message\",\n    \"uuid\": \"123e4567-e89b-12d3-a456-426614174000\"\n  },\n  \"filters\": {\n    \"exclude_fids\": [\n      2,\n      8988\n    ],\n    \"following_fid\": 3,\n    \"minimum_user_score\": 0.5,\n    \"near_location\": {\n      \"latitude\": 37.774929,\n      \"longitude\": -122.419418,\n      \"radius\": 1000\n    }\n  },\n  \"target_fids\": [\n    1,\n    2,\n    3\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.neynar.com/v2/farcaster/frame/notifications/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"notification\": {\n    \"body\": \"You have received a new message in your inbox.\",\n    \"target_url\": \"https://example.com/notifications\",\n    \"title\": \"New Message\",\n    \"uuid\": \"123e4567-e89b-12d3-a456-426614174000\"\n  },\n  \"filters\": {\n    \"exclude_fids\": [\n      2,\n      8988\n    ],\n    \"following_fid\": 3,\n    \"minimum_user_score\": 0.5,\n    \"near_location\": {\n      \"latitude\": 37.774929,\n      \"longitude\": -122.419418,\n      \"radius\": 1000\n    }\n  },\n  \"target_fids\": [\n    1,\n    2,\n    3\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "failure_count": 123,
  "not_attempted_count": 123,
  "success_count": 123,
  "retryable_fids": [
    3
  ]
}
{
  "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
{
  "code": "InvalidField",
  "errors": [
    {
      "code": "<string>",
      "expected": "<string>",
      "message": "<string>",
      "path": [
        "<string>"
      ],
      "received": "<string>"
    }
  ],
  "message": "Invalid query parameters"
}
{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}
{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}
{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}

​
See guide on setting this up easily Send Notifications to Mini App Users

​
Node.js SDK

🔗 SDK Method: publishFrameNotifications Use this API endpoint with the Neynar Node.js SDK for typed responses and better developer experience.

Authorizations

​
x-api-key
string
header
default:NEYNAR_API_DOCS
required

API key to authorize requests

Body

application/json
​
notification
object
required
​
filters
object

Filters to apply to the target_fids set. All filters are additive, so only users matching all filters will be notified.

Example:
{
  "exclude_fids": [2, 8988],
  "following_fid": 3,
  "minimum_user_score": 0.5,
  "near_location": {
    "latitude": 37.774929,
    "longitude": -122.419418,
    "radius": 1000
  }
}
​
target_fids
integer[]

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.

Maximum array length: 100
Required range: x >= 1
Example:
[1, 2, 3]

Response

Success

​
campaign_id
string<uuid>
required

The unique identifier for the notification campaign.

​
failure_count
integer<int32>
required

The number of notifications that failed to deliver.

​
not_attempted_count
integer<int32>
required

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

​
success_count
integer<int32>
required

The number of notifications successfully delivered.

​
retryable_fids
integer<int32>[]

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

The unique identifier of a farcaster user or app (unsigned integer)

Required range: x >= 0