> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quyền truy cập Telegram

> Tự động thêm khách hàng trả phí vào cuộc trò chuyện hoặc kênh Telegram riêng tư khi họ đăng ký hoặc mua hàng.

<Info>
  Quyền truy cập Telegram cho phép khách hàng trả phí truy cập vào một cuộc trò chuyện hoặc kênh riêng tư. Bot Telegram Dodo Payments sẽ tạo một liên kết mời dùng một lần cho mỗi khách hàng và xóa họ khi hủy.
</Info>

## Nội dung được cung cấp

* Grant được tạo ở trạng thái `pending` trong khi bot chuẩn bị lời mời, sau đó chuyển sang `delivered` khi liên kết đã sẵn sàng.
* Khách hàng nhận được liên kết mời Telegram dùng một lần trong email cung cấp và customer portal.
* Họ nhấn vào liên kết và bot thêm họ vào cuộc trò chuyện đã cấu hình.
* Khi hủy, hoàn tiền hoặc thu hồi thủ công, bot sẽ xóa họ khỏi cuộc trò chuyện.

Các trường hợp sử dụng phổ biến gồm kênh alpha riêng tư, nhóm tín hiệu trả phí và các đặc quyền theo cấp độ cộng đồng.

## Kết nối Telegram

<Steps>
  <Step title="Open Entitlements">
    Trong dashboard Dodo Payments, đi đến **Entitlements** và nhấp vào **+**, sau đó chọn **Telegram Access** làm integration. Dashboard yêu cầu Telegram user ID của bạn để bot có thể xác minh quyền sở hữu các cuộc trò chuyện mà bot quản lý.

    <Frame caption="New Entitlement → Telegram Access. The dashboard needs your Telegram user ID before it lists chats.">
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/telegram/connect-prompt.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=dbb8be6964b2cbfb9bbe9902944f3d5f" alt="New Entitlement Telegram Access form prompting for Telegram user ID and Connect Telegram button" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1131" data-path="images/entitlements/telegram/connect-prompt.png" />
    </Frame>

    <Tip>
      Hai bước tiếp theo là các tác vụ thiết lập trên Telegram và có thể hoàn thành theo bất kỳ thứ tự nào — lấy user ID của bạn và thêm bot vào cuộc trò chuyện với quyền admin. Sau khi hoàn tất cả hai, quay lại dashboard để thực hiện bước cuối cùng.
    </Tip>
  </Step>

  <Step title="Get your Telegram user ID">
    Trên Telegram, gửi tin nhắn **`/start`** đến:

    * **`@dodo_payments_bot`** nếu bạn đang sử dụng **Live Mode**
    * **`@DodoPaymentsTestBot`** nếu bạn đang sử dụng **Test Mode**

    Bot sẽ trả lời bằng Telegram user ID dạng số của bạn. Hãy sao chép ID này — bạn sẽ dán vào dashboard ở bước cuối cùng.
  </Step>

  <Step title="Add the bot to your chat as an admin">
    Trong nhóm hoặc kênh Telegram mà bạn muốn giới hạn quyền truy cập, mở danh sách thành viên và **thêm chính bot đó làm admin** (`@dodo_payments_bot` cho live, `@DodoPaymentsTestBot` cho test) với hai quyền sau được bật:

    * **Ban Users** — cần thiết để xóa thành viên khi thu hồi
    * **Add Users** — cần thiết để mời khách hàng trả phí

    Tắt tất cả các quyền admin còn lại.

    <Frame caption="Telegram → Promote to admin. Only Ban Users and Add Users need to be enabled.">
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/telegram/promote-bot-admin.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=bf927f2ee98616b671257d246de06cd3" alt="Telegram Promote to admin screen showing Ban Users and Add Users enabled for the Dodo Payments bot" style={{ maxHeight: '500px', width: 'auto' }} width="734" height="1626" data-path="images/entitlements/telegram/promote-bot-admin.png" />
    </Frame>
  </Step>

  <Step title="Connect Telegram and pick the chat">
    Quay lại dashboard, dán user ID từ bước 2 vào **Telegram User ID** và nhấp vào **Connect Telegram**. Chat picker lúc này sẽ liệt kê mọi nhóm và kênh mà bot là admin — chọn nhóm hoặc kênh bạn muốn giới hạn quyền truy cập, đặt tên cho entitlement và nhấp vào **Create Entitlement**.
  </Step>
</Steps>

## Luồng khách hàng

1. Khách hàng hoàn tất checkout.
2. Dodo Payments tạo grant `pending` và yêu cầu bot tạo một liên kết mời dùng một lần đến cuộc trò chuyện đã cấu hình.
3. Khi liên kết đã sẵn sàng, grant chuyển sang `delivered` và liên kết được đưa vào email cung cấp và customer portal.
4. Khách hàng nhấn vào liên kết và được thêm vào cuộc trò chuyện.
5. Khi thu hồi, bot sẽ xóa khách hàng khỏi cuộc trò chuyện.

<Tip>
  Liên kết mời chỉ có thể sử dụng một lần và sẽ hết hạn sau khi khách hàng tham gia. Nếu họ làm mất liên kết trước khi tham gia, hãy tạo lại liên kết bằng cách gửi lại email cung cấp hoặc thu hồi rồi tạo lại grant từ dashboard.
</Tip>

## Cấu hình bắt buộc

| Trường    | Bắt buộc | Mô tả                                                                                                                        |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `chat_id` | Có       | Chat ID của Telegram (dạng số, thường là số âm đối với nhóm/kênh). Chat picker của dashboard sẽ tự điền giá trị này cho bạn. |

## Tạo qua API

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const entitlement = await client.entitlements.create({
    name: 'Premium Signals Group',
    integration_type: 'telegram',
    integration_config: {
      chat_id: '-1001234567890',
    },
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.create(
      name="Premium Signals Group",
      integration_type="telegram",
      integration_config={"chat_id": "-1001234567890"},
  )
  ```

  ```go Go theme={null} theme={null}
  client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
    Name:            dodopayments.F("Premium Signals Group"),
    IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeTelegram),
    IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
      dodopayments.IntegrationConfigTelegramConfigParam{
        ChatID: dodopayments.F("-1001234567890"),
      },
    ),
  })
  ```
</CodeGroup>

## Webhooks

Xem [các sự kiện webhook `entitlement_grant.*`](/developer-resources/webhooks/intents/entitlement-grant). Grant Telegram bắt đầu ở trạng thái `pending` và chuyển sang `delivered` sau khi bot phát hành liên kết mời.

## Khắc phục sự cố

<AccordionGroup>
  <Accordion title="Chat doesn't appear in the picker">
    Bot Dodo Payments phải được thêm vào cuộc trò chuyện **với tư cách admin** và bật **Add Users**. Picker đọc trạng thái trực tiếp, vì vậy cuộc trò chuyện sẽ xuất hiện ngay khi bot trở thành admin.
  </Accordion>

  <Accordion title="Customer says the invite link doesn't work">
    Liên kết dùng một lần của Telegram sẽ hết hạn sau lần sử dụng đầu tiên. Nếu khách hàng nhấn vào liên kết trên thiết bị đã đăng xuất hoặc làm mất liên kết, hãy thu hồi grant và cấp lại.
  </Accordion>

  <Accordion title="Customer cancelled but is still in the chat">
    Bot cần có quyền admin **Ban Users** để xóa thành viên. Mở cài đặt cuộc trò chuyện và xác nhận cả **Ban Users** lẫn **Add Users** đều được bật cho bot Dodo Payments.
  </Accordion>
</AccordionGroup>