> ## Documentation Index
> Fetch the complete documentation index at: https://www.dropfans.io/developers/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

- Source: https://www.dropfans.io/developers/guides/pay-to-chat
- Section: Guides
- OpenAPI: https://www.dropfans.io/developers/openapi.json

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.

> [!NOTE] Switched on per app
> These endpoints are the `chat_gate` [API category](https://www.dropfans.io/developers/concepts/api-categories.md), 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.

## Three ways to use it

| You want | You build |
| --- | --- |
| A switch in your app, nothing else | [PUT /chat-gate](https://www.dropfans.io/developers/reference/update-chat-gate.md) 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](https://www.dropfans.io/developers/reference/request-chat-ask.md) for one fan now, or [GET /chat-gate/message](https://www.dropfans.io/developers/reference/get-chat-gate-message.md) 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.

## How it fits together

1. A fan writes to the creator. Your bot gets a `business_message`. Call [POST /chat-gate/check](https://www.dropfans.io/developers/reference/check-chat-message.md).
2. On `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}](https://www.dropfans.io/developers/reference/report-chat-ask.md).
3. The fan taps the button. It opens the Dropfans Mini App, where they pay signed in with their Telegram.
4. We send [`chat.unlocked`](https://www.dropfans.io/developers/webhooks/overview.md) 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.

## 1. Report your bot

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.

```bash
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.

## 2. Check every private message

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.

```javascript tab="Node"
// 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:

- A fan is asked once, and again after 12 hours if they still haven’t paid. Two messages at once get one ask.
- Nobody is asked within 12 hours of a message written from the account. Away and greeting messages (`offline: true`) don’t count.
- Who may chat: subscribers (a paid subscription nobody cancelled counts for two days after its period), in Pay to Chat anyone who paid the creator a tip or bought a drop (refunded or charged back doesn’t count), the creator, their agency, and the account’s Accept for list.
- Sub to Chat while the creator sells no subscription: nobody is asked.
- `quiet: true` for a chat a person has taken over: no ask, but `locked` is still reported.
- Skip groups, channels, bots and messages your own bot sent. We skip Telegram’s service account and Saved Messages.

> [!WARNING] Service messages
> 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.

## 3. Handle the webhooks

| 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.

## Ask when you decide

A chatter wants the fan asked now, or your flow has its own moment for it: [POST /chat-gate/asks](https://www.dropfans.io/developers/reference/request-chat-ask.md) 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](https://www.dropfans.io/developers/reference/get-chat-gate-message.md) 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.

```bash
curl "https://www.dropfans.io/api/external/v1/chat-gate/message?account=5550001111&locale=en" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"
```

## Settings

[GET /chat-gate](https://www.dropfans.io/developers/reference/get-chat-gate.md) and [PUT /chat-gate](https://www.dropfans.io/developers/reference/update-chat-gate.md) 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](https://www.dropfans.io/developers/reference/end-chat-conversation.md) ends a conversation and the fan pays again.

[PUT /chat-gate/exempt](https://www.dropfans.io/developers/reference/set-chat-exempt.md) sets an account’s Accept for list: fans who may always chat there. [POST /chat-gate/fans/lookup](https://www.dropfans.io/developers/reference/lookup-chat-fans.md) gives up to 500 fans’ status at once, for a chat list.

[POST /chat-gate/fans/open](https://www.dropfans.io/developers/reference/open-chats.md) 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`.

## Moving a gate you already run

If your app has its own Pay to Chat, you can move it over without your creators noticing:

1. **Copy.** Write each account’s switch with [PUT /chat-gate](https://www.dropfans.io/developers/reference/update-chat-gate.md) (always with `account`), its Accept for list, your bot with [PUT /chat-gate/chatbot](https://www.dropfans.io/developers/reference/report-chatbot.md), and the chats that are open today with [POST /chat-gate/fans/open](https://www.dropfans.io/developers/reference/open-chats.md). Keep writing changes to both sides.
2. **Compare.** Keep deciding yourself, and call check with `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.
3. **Switch.** Account by account, act on check instead of your own rule, and fall back to your own for a message when we time out.

## Fail open

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](https://www.dropfans.io/developers/webhooks/overview.md) or [Broadcast one drop to many fans](https://www.dropfans.io/developers/guides/broadcast-one-drop.md).

---

Previous: [Creator sign-up from your platform](https://www.dropfans.io/developers/guides/creator-signup.md) · Next: [Build your own CRM dashboard](https://www.dropfans.io/developers/guides/crm-dashboard.md) · All pages: [llms.txt](https://www.dropfans.io/developers/llms.txt)
