send_holder_broadcast
Write · Sign-in needed
Send a message to your token's holders
Sends a message from the token page id to its subscribed holders: in-app always, plus whichever of push, email, sms, telegram, discord and xmtp you list and each holder has turned on. It goes out at once unless you set scheduledAt. A sent message cannot be recalled. Only the page's owner or a manager can send; there is nothing to sign.
Before sending, call GET /api/v2/broadcasts/{id}/limits (how many sends are left) and GET /api/v2/broadcasts/{id}/delivery (whether Telegram and Discord also post publicly). With no holder group and no segment, telegram/discord also post once in the token's public community room and Discord webhook; with either, they are DMs only.
Limits: the Free plan sends 1 per rolling 7 days per token; paid plans have no plan limit, but every token is held to a safety ceiling (3 an hour and 10 a day by default, 1 a day in a token's first week), and both answer 429 with resetsAt. Up to 50,000 recipients per send, largest holders first. A new token's first send to more than 500 holders is held for review: it answers 200 with recipientCount: 0 and goes out once released.
Common mistakes: wallet must be one of your own signed-in wallets (it is recorded as the sender); channels must include inapp; pass crownChain whenever the same token id exists on more than one chain, or the message can reach the wrong token's holders or none. Every link and image is screened: links on a blocklist and images not on IPFS or Arweave answer 422.
| Reads or changes | Changes data; some changes cannot be undone |
| Sign-in | Yes |
| Scope | api:write |
| Calls | POST /api/v2/broadcasts/{id} (API Explorer) |
Input
JSON Schema, as the server serves it.
{
"additionalProperties": false,
"properties": {
"accessTierId": {
"description": "Make the message holders-only for this holder group on the token page's feed. Needs the page owner's paid plan.",
"type": [
"string",
"null"
]
},
"body": {
"maxLength": 2000,
"type": "string"
},
"chainScope": {
"description": "Chain key the broadcast is anchored on; omit for off-chain",
"pattern": "^[a-z0-9-]{1,32}$",
"type": "string"
},
"channels": {
"description": "Must include `inapp`. Defaults to `[\"inapp\"]`.",
"items": {
"enum": [
"inapp",
"push",
"email",
"xmtp",
"sms",
"telegram",
"discord"
],
"type": "string"
},
"type": "array"
},
"crownChain": {
"description": "Chain key of the token page. Send it whenever the token id exists on more than one chain.",
"pattern": "^[a-z0-9-]{1,32}$",
"type": "string"
},
"id": {
"description": "The token page's id (the registration's numeric token id)",
"format": "int64",
"minimum": 1,
"type": "integer"
},
"imageUrl": {
"description": "HTTPS, on IPFS or Arweave",
"type": "string"
},
"linkUrl": {
"description": "HTTPS",
"type": "string"
},
"richContent": {
"description": "Rich-text body as the composer produces it",
"type": "object"
},
"scheduledAt": {
"description": "Send later instead of now; at least 5 minutes ahead",
"format": "date-time",
"type": "string"
},
"segments": {
"description": "Narrow to holders in ANY of these segments (within the holder group, if one is set)",
"items": {
"enum": [
"all",
"new_7d",
"churned",
"reduced_50",
"whales",
"top_10",
"top_25",
"top_50",
"top_100"
],
"type": "string"
},
"type": "array"
},
"signature": {
"deprecated": true,
"description": "Ignored",
"type": "string"
},
"sourceType": {
"default": "manual",
"type": "string"
},
"tierIds": {
"description": "Holder groups to send to (any of them). Omit for every subscribed holder; an empty list is refused. Needs the page owner's paid plan.",
"items": {
"type": "string"
},
"type": "array"
},
"timestamp": {
"deprecated": true,
"description": "Ignored",
"format": "int64",
"type": "integer"
},
"title": {
"maxLength": 100,
"type": "string"
},
"type": {
"enum": [
"update",
"alert"
],
"type": "string"
},
"wallet": {
"description": "The sender; must be one of the caller's signed-in wallets",
"type": "string"
}
},
"required": [
"body",
"id",
"title",
"type",
"wallet"
],
"type": "object"
}Example
A tools/call request:
{
"name": "send_holder_broadcast",
"arguments": {
"body": "value",
"id": 1,
"title": "value",
"type": "update",
"wallet": "value"
}
}