Farcaster Mini Apps

https://miniapps.farcaster.xyz/docs/specification#notifications
Admin
Farcaster Mini Apps are web applications designed to render within Farcaster clients, enabling rich...
Tokens:4,187
Snippets:17
Trust Score:9.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Farcaster Mini App Manifest Example

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

An example JSON object representing a Farcaster Mini App's manifest. This includes essential metadata for distributing the app, such as name, icon, URLs, and splash screen configuration.

```json
{
  "version": "1",
  "name": "Yoink!",
  "iconUrl": "https://yoink.party/logo.png",
  "homeUrl": "https://yoink.party/framesV2/",
  "imageUrl": "https://yoink.party/framesV2/opengraph-image",
  "buttonTitle": "🚩 Start",
  "splashImageUrl": "https://yoink.party/logo.png",
  "splashBackgroundColor": "#f5f0ec",
  "webhookUrl": "https://yoink.party/api/webhook"
}
```

--------------------------------

### Farcaster Signature Example

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

An example of a Farcaster signature object, including base64 encoded header, payload, and signature. This is used for verifying the author and domain of a Farcaster Mini App.

```json
{
  "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0",
  "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9",
  "signature": "D7urCIelYBtFc12UkEw/VOE1rkGKMdmDqAP/6s7sLWNfjhyug8pQCTM68XVJ8Gal6eBZxvtFE4RpVwqDtnLrzhs="
}
```

--------------------------------

### Farcaster Mini App Manifest Example

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

This JSON object represents a valid `farcaster.json` manifest file. It includes details about account association for signing and information about the Mini App itself, such as its version, name, URLs, and button titles. This manifest is crucial for Farcaster clients to correctly display and interact with the Mini App.

```json
{
  "accountAssociation": {
    "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0",
    "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9",
    "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi"
  },
  "miniapp": {
    "version": "1",
    "name": "Yoink!",
    "iconUrl": "https://yoink.party/logo.png",
    "homeUrl": "https://yoink.party/framesV2/",
    "imageUrl": "https://yoink.party/framesV2/opengraph-image",
    "buttonTitle": "🚩 Start",
    "splashImageUrl": "https://yoink.party/logo.png",
    "splashBackgroundColor": "#f5f0ec",
    "webhookUrl": "https://yoink.party/api/webhook"
  }
}
```

--------------------------------

### Farcaster Mini App Manifest

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

Defines the structure of the `farcaster.json` manifest file required for a Farcaster Mini App. This includes account association details and Mini App configuration.

```APIDOC
## GET /websites/miniapps_farcaster_xyz-docs-specification/farcaster.json

### Description
This endpoint returns the `farcaster.json` manifest for a Mini App. The manifest contains essential configuration details for the Mini App, including account association and application-specific settings.

### Method
GET

### Endpoint
`/websites/miniapps_farcaster_xyz-docs-specification/farcaster.json`

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **accountAssociation** (object) - Contains header, payload, and signature for account verification.
  - **header** (string) - Base64url encoded header.
  - **payload** (string) - Base64url encoded payload.
  - **signature** (string) - Base64url encoded signature.
- **miniapp** (object) - Contains configuration details for the Mini App.
  - **version** (string) - The version of the Mini App.
  - **name** (string) - The display name of the Mini App.
  - **iconUrl** (string) - URL for the Mini App's icon.
  - **homeUrl** (string) - The base URL for the Mini App.
  - **imageUrl** (string) - URL for the Mini App's preview image.
  - **buttonTitle** (string) - The title for the call-to-action button.
  - **splashImageUrl** (string) - URL for the Mini App's splash screen image.
  - **splashBackgroundColor** (string) - Background color for the splash screen.
  - **webhookUrl** (string) - The URL for receiving server events.

#### Response Example
```json
{
  "accountAssociation": {
    "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0",
    "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9",
    "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi"
  },
  "miniapp": {
    "version": "1",
    "name": "Yoink!",
    "iconUrl": "https://yoink.party/logo.png",
    "homeUrl": "https://yoink.party/framesV2/",
    "imageUrl": "https://yoink.party/framesV2/opengraph-image",
    "buttonTitle": "🚩 Start",
    "splashImageUrl": "https://yoink.party/logo.png",
    "splashBackgroundColor": "#f5f0ec",
    "webhookUrl": "https://yoink.party/api/webhook"
  }
}
```
```

--------------------------------

### Server Events Webhook

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

Describes the server events that Farcaster Hosts POST to a Mini App's `webhookUrl`. These events include `miniapp_added`, `miniapp_removed`, `notifications_enabled`, and `notifications_disabled`.

```APIDOC
## POST /

### Description
Hosts send server events to the Mini App's `webhookUrl` to notify the Mini App about user interactions related to adding, removing, or managing notifications for the app. These events are signed using the Farcaster Signature format.

### Method
POST

### Endpoint
`[webhookUrl from manifest]`

### Parameters
#### Query Parameters
None

#### Path Parameters
None

#### Request Body
- **header** (string) - Required - Base64url encoded header of the Farcaster Signature.
- **payload** (string) - Required - Base64url encoded payload of the event. The content varies per event type.
- **signature** (string) - Required - Base64url encoded signature of the event.

### Request Example
```json
{
  "header": "string",
  "payload": "string",
  "signature": "string"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the event reception.

#### Response Example
```json
{
  "status": "ok"
}
```

---

## Event Types

### `miniapp_added`
This event is sent when a user adds a Mini App, either through an `addMiniApp` action or from a discovery surface. It includes notification details if notifications are enabled.

#### Webhook Payload Example
```json
{
  "event": "miniapp_added",
  "notificationDetails": {
    "url": "https://api.farcaster.xyz/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}
```

#### Event Type Definition
```typescript
type EventMiniAppAddedPayload = {
  event: 'miniapp_added';
  notificationDetails?: {
    url: string;
    token: string;
  };
};
```

---

### `miniapp_removed`
This event is triggered when a user removes a Mini App. Notification tokens associated with this app for the user become invalid.

#### Webhook Payload Example
```json
{
  "event": "miniapp_removed"
}
```

---

### `notifications_disabled`
Sent when a user disables notifications for a Mini App. Any existing notification tokens for that app and user are invalidated.

#### Webhook Payload Example
```json
{
  "event": "notifications_disabled"
}
```

---

### `notifications_enabled`
This event occurs when a user re-enables notifications for a Mini App. It includes new `notificationDetails` (URL and token) for sending notifications.

#### Webhook Payload Example
```json
{
  "event": "notifications_enabled",
  "notificationDetails": {
    "url": "https://api.farcaster.xyz/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}
```

#### Event Type Definition
```typescript
type EventNotificationsEnabledPayload = {
  event: 'notifications_enabled';
  notificationDetails: {
    url: string;
    token: string;
  };
};
```
```

--------------------------------

### Farcaster Mini App Embed JSON Schema

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

Defines the structure of the JSON object used in `fc:miniapp` meta tags. It includes fields for version, image URL, button details (title, action type, name, URL, splash image, background color), and constraints for each property.

```json
{
  "version": "1",
  "imageUrl": "https://yoink.party/framesV2/opengraph-image",
  "button": {
    "title": "🚩 Start",
    "action": {
      "type": "launch_frame",
      "name": "Yoink!",
      "url": "https://yoink.party/framesV2",
      "splashImageUrl": "https://yoink.party/logo.png",
      "splashBackgroundColor": "#f5f0ec"
    }
  }
}
```

--------------------------------

### POST /notifications

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

Send a notification to one or more users who have enabled notifications in the Farcaster app. The Mini App server uses a provided authentication token and a notification URL to push notifications.

```APIDOC
## POST /notifications

### Description
Sends a notification to specified users via their Farcaster client. This endpoint is intended for use by Mini App servers.

### Method
POST

### Endpoint
`/notifications` (This is a conceptual endpoint, the actual URL is provided dynamically as `notificationUrl`)

### Parameters
#### Query Parameters
* **notificationUrl** (string) - Required - The URL provided by the Farcaster client to which the notification request should be sent.

#### Request Body
- **notificationId** (string) - Required - An identifier for the notification, used with FID for idempotency. Max length: 128 characters.
- **title** (string) - Required - The title of the notification. Max length: 32 characters.
- **body** (string) - Required - The main content of the notification. Max length: 128 characters.
- **targetUrl** (string) - Required - The URL to open when the user clicks the notification. Must be on the same domain as the Mini App. Max length: 1024 characters.
- **tokens** (string[]) - Required - An array of notification tokens for the intended recipients. Max 100 tokens.

### Request Example
```json
{
  "notificationId": "notification-abc-123",
  "title": "New Update Available!",
  "body": "Check out the latest features in our Mini App.",
  "targetUrl": "https://your-mini-app.com/updates",
  "tokens": [
    "token1",
    "token2"
  ]
}
```

### Response
#### Success Response (200)
- **successfulTokens** (string[]) - Tokens for which the notification was successfully sent.
- **invalidTokens** (string[]) - Tokens that are no longer valid and should not be used again.
- **rateLimitedTokens** (string[]) - Tokens that exceeded rate limits; the notification can be retried later.

#### Response Example
```json
{
  "successfulTokens": [
    "token1"
  ],
  "invalidTokens": [],
  "rateLimitedTokens": [
    "token2"
  ]
}
```

### Idempotency
Requests must be deduplicated using `(FID, notificationId)` as an idempotency key, valid for 24 hours.

### Rate Limits
Host servers should impose rate limits per `token`:
* 1 notification per 30 seconds per `token`
* 100 notifications per day per `token`
```

--------------------------------

### Farcaster Mini App Embed Meta Tags

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

Specifies the meta tags required for a Mini App URL to be recognized as a Mini App Embed. It supports both `fc:miniapp` for new embeds and `fc:frame` for backward compatibility with legacy Mini Apps. These tags contain a stringified JSON object defining the embed's properties.

```html
<meta name="fc:miniapp" content="<stringified Embed JSON>" />
<!-- For backward compatibility of legacy Mini Apps -->
<meta name="fc:frame" content="<stringified Embed JSON>" />
```

--------------------------------

### Farcaster Server Event Signature Format

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

This structure represents the common format for server events sent to a Mini App's webhook URL. It includes a header, payload, and signature, all base64url encoded. The header and payload can be decoded to JSON, with the payload content varying based on the specific event type.

```json
{
  header: string;
  payload: string;
  signature: string;
}
```

--------------------------------

### Farcaster Signature Payload Schema

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

Defines the JSON structure for a Farcaster signature payload used to verify domain ownership. It requires a 'domain' field that must match the FQDN of the hosted Mini App.

```json
{
  "domain": "string";
}
```

--------------------------------

### miniapp_added Server Event Payload

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

This JSON payload is sent to the Mini App's webhook when a user adds the Mini App. It includes the event type and optional `notificationDetails`, which contain the URL and token for sending notifications. This event signifies that the app has been favorited and notifications are enabled.

```json
{
  "event": "miniapp_added",
  "notificationDetails": {
    "url": "https://api.farcaster.xyz/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}
```

--------------------------------

### miniapp_removed Server Event Payload

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

This JSON payload is sent to the Mini App's webhook when a user removes the Mini App. It simply contains the `event` field set to 'miniapp_removed'. This indicates that any previously issued notification tokens for this user and app are now invalid.

```json
{
  "event": "miniapp_removed"
}
```

--------------------------------

### miniapp_added TypeScript Type Definition

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

This TypeScript type definition describes the structure of the `miniapp_added` event payload. It specifies the `event` field as 'miniapp_added' and an optional `notificationDetails` object conforming to the `MiniAppNotificationDetails` type.

```typescript
type EventMiniAppAddedPayload = {
  event: 'miniapp_added';
  notificationDetails?: MiniAppNotificationDetails;
};
```

--------------------------------

### notifications_enabled Server Event Payload

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

This JSON payload is sent to the Mini App's webhook when a user enables notifications for the Mini App. It includes the `event` field as 'notifications_enabled' and the `notificationDetails`, providing the `url` and `token` for sending notifications.

```json
{
  "event": "notifications_enabled",
  "notificationDetails": {
    "url": "https://api.farcaster.xyz/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}
```

--------------------------------

### notifications_enabled TypeScript Type Definition

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

This TypeScript type definition outlines the structure for the `notifications_enabled` event payload. It specifies the `event` as 'notifications_enabled' and requires a `notificationDetails` object conforming to the `MiniAppNotificationDetails` type.

```typescript
type EventNotificationsEnabledPayload = {
  event: 'notifications_enabled';
  notificationDetails: MiniAppNotificationDetails;
};
```

--------------------------------

### notifications_disabled Server Event Payload

Source: https://miniapps.farcaster.xyz/docs/specification#notifications/index

This JSON payload is sent to the Mini App's webhook when a user disables notifications for the Mini App. It contains the `event` field set to 'notifications_disabled'. This signals that notification tokens for this user and app are no longer valid.

```json
{
  "event": "notifications_disabled"
}
```
Tokens:
Raw