Canal Social (Instagram — dual provider)

26. Canal Social (Instagram — dual provider)#

O Catcher expõe o Instagram como um channel (channel=instagram), com dois providers atrás do mesmo contrato: zernio (LIVE) e meta_instagram (scaffold, gated por App Review da Meta). O consumidor vê channel + capabilities, nunca o nome do backend.

Modelo de dados: Profile → SocialAccount (tabelas próprias no tenant DB, NÃO tenant_instances — sem QR, sem proxy por conta, sem FSM de sessão WhatsApp). Eventos no MESMO bus (event_logs + Pub/Sub + webhook ordenado). Mídia SEMPRE re-hospedada em R2 e exposta como media_id — nenhuma URL de CDN da Meta/Zernio atravessa um DTO, evento ou payload.

Provider Status O que cobre
zernio LIVE DM, comments, posts, mentions, ice breakers, comment automations, analytics, ads messaging
meta_instagram scaffold DM + comments (oficial Graph) — gated por META_INSTAGRAM_ENABLED=false até o App Review da Meta

CapabilitiesForProvider: zernio → tudo live=true; meta_instagram → live=false, comment_automations=false (Meta não cobre). requires_proxy=false nos dois (egress HTTPS direto, carve-out como meta_cloud).

Flags (API-only, nunca reiniciam o worker): ZERNIO_ENABLED, ZERNIO_API_URL, ZERNIO_API_KEY, ZERNIO_WEBHOOK_SECRET; META_INSTAGRAM_ENABLED, META_INSTAGRAM_APP_ID, META_INSTAGRAM_APP_SECRET, META_INSTAGRAM_WEBHOOK_VERIFY_TOKEN, META_INSTAGRAM_GRAPH_VERSION, META_INSTAGRAM_GRAPH_BASE_URL.

26.1 Perfis e contas#

Método Rota Descrição
POST /v1/social/profiles Cria um perfil social. Body: {name, zernio_profile_id?} → 201 {id, name, zernio_profile_id, ...}.
GET /v1/social/profiles Lista os perfis do tenant.
PATCH /v1/social/profiles/{id} Renomeia um perfil. Body: {name} → 200.
DELETE /v1/social/profiles/{id} Remove um perfil. Recusado com 409 SOCIAL_PROFILE_HAS_ACCOUNTS enquanto houver contas conectadas nele.
GET /v1/social/providers Matriz de capacidades dos dois providers com live refletindo as flags do deploy.
GET /v1/social/accounts Lista as contas sociais com capabilities anexadas.
GET /v1/social/accounts/{id} Uma conta social.
GET /v1/social/accounts/{id}/media/{mediaId} Baixa uma mídia da conta (avatar) via R2 — nunca CDN Meta.
POST /v1/social/accounts/instagram/connect Conecta uma conta Instagram. Body: {profile_id, username, provider?}. Provider default zernio; meta_instagram → 501 META_INSTAGRAM_DISABLED enquanto a flag estiver off. → 201 com status=CONNECTED + capabilities.
DELETE /v1/social/accounts/{id} Desconecta (soft-disconnect; reconectar revive a mesma linha — upsert).

A resposta de uma conta: {id, profile_id, platform:"instagram", provider, channel:"instagram", username, platform_user_id, status, picture_media_id, picture_url, last_error, connected_at, created_at, updated_at, capabilities}. picture_url é sempre um path Catcher (/v1/social/accounts/{id}/media/{mediaId}), nunca uma URL de CDN.

26.2 Inbox DM (Direct Messages)#

Mesmo contrato do WhatsApp: Idempotency-Key, 202 com message_id (UUID Catcher pré-gerado), família de eventos message.*.

Método Rota Descrição
GET /v1/social/accounts/{id}/conversations Lista threads de DM (paginado, cursor/limit). Retorna conversas com UUID Catcher + provider_thread_id.
GET /v1/social/conversations/{id}/messages Mensagens de uma conversa (paginado, ordem estável asc, after_id/cursor/limit/sort_order). UUID Catcher em id.
POST /v1/social/conversations/{id}/messages Envia DM (texto e/ou mídia). Header Idempotency-Key (obrigatório). Body: {text?, media_id?, media_url?, attachment_type?} → 202 {status:"sent", message_id, idempotency_key}. A chamada ao provider é SÍNCRONA — erro de janela/quota/mídia retorna na hora com error_code estável.
POST /v1/social/conversations/{id}/read Marca a conversa como lida.

Janela de 24h (T3.6): fora da janela de DM, o provider recusa → 409 OUTSIDE_SERVICE_WINDOW. A cópia PT-BR do Console é Instagram-aware ("aguarde o contato enviar uma nova mensagem").

Eventos (inbound via webhook Zernio): message.received, conversation.started; (outbound): message.sent (source:"api" para envios pela API, source:"external" para echo de outro dispositivo). Payload com message_ids = UUID Catcher, username + from (platform user id), sem phone, sem URL de CDN. Mídia inbound re-hospedada em R2 antes da emissão (media_id).

26.3 Comments#

Método Rota Descrição
GET /v1/social/accounts/{id}/comments Posts comentados da conta (com comment_count/like_count). Cada post traz picture_media_id — a thumbnail re-hospedada em R2 (dedup por post id), servida via /v1/social/accounts/{id}/media/{mediaId} — nunca a URL de CDN da Meta.
GET /v1/social/accounts/{id}/posts/{postId}/comments Thread de comentários de um post (paginado). Persistidos com UUID Catcher. Cada item: {id (UUID Catcher), account_id, provider_comment_id, media_id, parent_comment_id?, text, from_username?, from_user_id?, hidden, timestamp}. hidden é o estado de moderação do provider e vem SEMPRE (nunca omitido) — é o que permite ao consumidor desenhar o estado após um reload, em vez de depender do retorno do hide. from_username do canal oficial cai para from.username quando o autor não é a própria conta (a Graph só preenche o username de topo nos comentários próprios), e timestamp é o da Graph, não o do sync.
POST /v1/social/comments/{id}/reply Responde um comentário. Requer Idempotency-Key (um retry é respondido da reserva — nunca duplica um comentário público). Body: {account_id, post_id, text, parent_comment_id?} → 201.
POST /v1/social/comments/{id}/hide Oculta. Body: {account_id, post_id}.
POST /v1/social/comments/{id}/unhide Reexibe. Body: {account_id, post_id}.
DELETE /v1/social/comments/{id} Exclui (se o provider permitir). Body: {account_id, post_id}. Instagram: NÃO suportado pelo Zernio (a API do provider não tem DELETE de comentário — moderation é YouTube-only; a ação suportada é hide) → 501 SOCIAL_OP_UNSUPPORTED.
POST /v1/social/comments/{id}/private-reply Resposta PRIVADA (DM) ao autor do comentário. Requer Idempotency-Key. Body: {account_id, post_id, message}. Janela de 7 dias → 409 PRIVATE_REPLY_WINDOW_EXPIRED.

Eventos: comment.received (inbound via webhook), comment.replied, comment.hidden, comment.deleted (executor-side). Payload: comment_id = UUID Catcher, provider_media_id (o post), from_username + from_user_id, sem URL de CDN.

26.4 Posts#

Método Rota Descrição
GET /v1/social/accounts/{id}/feed Relatório unificado de posts da conta — mescla no servidor: (a) o feed orgânico REAL do Instagram (GET /accounts/{id}/posts do provedor, a ÚNICA superfície que carrega mediaType, logo a única forma de saber que um post é carrossel), (b) os posts publicados pela Catcher (tabela local, com status/scheduled_for) e (c) as métricas por post (GET /analytics). Query: limit (default 50, máx 100). Cada item: {id, source: catcher|organic, provider_media_id, caption, post_type: feed|reels|carousel|story, media_type: image|video|carousel, permalink, thumb_media_id, media_count, timestamp, status, scheduled_for, metrics}. metrics = {likes, comments, views?, impressions?, reach?, shares?, saves?, clicks?, follows?, engagement_rate?, reels_avg_watch_time?, reels_total_watch_time?, source: provider_analytics|feed_counts, last_updated?} — source=feed_counts significa que o provedor só expõe curtidas/comentários para aquele post (típico de post orgânico antigo que a Zernio não rastreia). post_type ≠ media_type: um post de feed pode ser vídeo sem ser Reel. thumb_media_id é mídia re-hospedada no R2 — nenhuma URL de CDN da Meta atravessa a resposta (lição #31). Limitação do provedor: de um carrossel orgânico a Zernio devolve apenas a CAPA (não há superfície children/carousel_media); os demais itens só no permalink. meta = {organic_count, catcher_count, has_analytics, partial, warnings} — partial=true + warnings[] (organic_feed_unavailable | catcher_posts_unavailable | analytics_unavailable) indicam que uma das três superfícies do provedor não respondeu: o relatório é INCOMPLETO, não vazio. Só uma falha TOTAL (feed orgânico E posts locais) devolve erro.
GET /v1/social/accounts/{id}/overview Números de CONTA — só provider meta_instagram. Retorna {username, name, account_type, followers_count, follows_count, media_count, provider_account_id, platform_user_id, account_insights, publish_quota}. account_insights é o rollup do dia (só as métricas que o provedor reportou: accounts_engaged, total_interactions, likes, comments, saves, shares, replies, profile_links_taps, views). publish_quota = {total, usage, duration_seconds} — a cota REAL da Meta (100 por 24h corridas; carrossel conta como 1), não uma estimativa. Dois ids por design: provider_account_id é o app-scoped que endereça a API; platform_user_id é o formato clássico IG Business que chega nos payloads de webhook — comparar webhook contra só um dos dois falha em silêncio. Conta no provider zernio recebe 501 PROVIDER_UNSUPPORTED em vez de um shape meio preenchido.
GET /v1/social/accounts/{id}/posts Feed dos posts criados/agendados via Catcher (com status draft/scheduled/published/failed, thumbnail_media_id, métricas).
POST /v1/social/accounts/{id}/posts Publica (publishNow). JSON `{caption, media_id
POST /v1/social/accounts/{id}/posts/schedule Agenda. Mesmo body + scheduled_for (RFC3339).
DELETE /v1/social/posts/{id} Exclui um post (também cancela um agendamento).
GET /v1/social/accounts/{id}/posts/quota Quota de publicação da plataforma: {quotaUsage, quotaTotal, quotaDurationSeconds}.
GET /v1/social/accounts/{id}/posts-analytics Lista agregada de performance de posts (overview + métricas por post). Query: sort (engagement/impressions/reach/likes/comments/shares/saves/clicks/views/follows), order (asc/desc), limit.
DELETE /v1/social/posts/{id} Exclui um post (também cancela um agendamento). Post publicado no Instagram não pode ser excluído via API (regra da plataforma) — nesse caso o endpoint faz soft-delete LOCAL (scope=local) e o post deve ser removido pelo app do Instagram.

Quota (T5.5): estourar a quota → 429 PUBLISHING_QUOTA_EXCEEDED. Eventos: post.published, post.scheduled, post.failed, post.partial, post.cancelled, post.deleted — payload com post_id UUID Catcher + thumbnail_media_id (R2), sem URL de CDN. O feed esconde posts com status=deleted (tombstones locais).

26.5 Engagement (mentions, ice breakers, automations)#

Método Rota Descrição
GET /v1/social/accounts/{id}/mentions Menções da conta. Limitação do provider: Zernio é LinkedIn-only hoje — menções IG em comentário fluem como comment.received, story-mention em DM como message.received.
GET /v1/social/accounts/{id}/ice-breakers Lista as perguntas frequentes do Direct.
PUT /v1/social/accounts/{id}/ice-breakers Define (max 4, pergunta ≤ 80 chars). Body: {ice_breakers:[{question, payload}]} → 400 ICEBREAKER_LIMIT / ICEBREAKER_QUESTION_TOO_LONG.
DELETE /v1/social/accounts/{id}/ice-breakers Limpa todas.
GET/POST /v1/social/accounts/{id}/comment-automations Lista / cria automações comment-to-DM (keyword-triggered). Create: `{name, trigger?: comment
PATCH/DELETE /v1/social/accounts/{id}/comment-automations/{automationId} Atualiza / exclui uma automação.

26.6 Analytics#

Leituras passam por cache curto (10min, Redis) para não estourar o rate limit do provider em polling do Console.

Método Rota Descrição
GET /v1/social/accounts/{id}/insights Insights da conta (reach, views, accounts_engaged, total_interactions, +). Query: metrics, since, until, metric_type. Dados com até 48h de atraso (dataDelay).
GET /v1/social/accounts/{id}/audience Demografia de seguidores (idade, gênero, país, cidade). Query: timeframe.
GET /v1/social/accounts/{id}/followers Histórico de seguidores (ganhos/perdidos). Query: since, until.
GET /v1/social/posts/{id}/insights Insights de um post/story (métricas reais de feed: impressions/reach/likes/comments/saves/views/engagementRate + platformPostUrl). Fallback para story insights quando o post não está no tracking do provider.
GET /v1/social/accounts/{id}/leads Leads de formulários Lead Gen (ads) persistidos do webhook lead.received. Query: limit.

26.7 Ads (click-to-message + boost)#

Requer uma ad account Meta conectada ao perfil Zernio (a conta de validação não tem — bloqueio externo).

Método Rota Descrição
POST /v1/social/accounts/{id}/ads/messaging Cria um anúncio click-to-message que abre o Direct (destination: instagram_direct). Requer Idempotency-Key (cria objeto cobrável — um retry nunca cria dois). Body: {adAccountId, name, headline?, body?, imageUrl?, budgetAmount?, budgetType?}.
POST /v1/social/accounts/{id}/ads/boost Impulsiona um post publicado como anúncio. Requer Idempotency-Key. Body: `{postId

Limitação do provider: a listagem de conversas do Zernio NÃO carrega flag de origem/atribuição de anúncio — não há como marcar source=ads numa conversa hoje.

26.8 Webhooks#

Rota Descrição
POST /v1/webhooks/zernio Ingest dos eventos do provider Zernio. Assinatura HMAC X-Zernio-Signature (sha256 hex do raw body com ZERNIO_WEBHOOK_SECRET; aceita sha256= prefixo ou hex puro), comparação em tempo constante → 403 se ausente/tampered. Roteamento multi-tenant por provider_account_id; conta desconhecida → 200 sem emissão (nunca 500, nunca tenant errado). Idempotência por id de evento do provider.
GET /v1/instagram/webhook Handshake oficial (scaffold meta_instagram) — responde hub.challenge quando hub.verify_token = META_INSTAGRAM_WEBHOOK_VERIFY_TOKEN.
POST /v1/instagram/webhook Ingest oficial assinado (X-Hub-Signature-256 via META_INSTAGRAM_APP_SECRET). Roteamento por ig user id → SocialAccount (provider meta_instagram).

Eventos sociais no catálogo (AllEventTypes): account.connected, account.disconnected, account.error, conversation.started, message.received (inclusive reações, type reaction), message.sent, message.edited, message.deleted, message.delivered, message.read, message.delivery_failed, comment.received, comment.replied, comment.hidden, comment.deleted, post.published, post.scheduled, post.failed, post.partial, post.cancelled, post.deleted, lead.received, mention.received (limitação IG documentada).

Reação num DM (o "like"): chega como message.received type reaction (reaction.received sob o dialeto específico), achatada — content = emoji (vazio = removida), reaction_target_id = UUID Catcher da mensagem reagida (vazio quando o alvo não está na base), target_from_me, message_ids: [] (reação não vira linha). Escopo do provider: o Zernio só entrega reaction.received para WhatsApp/Telegram na spec atual — reações ❤️ em DM Instagram não chegam (processador pronto pra quando cobrirem). Limitações da plataforma: likes/saves/reposts em POSTS orgânicos não são expostos pelo Instagram a terceiros (sem webhook); comentários em posts chegam via comment.received.

lead.received (leadgen forms): payload {lead_id (UUID Catcher), leadgen_id, form_id, form_name, ad_id, adset_id, campaign_id, is_organic, fields{pergunta→resposta}, username, timestamp} — persistido em social_leads (dedup por leadgen_id), listável via GET /v1/social/accounts/{id}/leads.

26.9 Códigos de erro do canal social#

error_code HTTP Quando
ZERNIO_DISABLED 409 Provider zernio desligado no deploy (ZERNIO_ENABLED=false).
META_INSTAGRAM_DISABLED 501 Criar conta meta_instagram com a flag off (scaffold até App Review).
META_INSTAGRAM_UNSUPPORTED 501 Feature fora do alcance do Graph (posts, mentions, ice breakers, automations, analytics, ads) num provider oficial — a Zernio cobre.
SOCIAL_PROVIDER_UNSUPPORTED 501 Provider não suporta a feature.
SOCIAL_ACCOUNT_NOT_ON_PROVIDER 502 A conta Instagram não foi encontrada no provider no connect.
OUTSIDE_SERVICE_WINDOW 409 Janela de DM de 24h fechada (o contato precisa mensar primeiro).
PRIVATE_REPLY_WINDOW_EXPIRED 409 Janela de 7 dias da resposta privada a comentário expirou.
SOCIAL_OP_UNSUPPORTED 501 O provider não suporta a operação pra essa plataforma (ex.: excluir comentário no Instagram — use hide).
PUBLISHING_QUOTA_EXCEEDED 429 Quota de publicação da plataforma atingida.
ICEBREAKER_LIMIT 400 Mais de 4 ice breakers.
ICEBREAKER_QUESTION_TOO_LONG 400 Pergunta de ice breaker acima de 80 chars.
MEDIA_FETCH_FAILED 502 Download da mídia falhou (URL inválida, MIME não suportado, oversized).
ZERNIO_AUTH 502 A API key da Zernio foi rejeitada (rotacionar).
ZERNIO_RATE_LIMIT 429 Rate limit da Zernio.