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

# Como hospedar um bot do Telegram 24/7

> Hospede seu bot do Telegram 24/7 na Square Cloud: obtenha um token com o BotFather, escreva um bot com grammY ou pyTelegramBotAPI, faça o deploy e teste.

export const RecommendedPlan = ({lang, plan, tier, cpu, appType, min}) => {
  const t = {
    'en': {
      q: <>Which plan should you choose for {appType}?</>,
      rec: p => <>We recommend the {p} plan: its <b>{tier} GB</b> of RAM and <b>{cpu} vCPU</b> handle most projects of this kind, with headroom for traffic spikes.</>,
      min: m => <> Lighter projects also run on the {m} plan.</>,
      pro: p => <> For larger projects, the {p} plan adds more RAM and CPU.</>
    },
    'pt-br': {
      q: <>Qual plano escolher para {appType}?</>,
      rec: p => <>Recomendamos o plano {p}: seus <b>{tier} GB</b> de RAM e <b>{cpu} vCPU</b> atendem a maioria dos projetos desse tipo, com folga para picos de tráfego.</>,
      min: m => <> Projetos mais leves também rodam no plano {m}.</>,
      pro: p => <> Para projetos maiores, o plano {p} oferece mais RAM e CPU.</>
    },
    'es': {
      q: <>¿Qué plan elegir para {appType}?</>,
      rec: p => <>Te recomendamos el plan {p}: sus <b>{tier} GB</b> de RAM y <b>{cpu} vCPU</b> cubren la mayoría de los proyectos de este tipo, con margen para picos de tráfico.</>,
      min: m => <> Los proyectos más ligeros también funcionan en el plan {m}.</>,
      pro: p => <> Para proyectos más grandes, el plan {p} ofrece más RAM y CPU.</>
    },
    'fr': {
      q: <>Quel plan choisir pour héberger {appType} ?</>,
      rec: p => <>Nous recommandons le plan {p} : ses <b>{tier} Go</b> de RAM et <b>{cpu} vCPU</b> suffisent pour la plupart des projets de ce type, avec une marge pour les pics de trafic.</>,
      min: m => <> Les projets plus légers fonctionnent aussi avec le plan {m}.</>,
      pro: p => <> Pour les projets plus importants, le plan {p} offre davantage de RAM et de CPU.</>
    },
    'de': {
      q: <>Welcher Plan eignet sich für {appType}?</>,
      rec: p => <>Wir empfehlen den {p}-Plan: <b>{tier} GB</b> RAM und <b>{cpu} vCPU</b> reichen für die meisten Projekte dieser Art, mit Reserven für Lastspitzen.</>,
      min: m => <> Kleinere Projekte laufen auch mit dem {m}-Plan.</>,
      pro: p => <> Für größere Projekte bietet der {p}-Plan mehr RAM und CPU.</>
    },
    'it': {
      q: <>Quale piano scegliere per {appType}?</>,
      rec: p => <>Ti consigliamo il piano {p}: i suoi <b>{tier}GB</b> di RAM e <b>{cpu}vCPU</b> bastano per la maggior parte dei progetti di questo tipo, con margine per i picchi di traffico.</>,
      min: m => <> I progetti più leggeri funzionano anche con il piano {m}.</>,
      pro: p => <> Per progetti più grandi, il piano {p} offre più RAM e CPU.</>
    },
    'ja': {
      q: <>{appType}にはどのプランを選べばよいですか？</>,
      rec: p => <>{p}プランをおすすめします。<b>{tier}GB</b>のRAMと<b>{cpu}vCPU</b>があれば、この種のプロジェクトの多くをトラフィックのピークにも余裕を持って動かせます。</>,
      min: m => <>軽量なプロジェクトは{m}プランでも動作します。</>,
      pro: p => <>より大規模なプロジェクトには、RAMとCPUが増える{p}プランをご検討ください。</>
    },
    'zh': {
      q: <>托管{appType}应该选择哪个套餐？</>,
      rec: p => <>我们推荐 {p} 套餐：<b>{tier}GB</b> RAM 和 <b>{cpu}vCPU</b> 足以运行大多数此类项目，并能从容应对流量高峰。</>,
      min: m => <>较轻量的项目也可以在 {m} 套餐上运行。</>,
      pro: p => <>对于更大的项目，{p} 套餐提供更多 RAM 和 CPU。</>
    }
  };
  const siteLang = t[lang] ? lang : 'en';
  const c = t[siteLang];
  const pay = (name, query) => <a href={`https://squarecloud.app/${siteLang}/pay?${query}`}>{name}</a>;
  const isPro = plan.toLowerCase() === 'pro';
  return <Note>
      <b>{c.q}</b><br />
      {c.rec(pay(plan, `plan=${plan.toLowerCase()}&tier=${tier}`))}
      {min ? c.min(pay(min, `plan=${min.toLowerCase()}`)) : null}
      {isPro ? null : c.pro(pay('Pro', 'plan=pro'))}
    </Note>;
};

export const appType_0 = "um bot do Telegram"

## Introdução

Para desenvolver e hospedar {appType_0} na Square Cloud, siga a sequência de configurações e pré-requisitos abaixo.
Este guia cobre todo o processo, da configuração inicial ao deploy em produção.

### Pré-requisitos

* **Conta Square Cloud**: Cadastre-se através da [página de cadastro](https://squarecloud.app/pt-br/signup) usando seu e-mail.
* **Plano ativo**: Garante recursos dedicados e desempenho otimizado para seu aplicativo. Confira nossos [planos disponíveis](https://squarecloud.app/pt-br/pricing) e escolha o mais adequado às suas necessidades.

<RecommendedPlan appType="bots do Telegram" plan="Standard" tier="4" cpu="4" min="Hobby" lang="pt-br" />

Este guia usa o [runtime Node.js](/pt-br/articles/getting-started-with-nodejs) ou o [runtime Python](/pt-br/articles/getting-started-with-python).

## Crie o projeto

Uma conta no Telegram é essencial para testar e interagir com seu bot. Se você não tem uma, visite o [site oficial do Telegram](https://telegram.org/) para criar sua conta.

### Aplicação de bot no Telegram

<Steps>
  <Step title="Encontre o BotFather" icon="rocket">
    Acesse o [Telegram Web](https://web.telegram.org/a/) e procure pelo bot oficial **BotFather**, responsável pela criação e gerenciamento de bots na plataforma.

    <Frame>
      <img src="https://cdn.squarecloud.app/docs/articles/telegram/getting-started.webp" alt="Encontrando o BotFather no Telegram" style={{ borderRadius: "0.2rem" }} />
    </Frame>
  </Step>

  <Step title="Obtenha o token" icon="key">
    Inicie uma conversa com o BotFather e digite `/start`. Em seguida, selecione a opção `/newbot` para criar um novo bot. O sistema pedirá um nome para o seu bot e, após a confirmação, gerará automaticamente o token de autenticação necessário.

    <Frame>
      <img src="https://cdn.squarecloud.app/docs/articles/telegram/generating-token.webp" alt="Gerando o token do bot Telegram com o BotFather" style={{ borderRadius: "0.2rem" }} />
    </Frame>
  </Step>
</Steps>

<Warning>**Mantenha o token em segredo**: este token concede controle total sobre o bot. Nunca o escreva no seu código nem o coloque no seu ZIP: os exemplos abaixo o leem da variável de ambiente `TELEGRAM_BOT_TOKEN`.</Warning>

## Desenvolva o bot

Escreva o bot com grammY (Node.js) ou pyTelegramBotAPI (Python). Os dois exemplos ecoam toda mensagem de texto:

<Tabs>
  <Tab title="Node.js - grammY">
    1. Verifique se o Node.js está instalado em seu sistema. Caso contrário, baixe-o no [site oficial do Node.js](https://nodejs.org/).

    2. Inicialize um novo projeto Node.js:

    ```bash Terminal theme={"system"}
    npm init -y
    ```

    3. Instale a biblioteca grammY:

    ```bash Terminal theme={"system"}
    npm install grammy
    ```

    4. Crie o arquivo principal (`index.js`) com a seguinte estrutura:

    ```javascript index.js theme={"system"}
    const { Bot } = require("grammy");

    // O token vem da variável de ambiente TELEGRAM_BOT_TOKEN
    const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN);

    // Responde a cada mensagem de texto com um eco
    bot.on("message:text", async (ctx) => {
      await ctx.reply(`${ctx.me.username} responde: ${ctx.message.text}`);
    });

    // Long polling: o bot pede novas mensagens ao Telegram, então nenhuma URL pública é necessária
    bot.start({
      onStart: (botInfo) => console.log(`Bot ${botInfo.username} iniciado com sucesso!`),
    });
    ```
  </Tab>

  <Tab title="Python - telebot">
    1. Verifique se o Python e o pip estão instalados. Caso contrário, baixe-os no [site oficial do Python](https://www.python.org/).

    2. Instale a biblioteca pyTelegramBotAPI:

    ```bash Terminal theme={"system"}
    pip install pyTelegramBotAPI
    ```

    3. Crie o arquivo principal (`main.py`):

    ```python main.py theme={"system"}
    import os

    import telebot

    # O token vem da variável de ambiente TELEGRAM_BOT_TOKEN
    bot = telebot.TeleBot(os.environ["TELEGRAM_BOT_TOKEN"])
    bot_name = bot.get_me().username


    # Ecoa toda mensagem que não é um comando
    @bot.message_handler(func=lambda message: not message.text.startswith("/"))
    def echo_handler(message):
        bot.reply_to(message, f"{bot_name} responde: {message.text}")


    if __name__ == "__main__":
        print(f"Bot {bot_name} iniciado com sucesso!")
        # Long polling: nenhuma URL pública é necessária
        bot.infinity_polling()
    ```

    4. Crie o arquivo `requirements.txt` para gerenciar as dependências:

    ```txt requirements.txt theme={"system"}
    pyTelegramBotAPI
    ```
  </Tab>
</Tabs>

## Configure a Square Cloud

Crie um arquivo `squarecloud.app` na raiz do projeto, ao lado do seu arquivo principal. Ele diz à Square Cloud como rodar o seu bot:

<CodeGroup>
  ```systemd grammY theme={"system"}
  DISPLAY_NAME=My Telegram Bot
  MAIN=index.js
  MEMORY=512
  VERSION=recommended
  AUTORESTART=true
  ```

  ```systemd telebot theme={"system"}
  DISPLAY_NAME=My Telegram Bot
  MAIN=main.py
  MEMORY=512
  VERSION=recommended
  AUTORESTART=true
  ```
</CodeGroup>

* `MAIN` é o arquivo que a Square Cloud executa, e `MEMORY` é a RAM do bot em MB. Bots precisam de pelo menos 256 MB; 512 MB deixa espaço para crescer.
* `AUTORESTART=true` inicia o bot de novo se ele travar. Veja [como funciona o auto restart](https://help.squarecloud.app/pt-br/article/como-usar-o-auto-restart-na-square-cloud-mdyj38/).
* Não há `SUBDOMAIN`: com long polling, o bot não precisa de URL pública.

Veja a [referência do arquivo de configuração](/pt-br/getting-started/config-file) para todos os campos.

## Defina o token do bot

O seu código lê o token da variável de ambiente `TELEGRAM_BOT_TOKEN`, então o token nunca entra nos seus arquivos. Defina-o de uma destas formas:

* **Dashboard**: na página de upload, abra **Configuração avançada** e adicione uma variável chamada `TELEGRAM_BOT_TOKEN` com o seu token como valor. Para um bot que já está no ar, adicione-a na página **Variáveis de ambiente** da aplicação e reinicie o bot.
* **CLI**: logo depois de enviar o bot (veja [Faça o deploy e verifique](#faça-o-deploy-e-verifique)), defina-a com [`squarecloud app env set`](/pt-br/cli-reference/environment-variables#squarecloud-app-env-set) e reinicie o bot:

```bash theme={"system"}
squarecloud app env set TELEGRAM_BOT_TOKEN=your_token_here
squarecloud app restart
```

O bot lê as variáveis de ambiente quando inicia, então reinicie-o após cada alteração. Veja [Variáveis de ambiente](/pt-br/platform/environment-variables) para as outras formas de gerenciá-las.

<Tip>Para rodar o bot no seu computador primeiro, defina a variável no terminal: `export TELEGRAM_BOT_TOKEN=your_token_here` no macOS e no Linux, ou `$env:TELEGRAM_BOT_TOKEN="your_token_here"` no PowerShell.</Tip>

## O que vai no ZIP

* O seu arquivo principal (`index.js` ou `main.py`) e os seus outros arquivos de código.
* `package.json` ou `requirements.txt`.
* `squarecloud.app`.

Deixe de fora a `node_modules`, a `.venv` e a `__pycache__`: a Square Cloud instala as suas dependências quando o bot inicia.

## Faça o deploy e verifique

Crie o ZIP descrito acima e faça o upload:

### Via dashboard

<Steps>
  <Step title="Acesse a página de upload">
    Acesse a [página de upload](https://squarecloud.app/pt-br/dashboard/new) e envie seu arquivo zip.
  </Step>

  <Step title="Configure seu ambiente">
    Após fazer o upload do seu arquivo zip, você precisará configurar o nome, o arquivo principal ou o ambiente de execução e outras configurações do seu projeto.\
    Se você estiver enviando um projeto web, certifique-se de selecionar "Publicação na Web" e definir um subdomínio para o seu projeto.
  </Step>

  <Step title="Faça o deploy do projeto">
    Por fim, clique no botão "Deploy" para hospedar seu projeto na Square Cloud.
    Após o deploy, você poderá monitorar o status e os registros do seu projeto no dashboard.

    <Frame>
      <img src="https://cdn.squarecloud.app/docs/articles/dashboard/uploading-pt-br.gif" alt="Enviando aplicação para a Square Cloud" style={{ borderRadius: "0.2rem" }} />
    </Frame>
  </Step>

  <Step title="Confirme que seu app está no ar">
    Seu primeiro deploy geralmente leva menos de um minuto. No [dashboard](https://squarecloud.app/pt-br/dashboard), aguarde o status da sua aplicação mudar para em execução e verifique os registros em busca de erros de inicialização.\
    Se você fez deploy de um site ou API, abra `https://<seu-subdominio>.squareweb.app` no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
    <Tip>Seu app não está iniciando? Veja o [guia de solução de problemas](/pt-br/platform/troubleshooting/app-wont-start) para as causas e correções mais comuns.</Tip>
  </Step>
</Steps>

### Via CLI

Para usar esse método, seu projeto precisa de um arquivo de configuração chamado `squarecloud.app` na raiz. Ele informa à Square Cloud como executar a sua aplicação.

<Card title="Guia do arquivo de configuração" icon="link" href="/pt-br/getting-started/config-file">
  Saiba como criar o arquivo de configuração `squarecloud.app` que define o ambiente da sua aplicação.
</Card>

<Steps>
  <Step title="Instale a CLI">
    Instale a [CLI da Square Cloud](/pt-br/cli-reference/installation). Se você já a tem, execute o mesmo comando para atualizá-la:

    <CodeGroup>
      ```bash macOS, Linux e WSL theme={"system"}
      curl -fsSL https://cli.squarecloud.app/install | bash
      ```

      ```bash Windows com npm theme={"system"}
      npm install -g @squarecloud/cli@latest
      ```
    </CodeGroup>
  </Step>

  <Step title="Faça login">
    Execute o comando abaixo. Ele abre o seu navegador: aprove o login lá e a CLI está pronta. Não há nenhuma chave de API para copiar. Para scripts e CI, veja [autenticação da CLI](/pt-br/cli-reference/authentication).

    ```bash theme={"system"}
    squarecloud auth login
    ```
  </Step>

  <Step title="Envie o seu projeto">
    Na pasta do seu projeto, execute o comando abaixo. A CLI compacta a pasta atual, deixando de fora o que o [`squarecloud.ignore`](/pt-br/getting-started/squarecloud-ignore) lista, e faz o upload:

    ```bash theme={"system"}
    squarecloud upload
    ```

    Para enviar um zip que você mesmo criou, passe-o com `--file`:

    ```bash theme={"system"}
    squarecloud upload --file <caminho/para/zip>
    ```
  </Step>

  <Step title="Confirme que seu app está no ar">
    Seu primeiro deploy geralmente leva menos de um minuto. Verifique o status e os registros da sua aplicação diretamente pelo terminal:

    ```bash theme={"system"}
    squarecloud app status
    squarecloud app logs
    ```

    Se você fez deploy de um site ou API, abra `https://<seu-subdominio>.squareweb.app` no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
    <Tip>Seu app não está iniciando? Veja o [guia de solução de problemas](/pt-br/platform/troubleshooting/app-wont-start) para as causas e correções mais comuns.</Tip>
  </Step>
</Steps>

### Teste o bot

Depois do deploy, encontre o seu bot no Telegram e envie uma mensagem. O bot responde com o mesmo texto, o que confirma que ele está rodando.

<Frame>
  <img src="https://cdn.squarecloud.app/docs/articles/telegram/testing-bot.webp" alt="Testando o bot Telegram após o deploy" style={{ borderRadius: "0.2rem" }} />
</Frame>

## Erros comuns

### Error 409: Conflict: terminated by other getUpdates request

Outra cópia do bot está lendo as atualizações com o mesmo token, por exemplo a que você iniciou no seu computador. O Telegram entrega as atualizações a uma única conexão de long polling por bot. Pare a outra cópia, ou revogue o token no BotFather se você não sabe onde ela roda, depois defina o novo token e reinicie o bot.

### Error 401: Unauthorized

O token está errado ou foi revogado. Copie o token atual do BotFather, defina-o de novo e reinicie o bot.

### Token vazio ou `KeyError: 'TELEGRAM_BOT_TOKEN'`

A variável `TELEGRAM_BOT_TOKEN` não está definida: o grammY para com `Empty token!`, e o exemplo em Python para com um `KeyError`. Defina a variável, como em [Defina o token do bot](#defina-o-token-do-bot), e reinicie o bot.

## Próximos passos

<CardGroup cols={3}>
  <Card title="A aplicação não inicia" icon="triangle-exclamation" href="/pt-br/platform/troubleshooting/app-wont-start">
    Corrija módulos faltando, erros de memória e outras falhas na inicialização.
  </Card>

  <Card title="Variáveis de ambiente" icon="key" href="/pt-br/platform/environment-variables">
    Gerencie o token do seu bot e outros segredos.
  </Card>

  <Card title="python-telegram-bot com aiohttp" icon="telegram" href="/pt-br/tutorials/python/how-to-change-ptb-connection">
    Usa o python-telegram-bot? Corrija exceções NetworkError frequentes.
  </Card>
</CardGroup>

Para saber mais sobre essas bibliotecas, consulte a [documentação oficial do grammY](https://grammy.dev/) e a [página do pyTelegramBotAPI no PyPI](https://pypi.org/project/pyTelegramBotAPI/).

## Contate-nos

Se você continuar enfrentando **dificuldades técnicas**, nossa **equipe de suporte especializada** está disponível para auxiliá-lo. [**Entre em contato conosco**](https://squarecloud.app/pt-br/support) e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com [**4,9/5 em 402 avaliações**](https://www.trustpilot.com/review/squarecloud.app) no Google e Trustpilot.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.