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

# Telegram Entitlement

> Adicione clientes pagantes a um chat ou canal privado do Telegram automaticamente quando eles assinarem ou comprarem.

<Info>
  O privilégio do Telegram dá aos clientes pagantes acesso a um chat ou canal privado. O bot do Dodo Payments no Telegram gera um link de convite único para cada cliente e os remove no cancelamento.
</Info>

## O que é entregue

* A concessão é criada em `pending` enquanto o bot prepara o convite, depois transita para `delivered` quando o link está pronto.
* O cliente recebe um link de convite único do Telegram em seu e-mail de entrega e portal do cliente.
* Eles tocam no link e o bot os adiciona ao chat configurado.
* No cancelamento, reembolso ou revogação manual, o bot os remove do chat.

Usos comuns incluem canais alfa privados, grupos de sinal pagos e vantagens de nível de comunidade.

## Conectar Telegram

<Steps>
  <Step title="Open Entitlements">
    No painel do Dodo Payments, vá para **Entitlements** e clique em **+**, em seguida escolha **Telegram Access** como a integração. O painel solicita seu ID de usuário do Telegram para que o bot possa verificar a propriedade dos chats que gerencia.

    <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="Novo formulário de Acesso ao Telegram solicitando o ID de usuário do Telegram e o botão Conectar Telegram" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1131" data-path="images/entitlements/telegram/connect-prompt.png" />
    </Frame>

    <Tip>
      As duas próximas etapas são tarefas de configuração no Telegram e podem ser concluídas em qualquer ordem — obtenha seu ID de usuário e adicione o bot ao seu chat como administrador. Uma vez que ambos estejam feitos, volte ao painel para a etapa final.
    </Tip>
  </Step>

  <Step title="Get your Telegram user ID">
    No Telegram, envie uma mensagem para **`/start`** para:

    * **`@dodo_payments_bot`** se você estiver usando **Modo Live**
    * **`@DodoPaymentsTestBot`** se você estiver usando **Modo Teste**

    O bot responde com seu ID de usuário numérico do Telegram. Copie-o — você o colará no painel na última etapa.
  </Step>

  <Step title="Add the bot to your chat as an admin">
    No grupo ou canal do Telegram que você deseja proteger, abra a lista de membros e **adicione o mesmo bot como administrador** (`@dodo_payments_bot` para live, `@DodoPaymentsTestBot` para teste) com estas duas permissões ativadas:

    * **Banir Usuários** — necessário para remover membros na revogação
    * **Adicionar Usuários** — necessário para convidar clientes pagantes

    Deixe todas as outras permissões de administrador desligadas.

    <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="Tela do Telegram promovendo a administrador mostrando Banir Usuários e Adicionar Usuários ativados para o bot do Dodo Payments" 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">
    De volta ao painel, cole o ID de usuário da etapa 2 em **Telegram User ID** e clique em **Connect Telegram**. O seletor de chat agora lista todos os grupos e canais onde o bot é administrador — escolha o que você quer proteger, dê um nome ao privilégio e clique em **Create Entitlement**.
  </Step>
</Steps>

## Fluxo do cliente

1. O cliente conclui o checkout.
2. O Dodo Payments cria uma concessão `pending` e pede ao bot para gerar um link de convite único para o chat configurado.
3. Quando o link está pronto, a concessão passa para `delivered` e o link é incluído no e-mail de entrega e no portal do cliente.
4. O cliente toca no link e é adicionado ao chat.
5. Na revogação, o bot remove o cliente do chat.

<Tip>
  O link de convite é de uso único e expira após o cliente entrar. Se o cliente perder o link antes de entrar, regenere-o reenviando o e-mail de entrega ou revogando e recriando a concessão a partir do painel.
</Tip>

## Configuração necessária

| Campo     | Obrigatório | Descrição                                                                                                                 |
| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| `chat_id` | Sim         | O ID do chat do Telegram (numérico, geralmente negativo para grupos/canais). O seletor do painel preenche isso para você. |

## Criar via 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

Veja [eventos de webhook](/developer-resources/webhooks/intents/entitlement-grant). As concessões do Telegram chegam como `pending` e passam para `delivered` uma vez que o bot tenha emitido o link de convite.

## Solução de problemas

<AccordionGroup>
  <Accordion title="Chat doesn't appear in the picker">
    O bot do Dodo Payments deve ser adicionado ao chat **como administrador** com **Adicionar Usuários** ativado. O seletor lê o estado em tempo real, então o chat aparece assim que o bot for administrador.
  </Accordion>

  <Accordion title="Customer says the invite link doesn't work">
    Os links únicos do Telegram expiram após o primeiro uso. Se o cliente tocou nele em um dispositivo desconectado ou perdeu o link, revogue a concessão e reemita.
  </Accordion>

  <Accordion title="Customer cancelled but is still in the chat">
    O bot precisa da permissão de administrador **Banir Usuários** para remover membros. Abra as configurações do chat e confirme que tanto **Banir Usuários** quanto **Adicionar Usuários** estão marcados no bot do Dodo Payments.
  </Accordion>
</AccordionGroup>