API reference

Update Telegram notification settings

An action-dispatch endpoint — the `action` field picks one of three operations:

View as MarkdownUpdated Aug 19, 2026

PUT/api/external/notifications

An action-dispatch endpoint — the action field picks one of three operations:

save-handle — store the creator's Telegram @handle (telegramHandle, leading @ stripped).
disconnect — clear the personal chat, the group, or both (type: "personal" | "group" | "all").
add-group — register a group/channel by chat id (groupChatId, e.g. "-100…"). The bot must already be a member: the id is verified against Telegram before saving, and private-chat ids are rejected.

This rewrites the creator's live notification settings

The same fields power the creator's own Dropfans → Telegram sale notifications. Changing them here changes where the creator's notifications go — including notifications your app has nothing to do with. Only call this when the creator explicitly asked for it.

Authentication

Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.

Request body

Content type: application/json

Name	Type	Required	Description
`action`	string	Required	Which operation to perform. One of: `save-handle`, `disconnect`, `add-group`
`telegramHandle`	string	Optional	save-handle only: the @handle (leading @ is stripped).
`type`	string	Optional	disconnect only: what to clear. One of: `personal`, `group`, `all`
`groupChatId`	string	Optional	add-group only: the Telegram chat id of a group/channel the bot is in.

Save the creator’s handle

{
  "action": "save-handle",
  "telegramHandle": "valeria_tg"
}

{
  "action": "add-group",
  "groupChatId": "-1001234567890"
}

Disconnect everything

{
  "action": "disconnect",
  "type": "all"
}

Responses

200Action applied. save-handle echoes `telegramHandle`; add-group echoes `groupName`; disconnect returns `{success:true}` alone.

Name	Type	Description
`success`	boolean	Always true.
`telegramHandle`	string	save-handle only: the stored handle (without @).
`groupName`	string	add-group only: the group’s title as Telegram reports it.

Example response

{
  "success": true,
  "groupName": "Valeria sales"
}

Errors

Status	Body	When
400	`{"error":"Invalid JSON body"}`	The body is not valid JSON.
400	`{"error":"telegramHandle is required"}`	save-handle without a handle.
400	`{"error":"Invalid telegram handle"}`	save-handle with an empty handle after stripping @.
400	`{"error":"type must be \"personal\", \"group\", or \"all\""}`	disconnect with a bad type.
400	`{"error":"groupChatId is required"}`	add-group without a chat id.
400	`{"error":"Could not find this group. Make sure the bot has been added to the group first."}`	Telegram does not know the chat, or the bot is not a member.
400	`{"error":"This ID belongs to a private chat, not a group or channel."}`	add-group with a personal chat id.
400	`{"error":"Unknown action"}`	`action` is none of the three.
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.

Rate limiting

Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.

Code samples

curl -X PUT "https://www.dropfans.io/api/external/notifications" \
  -H "Authorization: Bearer $DROPFANS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "save-handle",
  "telegramHandle": "valeria_tg"
}'

const res = await fetch(`https://www.dropfans.io/api/external/notifications`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "action": "save-handle",
    "telegramHandle": "valeria_tg"
  }),
});
console.log(await res.json());

import os
import requests

res = requests.put(
    "https://www.dropfans.io/api/external/notifications",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    json={
        "action": "save-handle",
        "telegramHandle": "valeria_tg",
    },
)
print(res.json())

← Previous

Read the Telegram notification status

Questions? [email protected]