Skip to main content

Introdução

Para desenvolver e hospedar um bot do X (Twitter) 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 usando seu e-mail.
  • Plano ativo: Garante recursos dedicados e desempenho otimizado para seu aplicativo. Confira nossos planos disponíveis e escolha o mais adequado às suas necessidades.
Este guia usa o runtime Node.js.

Crie 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. Uma conta de Desenvolvedor X também é necessária para acessar as APIs. Solicite acesso através do Portal do Desenvolvedor X.
A API do X é cobrada por uso: ler menções e publicar respostas é cobrado na sua conta de desenvolvedor do X, incluindo as verificações periódicas de menções do bot. Confira os valores atuais na página de preços da API do X antes de fazer o deploy.

Aplicação de bot no X

1

Abra o Portal do Desenvolvedor

  1. Acesse o Portal do Desenvolvedor X.
  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.
2

Crie um projeto

  1. No Developer Portal, 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.
3

Crie um 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.
4

Gere as 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.
5

Defina as permissões do aplicativo

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

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

Confira as suas 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

Desenvolva o bot

  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.
  2. Inicialização do projeto: Crie um novo projeto Node.js executando:
Terminal
  1. Instalação de dependências: Instale as bibliotecas necessárias para o bot:
Terminal
  1. Credenciais: o código lê as quatro credenciais de variáveis de ambiente, então elas nunca entram no seu código. Para testar o bot no seu computador, coloque-as em um arquivo .env e inicie o bot com node --env-file=.env index.js:
.env
A Square Cloud não lê esse arquivo quando o bot roda: você define as mesmas variáveis na plataforma em Defina as credenciais.
  1. Criação do arquivo principal: Desenvolva o arquivo index.js com a estrutura base do bot:
index.js

Configure a Square Cloud

Crie um arquivo squarecloud.app na raiz do projeto, ao lado do index.js. Ele diz à Square Cloud como rodar o seu bot:
squarecloud.app
  • 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.
  • Não há SUBDOMAIN: o bot chama a API do X e não serve páginas web.
Veja a referência do arquivo de configuração para todos os campos.

Defina as credenciais

Segurança: nunca inclua suas credenciais de API diretamente no código. Sempre use variáveis de ambiente na Square Cloud.
O bot precisa de quatro variáveis de ambiente:
  • 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
Defina-as de uma destas formas:
  • Dashboard: na página de upload, abra Configuração avançada e adicione as quatro variáveis. Para um bot que já está no ar, adicione-as 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), carregue-as do seu arquivo .env local com squarecloud app env set e reinicie o bot:
O bot lê as variáveis de ambiente quando inicia, então reinicie-o após cada alteração. Veja Variáveis de ambiente para as outras formas de gerenciá-las.

O que vai no ZIP

  • O index.js e os seus outros arquivos de código.
  • package.json.
  • squarecloud.app.
Deixe a node_modules de fora: a Square Cloud instala as suas dependências quando o bot inicia. Deixe de fora também o seu arquivo .env: se você faz o upload pela CLI, adicione uma linha com .env ao seu arquivo squarecloud.ignore para que a CLI o ignore.

Faça o deploy e verifique

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

Via dashboard

1

Acesse a página de upload

Acesse a página de upload e envie seu arquivo zip.
2

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

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.
Enviando aplicação para a Square Cloud
4

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. No 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.
Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

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.

Guia do arquivo de configuração

Saiba como criar o arquivo de configuração squarecloud.app que define o ambiente da sua aplicação.
1

Instale a CLI

Instale a CLI da Square Cloud. Se você já a tem, execute o mesmo comando para atualizá-la:
2

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

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 lista, e faz o upload:
Para enviar um zip que você mesmo criou, passe-o com --file:
4

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:
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.
Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Teste o bot

Após o deploy, verifique os logs da aplicação no dashboard da Square Cloud em busca da mensagem Bot inicializado com sucesso! para confirmar que o bot autenticou corretamente. Em seguida, de outra conta, publique um tweet que mencione o bot com !ping (por exemplo, @seu_bot !ping) e confirme que ele responde com Pong! 🤖 Bot do X funcionando corretamente! no X em poucos minutos. Menções publicadas antes de o bot iniciar são ignoradas.

Erros comuns

Request failed with code 401

Os logs mostram Erro ao verificar o bot: seguido deste erro. Uma das quatro credenciais está errada ou faltando. Copie-as de novo da seção “Keys and tokens”, defina as quatro variáveis e reinicie o bot.

Request failed with code 403 ao responder

O bot se autentica, mas não consegue publicar. Os tokens de acesso foram gerados enquanto o aplicativo tinha permissão somente de leitura. Selecione “Read and write” nas permissões do aplicativo, gere de novo o Access Token e o Secret, atualize a ACCESS_TOKEN e a ACCESS_TOKEN_SECRET e reinicie o bot.

Request failed with code 429

O bot atingiu um limite de taxa da API do X. Espere antes da próxima requisição e espace as suas chamadas como em Limitação de taxa (rate limiting).

Indo além

Os trechos abaixo estendem o index.js: adicione-os ao arquivo e chame-os onde o seu bot precisar.

Monitoramento de hashtags

Postagens agendadas

Limitação de taxa (rate limiting)

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

Tratamento de erros

Próximos passos

A aplicação não inicia

Corrija módulos faltando, erros de memória e outras falhas na inicialização.

Variáveis de ambiente

Gerencie as credenciais do seu bot e outros segredos.

Runtime Node.js

Como a Square Cloud roda aplicações Node.js.
Para saber mais sobre o twitter-api-v2 e a API do X, consulte a documentação oficial do twitter-api-v2, a documentação oficial da API do X, as políticas de uso da API do X e a introdução à API do X.

Contate-nos

Se você continuar enfrentando dificuldades técnicas, nossa equipe de suporte especializada está disponível para auxiliá-lo. Entre em contato conosco 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 no Google e Trustpilot.