Skip to content

docs for localized notifications #487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
michalstruck wants to merge 7 commits into
base: main
Choose a base branch
from
Open

docs for localized notifications #487

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
cd1b641
docs for localized notifications
michalstruck Aug 13, 2025
bf87d27
add table and redact
michalstruck Aug 13, 2025
a2d7bc7
alphabetic order
michalstruck Aug 13, 2025
0b2167d
restructure
michalstruck Aug 13, 2025
e6cb11e
example
michalstruck Aug 13, 2025
5fec8fd
cspell
michalstruck Aug 13, 2025
8edf3fb
fix link
michalstruck Aug 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 42 additions & 10 deletions cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,33 @@
"enabled": true,
"language": "en-US",
"allowCompoundWords": true,
"dictionaries": ["typescript", "node", "npm", "html"],
"enabledLanguageIds": ["typescript", "typescriptreact", "javascript", "markdown", "yaml", "json"],
"ignorePaths": ["**/node_modules", "package.json", "pnpm-lock.yaml"],
"ignoreWords": ["signup"],
"ignoreRegExpList": ["app_[a-z0-9]+", "jwk_[a-z0-9]+", "ey[a-zA-Z0-9]+\\.ey[a-zA-Z0-9]+\\.[a-zA-Z0-9]+"],
"dictionaries": [
"typescript",
"node",
"npm",
"html"
],
"enabledLanguageIds": [
"typescript",
"typescriptreact",
"javascript",
"markdown",
"yaml",
"json"
],
"ignorePaths": [
"**/node_modules",
"package.json",
"pnpm-lock.yaml"
],
"ignoreWords": [
"signup"
],
"ignoreRegExpList": [
"app_[a-z0-9]+",
"jwk_[a-z0-9]+",
"ey[a-zA-Z0-9]+\\.ey[a-zA-Z0-9]+\\.[a-zA-Z0-9]+"
],
"words": [
"abitype",
"anonymized",
Expand All @@ -17,19 +39,25 @@
"CCIP",
"clippy",
"clsx",
"Completionist",
"countup",
"Csvg",
"defi",
"devs",
"DEXABI",
"diarias",
"disabletxpoolgossip",
"Disponibles",
"Emoy",
"enode",
"erigon",
"Eruda",
"están",
"ETHSF",
"Fbridge",
"Fdashboard",
"gamification",
"Gamification",
"gigagas",
"groth",
"gtag",
Expand All @@ -48,6 +76,7 @@
"JWT",
"keccak",
"lazo",
"listas",
"llms",
"localised",
"MateoSauton",
Expand All @@ -66,6 +95,7 @@
"omnichain",
"onramps",
"Onramps",
"Optimising",
"Orbz",
"PAYG",
"Paylodfor",
Expand All @@ -75,22 +105,28 @@
"Pimlico",
"Pimlico's",
"POAP",
"prêtes",
"Pyth",
"Qppp",
"qrcode",
"quix",
"quotidiennes",
"Rabby",
"recma",
"Recompensas",
"Récompenses",
"rehype",
"reinitializes",
"Rustification",
"Salut",
"SDAI",
"Sepolia",
"shiki",
"Sismo",
"SIWE",
"slugified",
"snarkyjs",
"sont",
"testid",
"timestamptz",
"tute",
Expand All @@ -109,10 +145,6 @@
"zeth",
"zkhack",
"zrok",
"zustand",
"Completionist",
"gamification",
"Gamification",
"Optimising"
"zustand"
]
}
11 changes: 8 additions & 3 deletions src/pages/mini-apps/notifications/features-and-guidelines.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,20 @@ the recipient's username.
-d '{
"app_id": "app_id",
"wallet_addresses": ["0x123", "0x456"],
"title": "title",
"message": "🧑‍🍳 We're cooking something special for you ${username}",
"localisations": [
{
"language": "en",
"title": "title",
"message": "🧑‍🍳 We're cooking something special for you ${username}"
}
],
"mini_app_path": "worldapp://mini-app?app_id=[app_id]&path=[path]"
}'
```

</CodeGroup>

when sent to users, the messagebecomes:<br />
when sent to users, the message becomes:<br />
`🧑‍🍳 We're cooking something special for you mistico`<br />
`🧑‍🍳 We're cooking something special for you tute`<br />
`🧑‍🍳 We're cooking something special for you struck`<br />
Expand Down
50 changes: 48 additions & 2 deletions src/pages/mini-apps/notifications/how-to-send-notifications.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import { Link } from '@/components/Link'

# Send Notifications

Please take a minute to read the [Features & Guidelines](/mini-apps/notifications/features-and-guidelines).
Expand All @@ -7,12 +9,16 @@ To send notifications to users you need to:

- Request permission in the Developer Portal Advanced settings, for your mini app,
- request permission to send notifications from the user, via MiniKit (see [Request Permission](/mini-apps/commands/request-permission)),
- actually send the notification using our API or the Developer Portal (see [How To Send Notifications](/mini-apps/notifications/how-to-send-notifications)).
- actually send the notification using our API or the Developer Portal.

Notifications are queued on our servers, users may not receive them immediately.

## Manually sending notifications from Developer Portal

<Note type="info">
This form doesn't support localized notifications yet. To take advantage of localizations, use the API.
</Note>

You can send notifications to multiple wallet addresses (up to a thousand) directly from the Developer Portal.

<div style={{ maxWidth: '50%' }}>
Expand All @@ -23,7 +29,47 @@ Use the form to input addresses, and content details. Once you click the `Send`

## Calling the send-notification endpoint

You can also call our API to send notifications. For detailed information, see the [API Reference](/mini-apps/reference/api#send-notification).
The API endpoint provides capabilities for sending notifications programmatically. These notifications can be localized,
which ensures you reach users in their preferred language. This results in a dramatically higher engagement rate.

### Localization made simple

```javascript
const response = await fetch('https://developer.worldcoin.org/api/v2/minikit/send-notification', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
app_id: 'your_app_id',
wallet_addresses: ['0x123...', '0x456...'],
localisations: [
{
language: 'en',
title: '🎉 Rewards Available',
message: 'Hey ${username}, your daily rewards are ready!',
},
{
language: 'es',
title: '🎉 Recompensas Disponibles',
message: 'Hola ${username}, tus recompensas diarias están listas!',
},
{
language: 'fr',
title: '🎉 Récompenses Disponibles',
message: 'Salut ${username}, vos récompenses quotidiennes sont prêtes!',
},
],
mini_app_path: 'worldapp://mini-app?app_id=your_app_id&path=/rewards',
}),
})
```

Each user automatically receives the notification in their preferred language.
If their language isn't included in your localizations, you'll receive a specific `reason` in the response.

For complete API documentation including all supported languages and response formats, see the [API Reference](/mini-apps/reference/api#send-notification).

## Testing

Expand Down
79 changes: 67 additions & 12 deletions src/pages/mini-apps/reference/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,25 +154,48 @@ fetch(apiUrl, {

## Send Notification{{ tag: "POST", label: "https://developer.worldcoin.org/api/v2/minikit/send-notification" }}

This endpoint lets you send notifications to users of your mini app and requires an `api_key`.
This endpoint lets you send localized notifications to users of your mini app and requires an `api_key`.

### How do localizations work?

The user's language is available to you when they access your mini app
(via [Navigator](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language)).

All you need to do is provide localizations. Our backend will automatically infer which language is preferred by the user.
Currently we support only a subset of languages, with plans to expand. Find the entire list [here](/mini-apps/reference/api#supported-languages).
You can only specify languages that we support.

- If a user prefers a language that we don't currently support, we will deliver the notification in English.
- If you don't specify a localization for the user's preferred language, the notification will not be delivered.
The response will include a specific `reason` to inform you of this.

<Row>
<Col>
### Body Params

You are required to either specify both `title` and `message` OR `localisations`.

<Properties>
<Property name="wallet_addresses" type="string[]" required={true}>
<Property name="wallet_addresses" type="string[]" required>
The `wallet_addresses` is an array of wallet addresses to send the notification to. Users must have opted in to notifications for your app. Max 1000 users per call.
</Property>
<Property name="title" type="string" required={true}>
The `title` is the title of the notification. It should be 30 characters or less. May contain emojis.
<Property name="localisations" type="object[]">
`localisations` is an array of objects with properties:
- `language` (string, required): The language of the notification.
- `title` (string, required): The localized title of the notification.
- `message` (string, required): The localized message of the notification.
It's required to provide at least the `en` language.
</Property>
<Property name="message" type="string" required={true}>
The `message` is the message of the notification. It should be 200 characters or less. You can include the special variable `${username}` in your message, which will be replaced with the actual username of the recipient when the notification is delivered.
<Property name="title" type="string">
Note: This will not localize your notifications. The `title` is the title of the notification. It should be 30 characters or less. May contain emojis.
</Property>
<Property name="mini_app_path" type="string" required={true}>
<Property name="message" type="string">
Note: This will not localize your notifications. The `message` is the message of the notification. It should be 200 characters or less. You can include the special variable `${username}` in your message, which will be replaced with the actual username of the recipient when the notification is delivered.
</Property>
<Property name="mini_app_path" type="string" required>
The `mini_app_path` is the url encoded path of the mini app where your notification should link to when the user clicks on it. <br/><br/> Should be of the format `worldapp://mini-app?app_id=[app_id]&path=[path]` (path is optional).
</Property>
<Property name="app_id" type="string" required={true}>
<Property name="app_id" type="string" required>
The `app_id` is the identifier of the app initiating the transaction.
</Property>
</Properties>
Expand All @@ -191,7 +214,7 @@ This endpoint lets you send notifications to users of your mini app and requires
curl -X POST "https://developer.worldcoin.org/api/v2/minikit/send-notification" \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{"app_id": "app_id", "wallet_addresses": ["0x123", "0x456"], "title": "title", "message": "Hello ${username}, your transaction is complete!", "mini_app_path": "mini_app_path"}'
-d '{"app_id": "app_id", "wallet_addresses": ["0x123", "0x456"], "localisations": [{"language": "en", "title": "title", "message": "Hello ${username}, your transaction is complete!"}], "mini_app_path": "mini_app_path"}'
```
```js
fetch(apiUrl, {
Expand All @@ -202,8 +225,13 @@ This endpoint lets you send notifications to users of your mini app and requires
body: JSON.stringify({
app_id: "app_id",
wallet_addresses: ["0x123", "0x456"],
title: "title",
message: "Hello ${username}, your transaction is complete!",
localisations: [
{
language: "en",
title: "title",
message: "Hello ${username}, your transaction is complete!"
}
],
mini_app_path: "mini_app_path"
})
})
Expand Down Expand Up @@ -246,14 +274,41 @@ This endpoint lets you send notifications to users of your mini app and requires
"walletAddress": "0x444da9cab87c04a1d6f19d8b4be9aef8df26fcdd",
"sent": false,
"reason": "User has notification disabled for World App"
},
{
"walletAddress": "0x555da9cab87c04a1d6f19d8b4be9aef8df26fcdd",
"sent": false,
"reason": "User's preferred locale was not found in request"
}
]
}
```
</CodeGroup>
</Col>
</Row>
<hr/>

### Supported Languages

| Language | Code |
| ---------------------------- | -------- |
| English | `en` |
| Catalan | `ca` |
| Chinese Simplified | `zh_CN` |
| French | `fr` |
| German | `de` |
| Hindi | `hi` |
| Indonesian | `id` |
| Japanese | `ja` |
| Korean | `ko` |
| Malay | `ms` |
| Polish | `pl` |
| Portuguese | `pt` |
| Spanish | `es` |
| Spanish (Latin America) | `es_419` |
| Thai | `th` |
| Traditional Chinese (Taiwan) | `zh_TW` |

<hr />

## Get Transaction{{ tag: "GET", label: "https://developer.worldcoin.org/api/v2/minikit/transaction/{transaction_id}?app_id=&type=" }}

Expand Down