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
}Notifications
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
/
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
API key to authorize requests
Body
application/json
Show child attributes
Show child attributes
Filters to apply to the target_fids set. All filters are additive, so only users matching all filters will be notified.
Show child attributes
Show child attributes
Example:
{
"exclude_fids": [2, 8988],
"following_fid": 3,
"minimum_user_score": 0.5,
"near_location": {
"latitude": 37.774929,
"longitude": -122.419418,
"radius": 1000
}
}
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:
100Required range:
x >= 1Example:
[1, 2, 3]
Response
Success
The unique identifier for the notification campaign.
The number of notifications that failed to deliver.
The number of notifications not attempted (e.g., disabled tokens, invalid tokens).
The number of notifications successfully delivered.
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 >= 0Related topics
Sending NotificationsSend Notifications to Mini App UserspublishFrameNotificationsSpecificationUsing Neynar to build mini appsWas this page helpful?
⌘I