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.
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.Aplicação de bot no X
1
Abra o Portal do Desenvolvedor
- Acesse o Portal do Desenvolvedor X.
- Faça login com sua conta X (Twitter).
- Se for sua primeira vez, complete o processo de solicitação de acesso de desenvolvedor.
2
Crie um projeto
- No Developer Portal, clique em “Create Project” (Criar Projeto).
- Escolha um nome para seu projeto (ex: “Square Cloud Bot”).
- Selecione o caso de uso mais apropriado (ex: “Making a bot” - Criando um bot).
- Forneça uma descrição detalhada do seu bot.
- Confirme a criação do projeto.
3
Crie um aplicativo
- Dentro do projeto criado, clique em “Create App” (Criar Aplicativo).
- Defina um nome exclusivo para seu aplicativo.
- Confirme a criação do aplicativo.
- Anote o App ID gerado para referência futura.
4
Gere as chaves de API
- Navegue até a seção “Keys and tokens” (Chaves e tokens) do seu aplicativo.
- 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)
- Importante: Copie e salve estas chaves imediatamente, pois você não poderá visualizá-las novamente.
5
Defina as permissões do aplicativo
- Vá para a seção “App permissions” (Permissões do App).
- Clique em “Edit” (Editar) para modificar as permissões.
- Selecione “Read and write” (Leitura e escrita) para permitir que seu bot publique tweets.
- Se necessário, selecione “Read and write and Direct message” (Leitura, escrita e Mensagem direta) para funcionalidade de DM.
- Salve as alterações.
6
Gere os tokens de acesso
- Retorne à seção “Keys and tokens”.
- Na seção “Access Token and Secret” (Token e Segredo de Acesso), clique em “Generate” (Gerar).
- Confirme a geração do token.
- Copie e salve:
- Access Token (Token de Acesso)
- Access Token Secret (Segredo do Token de Acesso)
- Aviso: Estes tokens não podem ser visualizados novamente após fechar a página.
7
Confira as suas credenciais
- 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)
- Armazene essas credenciais em um local seguro
- Importante: Nunca compartilhe ou exponha estas credenciais publicamente
Desenvolva o bot
- 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.
- Inicialização do projeto: Crie um novo projeto Node.js executando:
Terminal
- Instalação de dependências: Instale as bibliotecas necessárias para o bot:
Terminal
- 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
.enve inicie o bot comnode --env-file=.env index.js:
.env
- Criação do arquivo principal: Desenvolva o arquivo
index.jscom a estrutura base do bot:
index.js
Configure a Square Cloud
Crie um arquivosquarecloud.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=trueinicia 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.
Defina as credenciais
Segurança: nunca inclua suas credenciais de API diretamente no código. Sempre use variáveis de ambiente na Square Cloud.
API_KEY: sua chave de API do XAPI_SECRET_KEY: sua chave secreta de API do XACCESS_TOKEN: seu token de acessoACCESS_TOKEN_SECRET: seu segredo do token de acesso
- 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
.envlocal comsquarecloud app env sete reinicie o bot:
O que vai no ZIP
- O
index.jse os seus outros arquivos de código. package.json.squarecloud.app.
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.
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.

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
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.
Via CLI
Para usar esse método, seu projeto precisa de um arquivo de configuração chamadosquarecloud.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 Para enviar um zip que você mesmo criou, passe-o com
squarecloud.ignore lista, e faz o upload:--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.
Teste o bot
Após o deploy, verifique os logs da aplicação no dashboard da Square Cloud em busca da mensagemBot 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 mostramErro 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 aACCESS_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 oindex.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.

