Pay to Chat from your own chatbot
Run Dropfans Pay to Chat and Sub to Chat through the Telegram chatbot your app already connects to a creator’s account: we decide and write the message, your bot sends it.
Questions? [email protected]
Run Dropfans Pay to Chat and Sub to Chat through the Telegram chatbot your app already connects to a creator’s account: we decide and write the message, your bot sends it.
Questions? [email protected]
Pay to Chat and Sub to Chat make a fan tip or subscribe on Dropfans before they chat with a creator on Telegram. Telegram lets an account have one chatbot, and only that bot sees its private messages. When the creator’s chatbot is yours, your bot carries the gate: Dropfans keeps the setting, every fan’s state and the wording, and tells your bot what to send. The creator keeps your bot and gets the same feature as with ours.
These endpoints are the chat_gate API category, off by default: ask support to switch it on. They need a key bound to your app, the creator’s own (Vault → API Connect) or your agency’s for a creator it manages.
| You want | You build |
|---|---|
| A switch in your app, nothing else | PUT /chat-gate with mode. If the creator’s chatbot is ours, our bot does the rest. |
| Your bot stays the creator’s chatbot | The relay below: check every private message, send the ask we return, handle two webhooks. |
| The message or its buttons on your own timing | POST /chat-gate/asks for one fan now, or GET /chat-gate/message for the text and links alone. |
Whichever you pick, the fan pays in the Dropfans Mini App and we decide who may chat. The wording is one fixed message per mode, in the fan’s language; only the creator’s name changes.
business_message. Call POST /chat-gate/check.action: "ask": send ask.text with ask.replyMarkup through the business connection, pin it silently, unpin ask.unpinMessageId if there is one, and report the message id to POST /chat-gate/asks/{id}.chat.unlocked to your webhook: post data.text in that chat and unpin data.unpinMessageId.locked: true in the answer means the fan would have to pay: keep your AI replies and scripts out of that chat. A person can still answer it.
On every business_connection update, tell us whose chatbot your bot is. The creator’s app then says it runs through yours, and setting changes reach you.
curl -X PUT "https://www.dropfans.io/api/external/v1/chat-gate/chatbot" \
-H "Authorization: Bearer $DROPFANS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"account":"5550001111","enabled":true,"canReply":true,"botUsername":"your_bot","accountName":"Mia"}'account is the business connection’s user.id; accountName its first_name, which the asks use.
Call check for each private message to a connected account: from the fan, and with from: "account" for ones written from the account, so nobody is asked while someone is talking to them.
// business_message handler. msg.chat.id is the fan, the connection's user.id the account.
const res = await fetch('https://www.dropfans.io/api/external/v1/chat-gate/check', {
method: 'POST',
headers: { Authorization: `Bearer ${creatorKey}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
account: String(connection.user.id),
fan: String(msg.chat.id),
from: msg.from.id === connection.user.id ? 'account' : 'fan',
offline: Boolean(msg.is_from_offline),
languageCode: msg.from.language_code,
}),
signal: AbortSignal.timeout(3000),
}).catch(() => null);
if (!res?.ok) return; // fail open: the message stands
const gate = await res.json();
if (gate.locked) skipAutoReply(msg.chat.id);
if (gate.action !== 'ask') return;
const sent = await bot.sendMessage({
business_connection_id: msg.business_connection_id,
chat_id: msg.chat.id,
text: gate.ask.text, // plain text: no parse_mode
reply_markup: gate.ask.replyMarkup,
}).catch(() => null);
await reportAsk(gate.ask.id, sent ? { messageId: sent.message_id } : { failed: true });
if (!sent) return;
await bot.pinChatMessage({ business_connection_id: msg.business_connection_id, chat_id: msg.chat.id, message_id: sent.message_id, disable_notification: true });
if (gate.ask.unpinMessageId) {
await bot.unpinChatMessage({ business_connection_id: msg.business_connection_id, chat_id: msg.chat.id, message_id: gate.ask.unpinMessageId });
}What we apply, so your bot doesn’t have to:
offline: true) don’t count.quiet: true for a chat a person has taken over: no ask, but locked is still reported.Pinning the ask makes Telegram add a “pinned a message” notice that arrives as a business_message from the account. Skip service messages, or send them with service: true. Sent as from: "account" without it, the notice counts as the creator writing and nobody is asked in that chat for 12 hours.
| Event | What your bot does |
|---|---|
chat.unlocked | Post data.text in the chat (data.account → data.fan) and unpin data.unpinMessageId. Sent once per ask, only to the app whose bot sent it. |
chat_gate.updated | The setting changed (data.account null = the creator’s). Unpin every data.unpin[] and refresh any switch you show. |
Telegram lets a chatbot answer only within 24 hours of the fan’s last message, so a late chat.unlocked may fail to post. Unpin anyway.
A chatter wants the fan asked now, or your flow has its own moment for it: POST /chat-gate/asks returns the gate’s ask for that fan at once, in the shape check uses. Send, pin and report it the same way. It skips the 12-hour wait and the quiet rules, but never asks a fan who may already chat, and it needs Pay to Chat or Sub to Chat to be on for the account (409 gate_off otherwise).
GET /chat-gate/message gives the same message without a fan, plus the tip and subscribe links on their own, each with its button label. Use it under a welcome message or in a broadcast. Nothing is tracked: no pin to manage and no report to send. The links work whether the gate is on or off; the text is only returned while it is on, because it says so.
curl "https://www.dropfans.io/api/external/v1/chat-gate/message?account=5550001111&locale=en" \
-H "Authorization: Bearer $DROPFANS_API_KEY"GET /chat-gate and PUT /chat-gate read and change the creator’s setting: mode EVERYONE, PAY or SUB. With account they read or set one Telegram account’s own, which wins over the creator’s; inherit: true drops it. The creator sets theirs in the Dropfans app too.
payScope (Pay to Chat): ONCE, the default, lets a fan who paid once chat for good. With PER_CONVERSATION, POST /chat-gate/fans/{fan}/lock ends a conversation and the fan pays again.
PUT /chat-gate/exempt sets an account’s Accept for list: fans who may always chat there. POST /chat-gate/fans/lookup gives up to 500 fans’ status at once, for a chat list.
POST /chat-gate/fans/open opens chats yourself, for payments we can’t tie to a fan’s Telegram (a drop link paid in a browser). In Pay to Chat such a fan reads opened and isn’t asked: for good with ONCE, until you end the conversation with PER_CONVERSATION.
If your app has its own Pay to Chat, you can move it over without your creators noticing:
account), its Accept for list, your bot with PUT /chat-gate/chatbot, and the chats that are open today with POST /chat-gate/fans/open. Keep writing changes to both sides.dryRun: true next to it. Nothing is claimed and no ask comes back, so fans see no difference. Look for chats you have open that we would lock.If check times out (3 seconds is plenty) or answers 5xx, let the message stand and don’t ask. Asking a fan who paid is worse than one free message. A 503 with code: "unavailable" means the same.
Next: Webhooks & polling or Broadcast one drop to many fans.