Check a private message
Call it for every private message to an account whose chatbot is your bot, and with `from: "account"` for messages written from the account.
Questions? [email protected]
Call it for every private message to an account whose chatbot is your bot, and with `from: "account"` for messages written from the account.
Questions? [email protected]
/api/external/v1/chat-gate/checkalso served at /api/external/chat-gate/checkNewCall it for every private message to an account whose chatbot is your bot, and with from: "account" for messages written from the account.
On action: "ask" send ask.text with ask.replyMarkup (plain text, no parse_mode) through the business connection, pin it silently, unpin ask.unpinMessageId and report the sent message to POST /chat-gate/asks/{id}. The ask is already claimed: until you report it failed, the fan isn’t asked again for 12 hours.
locked says the fan would have to pay: keep automated replies out of the chat. On a timeout or 5xx, let the message stand. See Pay to Chat from your own chatbot.
Send service: true for service messages (something was pinned, the history was cleared): Telegram shows your own pin as a message from the account, and without the flag it would silence the gate for 12 hours. dryRun: true decides without changing anything, for comparing our answer with a gate you already run.
Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.
For a creator you manage or onboarded
POST /api/external/v1/creators/{creatorId}/chat-gate/check — an agency's own key for a creator or AI persona it manages (needs canManageDrops), or your app owner's own key for an account your app onboarded. The X-Dropfans-Account header still works but is deprecated. See Acting for a creator.
Content type: application/json
| Name | Type | Required | Description |
|---|---|---|---|
account | string | Required | Telegram user id of the creator’s account (the business connection’s user.id). |
fan | string | Required | Telegram user id of the fan (the private chat’s id). |
from | string | Optional | account for a message written from the account itself: nobody is asked in that chat for 12 hours.One of: fan, accountDefault: "fan" |
service | boolean | Optional | A service message (a pin notice and the like), whoever it is from: never asks and never counts as the account writing. reason is service. |
dryRun | boolean | Optional | Decide only: no ask is claimed, nothing is stamped, and ask is null even when action is ask. The response carries dryRun: true. |
languageCode | string | Optional | The fan’s Telegram language_code, for the ask’s language. |
offline | boolean | Optional | An away, greeting or scheduled message (is_from_offline): not someone talking. |
quiet | boolean | Optional | A person has this chat: never ask (locked is still reported). |
accountName | string | Optional | The account’s first name for the ask; defaults to the one you reported. |
{
"account": "5550001111",
"fan": "48213377",
"from": "fan",
"languageCode": "en"
}| Name | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
dryRun | boolean | Only on a dry run: true. | ||||||||||||||||||
mode | string | Who may chat: everyone, fans who paid (tip or drop) or subscribed, or subscribers only. One of: EVERYONE, PAY, SUB | ||||||||||||||||||
payScope | string | Pay to Chat: ONCE = paid once, open for good; PER_CONVERSATION = a conversation can be ended and the fan pays again.One of: ONCE, PER_CONVERSATION | ||||||||||||||||||
source | string | account: that Telegram account has its own setting; creator: the creator’s applies.One of: account, creator | ||||||||||||||||||
status | string | open the gate is off; team the creator, their agency or Dropfans staff; exempt on the Accept for list; subscribed / paid let in by money; opened an app opened the chat itself ([POST /chat-gate/fans/open](/developers/reference/open-chats)); locked would be asked.One of: open, team, exempt, subscribed, paid, opened, locked | ||||||||||||||||||
locked | boolean | The fan would have to pay: keep automated replies out. | ||||||||||||||||||
action | string | Send the ask, or nothing. One of: none, ask | ||||||||||||||||||
reason | string | Why. One of: asked, mode_off, no_subscription_on_sale, not_locked, account_wrote, self, service, quiet, creator_talking, asked_recently, no_username | ||||||||||||||||||
ask | object | null | Set on action: "ask", except on a dry run.Show child attributes
|
{
"mode": "PAY",
"payScope": "ONCE",
"source": "creator",
"status": "locked",
"locked": true,
"action": "ask",
"reason": "asked",
"ask": {
"id": "ask_3f2a9c1d0b8e7f6a5c4d3e2f",
"text": "❌ Mia has Pay to Chat turned on. Send a tip of any amount to start a conversation and they'll be notified right away 💬",
"replyMarkup": {
"inline_keyboard": [
[
{
"text": "💵 Send a tip",
"url": "https://t.me/DropfansBot/app?startapp=t_mia"
}
]
]
},
"pin": true,
"unpinMessageId": null,
"locale": "en"
}
}| Status | Body | When |
|---|---|---|
| 400 | {"error":"account must be a Telegram user id (digits, as a string)","code":"invalid_telegram_id"} | `account` is missing or not a Telegram user id. |
| 400 | {"error":"fan must be a Telegram user id (digits, as a string)","code":"invalid_telegram_id"} | `fan` is missing or not a Telegram user id. |
| 400 | {"error":"from must be 'fan' or 'account'","code":"invalid_request"} | A bad `from`. |
| 401 | {"error":"Unauthorized","code":"unauthorized"} | Missing or invalid API key. |
| 403 | {"error":"This endpoint needs a key bound to an app with the chat_gate API category enabled — personal keys cannot use it.","code":"app_key_required","category":"chat_gate"} | A personal key: the chat gate answers back through app webhooks. |
| 409 | {"error":"The chat gate is for creator accounts.","code":"not_a_creator"} | The account is a fan account, suspended or banned. |
| 503 | {"error":"The chat gate is not available right now. Let the message through.","code":"unavailable"} | Something failed on our side. Fail open: let the message stand. |
| 400 | {"error":"X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.","code":"invalid_account_header"} | `X-Dropfans-Account` is not an account id. |
| 400 | {"error":"X-Dropfans-Account names a different account than the path — send one or the other.","code":"account_mismatch"} | Called under /v1/creators/{creatorId}/ with an `X-Dropfans-Account` naming another account. |
| 403 | {"error":"This key cannot act for that account.","code":"account_not_managed"} | The creator in the path (or `X-Dropfans-Account`) is one this key cannot act for: no ACCEPTED management by your agency and not an account your app onboarded (or it no longer holds a key bound to your app), a key minted for one creator, or someone is suspended, banned or deleted. An unknown id gets the same answer. |
| 403 | {"error":"The agency does not have permission for this on that account.","code":"permission_denied","permission":"canManageDrops"} | For a managed creator: the agency lacks `canManageDrops` on that account. |
| 403 | {"error":"This app does not have the chat_gate API category enabled. Contact support to enable it.","code":"api_category_disabled","category":"chat_gate"} | Your app has the Pay to Chat [API category](/developers/concepts/api-categories) switched off (the default for new apps). |
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.
curl -X POST "https://www.dropfans.io/api/external/v1/chat-gate/check" \
-H "Authorization: Bearer $DROPFANS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"account": "5550001111",
"fan": "48213377",
"from": "fan",
"languageCode": "en"
}'const res = await fetch(`https://www.dropfans.io/api/external/v1/chat-gate/check`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"account": "5550001111",
"fan": "48213377",
"from": "fan",
"languageCode": "en"
}),
});
console.log(await res.json());import os
import requests
res = requests.post(
"https://www.dropfans.io/api/external/v1/chat-gate/check",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
json={
"account": "5550001111",
"fan": "48213377",
"from": "fan",
"languageCode": "en",
},
)
print(res.json())