Bluesky.bot
Entrar

Criar um bot em TypeScript

Este guia escreve um bot que publica no Bluesky com @atproto/api, o SDK oficial de TypeScript. Funciona com Node.js 20 ou superior.

1. Criar uma palavra-passe de aplicação

Entre no Bluesky como o bot, abra Definições → Privacidade e segurança → Palavras-passe de aplicação e crie uma. Um bot entra com uma palavra-passe de aplicação, nunca com a palavra-passe principal da conta: pode revogá-la a qualquer momento sem mexer na conta.

2. Preparar o projeto

bash
mkdir my-bot && cd my-bot
npm init -y
npm pkg set type=module
npm install @atproto/api
npm install --save-dev tsx typescript

Mantenha as credenciais fora do código, em variáveis de ambiente:

bash
export BLUESKY_HANDLE="weather.bluesky.bot"
export BLUESKY_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"

3. Escrever o bot

bot.ts
// bot.ts: publica uma vez como o bot. Execute com `npx tsx bot.ts`.
import { AtpAgent, RichText } from "@atproto/api";

// A própria conta do bot, com sessão iniciada com uma palavra-passe de aplicação
// (Definições > Privacidade e segurança > Palavras-passe de aplicação),
// nunca com a palavra-passe principal.
const identifier = process.env.BLUESKY_HANDLE ?? "";
const password = process.env.BLUESKY_APP_PASSWORD ?? "";
if (!identifier || !password) {
  throw new Error("Set BLUESKY_HANDLE and BLUESKY_APP_PASSWORD.");
}

const agent = new AtpAgent({ service: "https://bsky.social" });
await agent.login({ identifier, password });

// O RichText encontra ligações, menções e hashtags para as tornar clicáveis.
const text = new RichText({
  text: "Today: sunny, 21°C. Forecast at https://example.com #weather",
});
await text.detectFacets(agent);

const { uri } = await agent.post({
  text: text.text,
  facets: text.facets,
  createdAt: new Date().toISOString(),
});
console.log(`Posted ${uri}`);

O que faz:

  • AtpAgent fala com https://bsky.social, o servidor das contas alojadas pelo Bluesky. Se o bot estiver noutro servidor (um PDS próprio), use o URL desse servidor.
  • login abre uma sessão com o handle e a palavra-passe de aplicação.
  • RichText e detectFacets transformam a ligação e #weather em facets clicáveis: um text simples mostrá-los-ia como caracteres normais.
  • post cria a publicação e devolve o seu URI at://.

4. Executá-lo

bash
npx tsx bot.ts

Erros que vale a pena tratar

  • Limites de utilização: o Bluesky responde 429 quando uma conta ou um servidor faz demasiado. Espere e tente mais tarde; veja as Boas práticas.
  • Credenciais expiradas: uma palavra-passe de aplicação revogada faz falhar o login. Crie uma nova.
  • Publicações longas: uma publicação leva 300 caracteres (grafemas). Corte o texto mais longo, ou publique uma sequência.

A seguir