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