🎯 Por onde começar
Comece pelo Bluesky pra validar o fluxo end-to-end. É a rede mais simples (handle + App Password, sem OAuth, sem dashboard de developer), então qualquer falha que aparecer aqui é problema do Postiz — não do provider. Depois que um agendamento Bluesky chegar publicado, aí sim parta para X, LinkedIn e Mastodon.
🗺️ Fluxo geral de conexão
Independente da rede, conectar uma conta no Postiz segue cinco passos. As variações (OAuth vs. App Password, scopes, custos) entram nos detalhes — mas a coluna vertebral é sempre essa.
Settings → Channels → Add channel
No dashboard do Postiz, escolha a rede social na grade de providers. Cada uma exibe seu fluxo próprio.
Autenticar
Login direto (Bluesky, Mastodon) ou redirect OAuth (X, LinkedIn) para o provider autorizar o Postiz a postar em seu nome.
Aprovar scopes
Confirmar permissões mínimas: ler perfil, publicar posts, anexar mídia. Recusar scope extra que a rede não exigir.
Token persistido
Postiz grava access_token + refresh_token criptografados no Postgres.
Canal aparece como ativo
A conta vira opção no compositor de posts. Status verde = pronta para agendar.
🦋 Adicionar conta Bluesky
Bluesky é o caminho mais curto: handle (algo como seunome.bsky.social) mais um App Password gerado nas configurações da própria rede. Não tem OAuth, não tem developer portal, não tem aprovação. Login direto via API ATProto.
Gere o App Password em bsky.app → Settings → App Passwords → Add App Password. Use um nome reconhecível tipo postiz-prod. Nunca cole sua senha principal.
# Dados pedidos pelo Postiz
Handle: seunome.bsky.social
App Password: xxxx-xxxx-xxxx-xxxx # gerado no bsky.app
# O que acontece internamente
POST https://bsky.social/xrpc/com.atproto.server.createSession
{ "identifier": "seunome.bsky.social", "password": "xxxx-xxxx-xxxx-xxxx" }
# → retorna accessJwt + refreshJwt, que o Postiz armazena🦋 Dica prática
Crie um App Password por ferramenta. Assim, se quiser desconectar só o Postiz no futuro, revoga aquele App Password específico e suas outras integrações continuam vivas. Senha principal jamais é tocada.
Conceitos-chave
Protocolo aberto que serve de base para o Bluesky.
Identificador público no formato de domínio.
Senha escopada por aplicação, revogável a qualquer hora.
Endpoint de login que devolve JWT de acesso.
🐦 Conectar X via OAuth
X (ex-Twitter) usa OAuth 2.0 com PKCE. Clica em "Connect X" no Postiz, é redirecionado para x.com/i/oauth2/authorize, autoriza o app e volta com um code que o backend troca por tokens.
O detalhe que assusta: postar via API exige o Basic plan, que custa US$ 200/mês e libera 3.000 posts mensais — ou usar provedores pay-per-use que revendem cotas. O Free tier só lê dados, não publica.
✓ O que FAZER
- ✓Avaliar se US$ 200/mês compensam pelo volume real.
- ✓Considerar pay-per-use se posta menos de 100/mês.
- ✓Confirmar o callback URL no developer portal.
- ✓Guardar
client_id/client_secretsó no.env.
✗ O que NÃO fazer
- ✗Esperar postar com o Free tier — não publica.
- ✗Reusar tokens de uma app antiga do Twitter v1.1.
- ✗Setar callback como
localhostem prod. - ✗Estourar rate limit sem backoff (vira ban temporário).
# .env adicional
X_API_KEY=seu_client_id
X_API_SECRET=seu_client_secret
# Callback URL registrado no developer.x.com
https://seu-dominio.com/api/auth/callback/xConceitos-chave
Padrão de autorização delegada via redirect.
Proof Key — proteção contra interceptação do code.
US$ 200/mês, 3k posts, write habilitado.
Provedores revendem cota por post avulso.
💼 Conectar LinkedIn
LinkedIn usa o produto Sign in with LinkedIn using OpenID Connect + Share on LinkedIn. Crie um app em linkedin.com/developers, habilite os dois produtos, configure o callback e capture Client ID + Client Secret.
Pegadinha: o access_token do LinkedIn vive 60 dias, e o refresh_token precisa do produto Marketing Developer Platform (aprovação manual). Sem ele, o Postiz força reconexão a cada dois meses.
# Scopes mínimos para postar como pessoa
openid
profile
email
w_member_social # publicar no feed pessoal
# Scopes extras para postar em Company Page
r_organization_social
w_organization_social
rw_organization_admin⏰ Dica prática
Anote no calendário a data de expiração do token LinkedIn (60 dias após conectar). O Postiz avisa via dashboard, mas se você só checa o app uma vez por semana, perde a janela e seu post agendado falha em silêncio. Reconecte uns 5 dias antes.
Conceitos-chave
OpenID Connect — identidade sobre OAuth 2.0.
Granularidade do que o app pode fazer pela conta.
60 dias por padrão sem refresh aprovado.
Requer scopes organization e admin role.
🐘 Adicionar Mastodon
Mastodon é federado: não tem "um Mastodon", tem milhares de instâncias (mastodon.social, fosstodon.org, hachyderm.io...). Cada uma é um servidor independente com seu próprio OAuth. O Postiz pede a URL da sua instância antes do login.
O fluxo é dinâmico: Postiz registra um app OAuth na instância que você informou via /api/v1/apps, recebe credenciais efêmeras e redireciona para o /oauth/authorize daquela instância. Tudo automático — você só cola a URL.
# O que Postiz pede
Instance URL: https://mastodon.social
# ou https://fosstodon.org, https://hachyderm.io, etc.
# Scopes solicitados
read # ler timeline e perfil
write # publicar toots
push # notificações (opcional)
# Caracteres por post na maioria das instâncias
500 # (algumas instâncias customizam pra 1000+)🐘 Dica prática
Não confunda seu handle federado (@voce@fosstodon.org) com a URL da instância (https://fosstodon.org). Postiz pede a URL — a instância onde sua conta vive, não o identificador público.
Conceitos-chave
Rede de servidores que conversam via ActivityPub.
Servidor Mastodon individual, com regras próprias.
App registrado on-the-fly via API da instância.
O "post" do Mastodon, equivalente ao tweet.
📅 Programar primeiro post
Com pelo menos dois canais conectados, abra o compositor (botão + New Post). Escreva texto curto, anexe uma imagem, marque dois ou mais canais e agende para amanhã às 9h — horário em que você consegue conferir se publicou de verdade.
Escrever o conteúdo
Texto que caiba no menor limite (280 do X). O Postiz mostra contador por canal e avisa estouro.
Anexar imagem
Drag-and-drop ou clique no clipe. JPG/PNG até ~8MB. Postiz redimensiona se algum provider exigir.
Selecionar canais
Marque os badges das contas (Bluesky + Mastodon recomendados pro primeiro teste — não consomem cota paga).
Definir data/hora
"Schedule" → calendário → amanhã 9h. Confirme o fuso horário no canto do compositor.
Confirmar agendamento
Job entra na fila Redis/BullMQ. Aparece no calendário com cor por canal e status scheduled.
🕘 Dica prática
No dia seguinte, faça as três checagens: 1) o calendário do Postiz mudou o status para posted; 2) a URL pública do post aparece como link no cartão; 3) você consegue clicar e ver o conteúdo na rede social real. Sem os três, não confie no agendador ainda.
Conceitos-chave
Editor unificado que adapta o conteúdo a cada canal.
Fila baseada em Redis que dispara o post na hora certa.
Conferir no perfil — agendamento usa o fuso do usuário.
Um draft, várias APIs — cada canal com seu render.
📊 Ver analytics básico
Depois que o post sair, o Postiz puxa métricas via API de cada provider. A aba Analytics agrega clicks, impressions, engagement e o status de entrega por plataforma.
📈 Métricas disponíveis por rede
- Bluesky: likes, reposts, replies. Sem impressions na API pública — só engajamento absoluto.
- X: impressions, likes, reposts, replies, bookmarks. Requer plano Basic+ para puxar via API.
- LinkedIn: impressions, reactions, comments, shares. Métricas detalhadas só em Company Pages.
- Mastodon: favourites, boosts, replies. Sem impressions — o protocolo não rastreia visualização.
# Status que aparecem no dashboard de cada post
scheduled # na fila, ainda não saiu
posting # job rodando agora
posted # publicado com sucesso, URL disponível
failed # erro do provider — clique para ver stack trace
expired # token expirou antes do horário (reconectar)✓ O que FAZER
- ✓Olhar a aba Analytics 24h após o post (números amadurecem).
- ✓Comparar engagement absoluto, não taxas entre redes diferentes.
- ✓Investigar todo status
failed— não ignore. - ✓Exportar CSV mensalmente para arquivo histórico.
✗ O que NÃO fazer
- ✗Confiar em impressions logo após postar — atrasa horas.
- ✗Comparar X (write pago) com Bluesky em valor absoluto.
- ✗Tratar
expiredcomo erro do Postiz — é token do provider. - ✗Otimizar pra métrica antes de ter 30 posts de baseline.
Conceitos-chave
Quantas vezes o post entrou na tela de alguém.
Cliques em links ou no próprio post.
Reações, comentários e compartilhamentos somados.
Estado do job no agendador (scheduled → posted).
🎯 Resumo do Módulo
/api/v1/apps, OAuth federado.Próximo Módulo:
2.5 — Agendamento avançado, calendário editorial e automações