GUÍA TÉCNICA — CONECTOR META (AURA)

Conectar Meta a Aura

Cómo crear y configurar, de una sola vez, la app de Meta que usan todos los workspaces de Aura para conectar sus cuentas de Facebook e Instagram. Esto lo hace el equipo de MayaCode una sola vez — cada cliente final solo hace clic en "Conectar" dentro de la app, nunca necesita su propia app de desarrollador.

Graph APIv23.0
FacebookFacebook Login (Pages)
InstagramInstagram API with Instagram Login

00 Qué vamos a crear

Meta separó su plataforma en dos productos independientes que Aura usa por separado — no son la misma cosa ni comparten credenciales, aunque viven dentro de la misma app de Meta:

Facebook Loginpara publicar en Páginas
Requiereuna Página de Facebook administrada por el usuario
CredencialesMETA_APP_ID / META_APP_SECRET
Instagram API with Instagram Loginpara publicar en Instagram
Requieresolo una cuenta de Instagram profesional (Business/Creator) — sin Página de Facebook vinculada
CredencialesINSTAGRAM_APP_ID / INSTAGRAM_APP_SECRET (distintas de las de arriba, aunque viven en la misma app de Meta)
Por qué separado: hasta 2024, conectar Instagram exigía forzosamente pasar por una Página de Facebook con la cuenta de Instagram vinculada — un obstáculo real para clientes que solo usan Instagram. El producto "Instagram API with Instagram Login" que lanzó Meta elimina esa dependencia. Aura usa ese producto directamente en vez del flujo viejo.

01 Crear la app en Meta

  1. Entrar a developers.facebook.com/apps con la cuenta de MayaCode.
  2. Crear app → tipo Business → asociarla a un Business Manager de MayaCode (si no existe uno, Meta ofrece crearlo en el mismo flujo).
  3. En el dashboard de la app, agregar los dos productos por separado: Facebook Login y, en la sección Instagram, API setup with Instagram login.
  4. Verificación de negocio (Business Verification): Meta la exige antes de otorgar acceso avanzado a los permisos de publicación — sube documentación legal de MayaCode (puede tardar de días a semanas en aprobarse). Sin esto, la app queda en modo desarrollo: solo funciona para cuentas agregadas manualmente como "Tester" en el dashboard, no para clientes reales.

02 Producto: Facebook Login

Configuración → Básica, y Facebook Login → Configuración.

App ID / SecretConfiguración → Básica — copiar como META_APP_ID / META_APP_SECRET
URI de redirección OAuth válidashttps://aura-api.mayacode.dev/api/social-accounts/oauth/facebook/callback
Dominios de la appaura-api.mayacode.dev

Permisos que Aura solicita en el consentimiento: pages_show_list, pages_read_engagement, pages_manage_posts.

03 Producto: Instagram API con Instagram Login

Dashboard → Instagram → API setup with Instagram login. Tiene su propio App ID/Secret, distinto del de Facebook Login.

Instagram app ID / secretcopiar como INSTAGRAM_APP_ID / INSTAGRAM_APP_SECRET — no el App ID de Facebook
URI de redirección OAuthhttps://aura-api.mayacode.dev/api/social-accounts/oauth/instagram/callback

Permisos: instagram_business_basic, instagram_business_content_publish. Cada cuenta que se conecte debe ser una cuenta profesional (Business o Creator) — Instagram lo exige del lado de la cuenta, no hay nada que configurar en la app para esto.

04 Permisos y revisión de la app

Sin esto, Aura solo funciona con cuentas agregadas a mano como testers — nunca con clientes reales.

Meta exige App Review para cada permiso de "acceso avanzado" (todos los listados en §02/§03 lo son). El proceso: grabar un screencast mostrando el flujo real dentro de Aura (conectar cuenta → programar post → verlo publicado), explicar por escrito para qué se usa cada permiso, y esperar la revisión de Meta.

Tiempos reales: la revisión de permisos suele tardar días; la verificación de negocio (§01), semanas. Iniciar ambos procesos lo antes posible — son la parte que Aura no puede automatizar, dependen enteramente de Meta.

05 Configurar los secrets

cd aura-backend
wrangler secret put META_APP_ID
wrangler secret put META_APP_SECRET
wrangler secret put INSTAGRAM_APP_ID
wrangler secret put INSTAGRAM_APP_SECRET

npm run deploy

No hace falta ninguna migración ni cambio de código para esto — los cuatro valores solo se leen en tiempo de ejecución (_lib/secrets.ts). Una vez configurados, los botones "Conectar Facebook"/"Conectar Instagram" dentro de Aura quedan operativos para cualquier workspace.

06 Renovación automática de tokens

Nada que operar manualmente — es el "todo automatizado" de punta a punta.

Ni Facebook ni Instagram entregan un token que dure para siempre: el token inicial dura 1-2 horas, se cambia de inmediato por uno de 60 días, y ese de 60 días hay que renovarlo antes de que venza. _lib/publisher.ts::refreshExpiringSocialTokens corre en el mismo cron que publica posts (cada minuto) y renueva cualquier cuenta de Facebook/Instagram cuyo token venza en los próximos 7 días — throttleado a un intento por cuenta por día. El usuario final nunca ve esto; solo tendría que reconectar si deja pasar los 60 días completos sin que Aura haya podido renovar (por ejemplo, si revocó el acceso desde Meta).

X, LinkedIn y TikTok quedan fuera de esta renovación automática por ahora — cada una tiene su propio mecanismo de refresh_token (ya migrado en el schema, social_accounts.refresh_token_encrypted), pero implementarlo no era parte de este alcance (enfocado en Meta). Sus tokens deberán reconectarse manualmente cuando venzan hasta que se construya su renovación.

07 Solución de problemas

Error"El usuario no administra ninguna Page"la cuenta de Facebook que autorizó no es admin de ninguna Page
Errorredirect_uri mismatchla URI de callback no coincide EXACTO (con/sin slash final) con la registrada en el dashboard de Meta
Errortoken expiró antes de lo esperadorevisar que el cron de aura-cron esté corriendo (wrangler tail en aura-backend) — sin el cron, no hay renovación
Errorapp en modo desarrollosolo conecta cuentas agregadas como Tester — falta completar App Review (§04)

Aura · MayaCode — documento vivo, generado a partir del estado real del código. ← Volver a la documentación de Aura