> ## 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 Bots do X (Twitter)

> Aprenda a criar e hospedar bots do X (Twitter) na Square Cloud. Tutorial completo com configuração, deploy e exemplos práticos em Node.js e Python.

export const RecommendedPlan = ({lang, plan, tier, cpu, appType}) => {
  const url = `https://squarecloud.app/${lang}/pay?plan=${plan.toLowerCase()}&tier=${tier}`;
  if (lang == 'en') {
    return <Note>
        <b>Wondering how much RAM and CPU your plan needs to host {appType}?</b><br />
        Don't worry, we're here to help.
        Our <a href={url}>{plan}</a> plan offers <b>{tier}GB</b> of RAM and <b>{cpu}vCPU</b>, which should be sufficient for most {appType}. 
        However, if you are working on a larger project and seeking extra stability, we recommend considering our <b>Pro</b> plan. With additional resources, you can maintain stability even during demand spikes. 
        To purchase, simply click <a href="https://squarecloud.app/en/pay?plan=pro">here</a>.
      </Note>;
  } else {
    return <Note>
          <b>Está se perguntando quanta RAM e CPU seu plano precisa para hospedar {appType}?</b><br />
          Não se preocupe, estamos aqui para ajudar.
          Nosso plano <a href={url}>{plan}</a> oferece <b>{tier}GB</b> de RAM e <b>{cpu}vCPU</b>, o que deve ser suficiente para a maioria dos {appType}.
          No entanto, se você estiver trabalhando em um projeto maior e precisar de mais estabilidade, recomendamos considerar nosso plano <b>Pro</b>.
          Com recursos adicionais, você pode manter a estabilidade mesmo durante picos de demanda.
          Para comprar, basta clicar <a href={`https://squarecloud.app/${lang}/pay?plan=pro`}>aqui</a>.
        </Note>;
  }
};

export const appType_0 = "um bot do X (Twitter)"

## Introdução

Para desenvolver e hospedar um aplicativo {appType_0} no Square Cloud, é essencial seguir uma sequência estruturada de configurações e pré-requisitos.
Este guia técnico abordará todo o processo, desde a configuração inicial até a implantação 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 Pago 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 X (Twitter)" plan="Hobby" tier="2" cpu="2" lang="pt-br" />

### Criando o projeto

Uma conta ativa no X (Twitter) é necessária para autenticação e operação do bot. Se você não tem uma, inscreva-se no [site oficial do X](https://x.com/).
Uma conta de Desenvolvedor X também é necessária para acessar as APIs. Solicite acesso através do [Portal do Desenvolvedor X](https://developer.x.com/en).

### Aplicação de Bot no X

<Steps>
  <Step title="Acessando o Portal do Desenvolvedor">
    1. Acesse o [Portal do Desenvolvedor X](https://developer.x.com/en/portal/dashboard).
    2. Faça login com sua conta X (Twitter).
    3. Se for sua primeira vez, complete o processo de solicitação de acesso de desenvolvedor.
  </Step>

  <Step title="Criação do Projeto">
    1. No painel, clique em "Create Project" (Criar Projeto).
    2. Escolha um nome para seu projeto (ex: "Square Cloud Bot").
    3. Selecione o caso de uso mais apropriado (ex: "Making a bot" - Criando um bot).
    4. Forneça uma descrição detalhada do seu bot.
    5. Confirme a criação do projeto.
  </Step>

  <Step title="Configuração do Aplicativo">
    1. Dentro do projeto criado, clique em "Create App" (Criar Aplicativo).
    2. Defina um nome exclusivo para seu aplicativo.
    3. Confirme a criação do aplicativo.
    4. Anote o **App ID** gerado para referência futura.
  </Step>

  <Step title="Geração das Chaves de API">
    1. Navegue até a seção "Keys and tokens" (Chaves e tokens) do seu aplicativo.
    2. Na seção "Consumer Keys" (Chaves de Consumidor), clique em "Regenerate" (Regerar) para gerar:
       * **API Key** (Chave de Consumidor)
       * **API Secret Key** (Chave Secreta de Consumidor)
    3. **Importante**: Copie e salve estas chaves imediatamente, pois você não poderá visualizá-las novamente.
  </Step>

  <Step title="Configuração de Permissões">
    1. Vá para a seção "App permissions" (Permissões do App).
    2. Clique em "Edit" (Editar) para modificar as permissões.
    3. Selecione "Read and write" (Leitura e escrita) para permitir que seu bot publique tweets.
    4. Se necessário, selecione "Read and write and Direct message" (Leitura, escrita e Mensagem direta) para funcionalidade de DM.
    5. Salve as alterações.
  </Step>

  <Step title="Geração dos Tokens de Acesso">
    1. Retorne à seção "Keys and tokens".
    2. Na seção "Access Token and Secret" (Token e Segredo de Acesso), clique em "Generate" (Gerar).
    3. Confirme a geração do token.
    4. Copie e salve:
       * **Access Token** (Token de Acesso)
       * **Access Token Secret** (Segredo do Token de Acesso)
    5. **Aviso**: Estes tokens não podem ser visualizados novamente após fechar a página.
  </Step>

  <Step title="Verificação de Credenciais">
    1. Confirme que você possui todas as 4 credenciais necessárias:
       * API Key (Chave de Consumidor)
       * API Secret Key (Chave Secreta de Consumidor)
       * Access Token (Token de Acesso)
       * Access Token Secret (Segredo do Token de Acesso)
    2. Armazene essas credenciais em um local seguro
    3. **Importante**: Nunca compartilhe ou exponha estas credenciais publicamente
  </Step>
</Steps>

## Desenvolvendo o projeto

1. **Verificação do Node.js**: 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. **Inicialização do projeto**: Crie um novo projeto Node.js executando:

```bash Terminal theme={null}
npm init -y
```

3. **Instalação de dependências**: Instale as bibliotecas necessárias para o bot:

```bash Terminal theme={null}
npm install twitter-api-v2
```

4. **Configuração de variáveis de ambiente**: Crie um arquivo `.env` para armazenar suas credenciais de forma segura (este arquivo não será usado na Square Cloud, mas é uma boa prática local):

```env .env theme={null}
API_KEY=sua_api_key_aqui
API_SECRET_KEY=sua_api_secret_key_aqui
ACCESS_TOKEN=seu_access_token_aqui
ACCESS_TOKEN_SECRET=seu_access_token_secret_aqui
```

5. **Criação do arquivo principal**: Desenvolva o arquivo `index.js` com a estrutura base do bot:

```javascript index.js theme={null}
// Importa módulos necessários
const { TwitterApi } = require('twitter-api-v2');

// Configure o cliente Twitter com autenticação
const client = new TwitterApi({
  appKey: process.env.API_KEY,
  appSecret: process.env.API_SECRET_KEY,
  accessToken: process.env.ACCESS_TOKEN,
  accessSecret: process.env.ACCESS_TOKEN_SECRET,
});

// Cliente com permissões de leitura e escrita
const rwClient = client.readWrite;

// Armazena o ID do usuário autenticado do bot (definido em verifyBot)
let botUserId = null;

// Função para verificar se o bot está funcionando
async function verifyBot() {
  try {
    // Obtém informações do usuário autenticado (X API v2)
    const me = await rwClient.v2.me();
    botUserId = me.data.id;
    console.log(`Bot inicializado com sucesso! Usuário: @${me.data.username}`);
    return true;
  } catch (error) {
    console.error('Erro ao verificar o bot:', error);
    return false;
  }
}

// Função para postar um tweet
async function postTweet(text) {
  try {
    const tweet = await rwClient.v2.tweet(text);
    console.log(`Tweet publicado com sucesso! ID: ${tweet.data.id}`);
    return tweet;
  } catch (error) {
    console.error('Erro ao postar tweet:', error);
    throw error;
  }
}

// Função para responder a menções
async function respondToMentions() {
  if (!botUserId) return;
  try {
    // Busca menções recentes (X API v2)
    const mentions = await rwClient.v2.userMentionTimeline(botUserId, {
      max_results: 10,
    });

    for (const tweet of mentions.data?.data ?? []) {
      // Verifica se é uma menção nova (implementar lógica de controle)
      if (tweet.text.includes('!ping')) {
        // Responde à menção
        await rwClient.v2.reply(
          'Pong! 🤖 Bot do X funcionando corretamente!',
          tweet.id
        );
        console.log(`Respondeu à menção (tweet ID: ${tweet.id})`);
      }
    }
  } catch (error) {
    console.error('Erro ao processar menções:', error);
  }
}

// Função para buscar e interagir com tweets específicos
async function searchAndInteract(query) {
  if (!botUserId) return;
  try {
    // Busca tweets recentes (X API v2)
    const tweets = await rwClient.v2.search(query, {
      max_results: 10,
    });

    for (const tweet of tweets.data?.data ?? []) {
      // Curte o tweet
      await rwClient.v2.like(botUserId, tweet.id);
      console.log(`Curtiu o tweet ID: ${tweet.id}`);

      // Espera um pouco entre as ações para evitar rate limiting
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  } catch (error) {
    console.error('Erro ao buscar e interagir:', error);
  }
}

// Função principal do bot
async function runBot() {
  console.log('Iniciando bot X...');
  
  // Verifica se o bot está configurado corretamente
  const botOk = await verifyBot();
  if (!botOk) {
    console.error('A inicialização do bot falhou');
    return;
  }
  
  // Exemplo: Postar um tweet de inicialização
  try {
    await postTweet('🤖 Bot do X inicializado e rodando na Square Cloud!');
  } catch (error) {
    console.log('Tweet de inicialização falhou, mas o bot continua rodando');
  }
  
  // Loop principal do bot
  setInterval(async () => {
    try {
      // Verifica e responde a menções a cada 5 minutos
      await respondToMentions();
      
      // Exemplo: Busca e interage com tweets sobre um tópico específico
      // await searchAndInteract('#SquareCloud');
      
    } catch (error) {
      console.error('Erro no loop principal:', error);
    }
  }, 5 * 60 * 1000); // 5 minutos
  
  console.log('Bot rodando. Pressione Ctrl+C para parar.');
}

// Manipulação de sinal para encerramento elegante
process.on('SIGINT', () => {
  console.log('\nEncerrando bot X...');
  process.exit(0);
});

process.on('SIGTERM', () => {
  console.log('\nEncerrando bot X...');
  process.exit(0);
});

// Inicializa o bot
runBot();
```

## Realizando o Deploy

Após preparar os arquivos do seu projeto, você pode enviá-los para a Square Cloud e hospedar seu projeto.
Para fazer isso, crie um arquivo ZIP contendo todos os arquivos do seu projeto.

<AccordionGroup>
  <Accordion title="Variáveis de Ambiente" icon="key">
    <Note>**Segurança**: Nunca inclua suas credenciais de API diretamente no código. Sempre use variáveis de ambiente na Square Cloud.</Note>

    Na Square Cloud, configure as seguintes variáveis de ambiente através do painel de controle:

    * `API_KEY`: Sua chave de API do X
    * `API_SECRET_KEY`: Sua chave secreta de API do X
    * `ACCESS_TOKEN`: Seu token de acesso
    * `ACCESS_TOKEN_SECRET`: Seu segredo do token de acesso
  </Accordion>
</AccordionGroup>

### 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 no Square Cloud.
    Após o deploy, você poderá monitorar o status e os registros do seu projeto no painel.

    <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>
</Steps>

### Via CLI

Para usar esse método, você precisa criar um arquivo de configuração chamado `squarecloud.app` no diretório raiz do seu projeto. Esse arquivo conterá a configuração necessária para o seu projeto.

<Card title="Saiba mais sobre: Como criar arquivo de configuração da Square Cloud." icon="link" href="/pt-br/getting-started/config-file">
  O arquivo squarecloud.app é um arquivo de configuração que será usado para configurar seu aplicativo; ele será usado para definir seu ambiente.
</Card>

<Steps>
  <Step title="Primeiro Passo">
    Primeiro, você precisa ter a CLI instalada em seu ambiente. Se você ainda não a possui, execute o seguinte comando em seu terminal:

    ```
    npm install -g @squarecloud/cli
    ```

    Se você já a possui, recomendamos atualizá-la. Para fazer isso, execute o seguinte comando em seu terminal:

    <Tabs>
      <Tab title="Windows">
        ```bash theme={null}
        squarecloud update
        ```
      </Tab>

      <Tab title="Linux, macOS, e WSL">
        ```bash theme={null}
        curl -fsSL https://cli.squarecloud.app/install | bash
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Segundo Passo">
    Agora, para autenticar e usar outros comandos da CLI, você encontrará sua chave de autorização [aqui](https://squarecloud.app/pt-br/account/security) clicando em "Solicitar Chave da API". Após obter sua chave de autorização, execute o seguinte comando:

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

  <Step title="Terceiro Passo">
    Finalmente, para fazer o deploy da sua aplicação para a Square Cloud usando a CLI, você precisa executar o seguinte comando:

    ```bash theme={null}
    squarecloud upload
    ```

    Ou se já possui o zip criado:

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

## Recursos Adicionais

Para aprofundar seu conhecimento sobre o desenvolvimento de bots do X usando twitter-api-v2, consulte a [documentação oficial da biblioteca twitter-api-v2](https://github.com/PLhery/node-twitter-api-v2). A documentação fornece guias detalhados, tutoriais avançados e referências completas de API para maximizar sua implementação.

Veja também:

* [Documentação oficial da API do X](https://docs.x.com/overview)
* [Políticas de uso da API do X](https://developer.x.com/en/developer-terms/policy)
* [Guia de melhores práticas para Bots](https://docs.x.com/x-api/getting-started/about-x-api)

### Monitoramento de Hashtags

```javascript theme={null}
// Função para monitorar hashtags específicas
async function monitorHashtags(hashtags) {
  for (const hashtag of hashtags) {
    try {
      const tweets = await rwClient.v2.search(`#${hashtag}`, {
        max_results: 10,
      });

      // Processa os tweets encontrados
      for (const tweet of tweets.data?.data ?? []) {
        console.log(`Tweet encontrado com #${hashtag}: ${tweet.text}`);
        // Implementar lógica de interação
      }
    } catch (error) {
      console.error(`Erro ao monitorar #${hashtag}:`, error);
    }
  }
}
```

### Postagens Agendadas

```javascript theme={null}
// Função para agendar postagens
function schedulePost(text, delay) {
  setTimeout(async () => {
    try {
      await postTweet(text);
      console.log('Postagem agendada publicada com sucesso!');
    } catch (error) {
      console.error('Erro ao publicar postagem agendada:', error);
    }
  }, delay);
}

// Exemplo: Agendar uma postagem para 1 hora
schedulePost('🤖 Postagem agendada pelo bot!', 60 * 60 * 1000);
```

### Limitação de Taxa (Rate Limiting)

O X (Twitter) possui limites de taxa rigorosos. Implemente controles para evitar exceder esses limites:

```javascript theme={null}
// Controle de Limitação de Taxa
const rateLimiter = {
  lastRequest: 0,
  minInterval: 1000, // 1 segundo entre as requisições
  
  async wait() {
    const now = Date.now();
    const timeSinceLastRequest = now - this.lastRequest;
    
    if (timeSinceLastRequest < this.minInterval) {
      const waitTime = this.minInterval - timeSinceLastRequest;
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
    
    this.lastRequest = Date.now();
  }
};
```

### Tratamento de Erros

```javascript theme={null}
// Função auxiliar para tentar novamente uma operação em caso de falha
async function retryOperation(operation, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      console.error(`Tentativa ${i + 1} falhou:`, error.message);
      
      if (i === maxRetries - 1) {
        throw error;
      }
      
      // Espera antes de tentar novamente
      await new Promise(resolve => setTimeout(resolve, 2000 * (i + 1)));
    }
  }
}
```

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