DaraMex Docs

Appearance

Meta Messenger — Conexión Manual ​

Esta página documenta el flujo manual para conectar una Facebook Page a DaraMex para mensajería de Messenger. Es una alternativa a Facebook Login para Empresas para clientes que no pueden o no quieren usar el OAuth interactivo.

A diferencia del flujo de Instagram Manual, Messenger no requiere una cuenta de Instagram Business vinculada a la Page. Solo se necesita la Page y los scopes de Pages + Messenger.

Resumen ​

El cliente genera un token de larga duración (System User token, "Nunca expira") en su propio Meta Business Manager y lo pega en el wizard del panel junto con el ID de su Facebook Page. La API valida el token, verifica que la Page sea accesible, y registra la conexión para mensajería de Messenger Platform.

Cuándo es útil:

  • El cliente opera en un entorno corporativo donde los viajes OAuth interactivos requieren aprobaciones adicionales de TI.
  • El Facebook Login para Empresas de DaraMex aún no está aprobado por Meta para el Business Manager del cliente.
  • El cliente prefiere gestionar sus propios tokens en lugar de delegar el consentimiento OAuth.

Cuándo usar el flujo manual vs Facebook Login ​

CriterioFacebook Login (OAuth)Conexión Manual
Configuración inicialBaja — el cliente solo hace clic en "Conectar con Facebook"Alta — requiere crear un System User en Business Manager y generar un token manualmente
Gestión del tokenDaraMex renueva internamenteEl cliente es responsable de regenerar el token si lo revoca
Duración del tokenToken de Sistema de Usuario (SUAT), no expira"Nunca expira" — siempre que el cliente no lo revoque manualmente
Riesgo de interrupciónBajoAlto si el cliente rota sus tokens sin actualizar la conexión
Recomendado paraLa mayoría de los clientesClientes con restricciones corporativas o técnicas

Prerequisitos ​

El cliente debe tener activos y configurados los siguientes recursos antes de iniciar el flujo manual:

  1. Meta Business Manager activo — el cliente debe ser administrador de un Business Portfolio en business.facebook.com.

  2. Facebook Page administrada por ese Business Manager — el cliente debe ser administrador de la Page con acceso completo a la misma. La Page debe tener Messenger habilitado (configuración por defecto en Pages de tipo negocio).

  3. System User creado en el Business Manager — con la Facebook Page asignada como asset con control total ("Administrar la Página"). Para crearlo: Business Manager → Usuarios → Usuarios del sistema → Agregar.

  4. La app de DaraMex asignada al System User — como asset de la app. El equipo de DaraMex debe haber proporcionado el App ID correspondiente.

  5. Token generado con expiración "Nunca expira" — al generar el token del System User, se debe seleccionar explícitamente la opción "Nunca" en el campo de expiración y marcar los scopes requeridos (ver sección siguiente).

Scopes requeridos ​

El token del System User debe tener todos los siguientes permisos:

ScopePara qué se usa
pages_show_listListar las Facebook Pages administradas por el token para verificar que pageId sea accesible.
pages_messagingEnviar y recibir mensajes de Messenger Platform en la Page.
pages_manage_metadataSuscribir la Page al webhook de la app (/{pageId}/subscribed_apps) para recibir eventos de Messenger.
pages_read_engagementLeer metadatos de la Page (nombre, estado) durante el proceso de conexión.

A diferencia del flujo de Instagram, no se requieren instagram_basic ni instagram_manage_messages.

Endpoint ​

POST /connections/meta/messenger/manual

Autenticación: sesión de panel activa (@Auth()). El usuario debe tener permiso CASL connections.connection:create.

Body:

json
{
  "accessToken": "EAABcde...",
  "pageId": "123456789",
  "displayName": "Mi Página de Soporte"
}
CampoTipoRequeridoDescripción
accessTokenstringSíSystem User token generado en Business Manager con "Nunca expira".
pageIdstringSíID de la Facebook Page desde la que se enviará y recibirá mensajes de Messenger.
displayNamestringNoNombre visible de la conexión en DaraMex. Si se omite, se usa el nombre de la Facebook Page.

Respuesta exitosa (200 OK):

json
{
  "connectionId": "01927bef-..."
}

Flujo ​

sequenceDiagram
    participant U as Usuario (Panel)
    participant P as Panel (UI)
    participant A as API
    participant M as Meta Graph API

    U->>P: Abre el wizard "Conexión manual" desde el catálogo de Messenger
    U->>P: Rellena accessToken + pageId + displayName (opcional)
    P->>A: POST /connections/meta/messenger/manual { accessToken, pageId, displayName? }

    A->>M: debug_token(accessToken)
    M-->>A: { expiresAt, dataAccessExpiresAt, scopes }
    note over A: Verifica expiresAt === 0 && dataAccessExpiresAt === 0<br/>Verifica 4 scopes requeridos

    A->>M: getMyAccounts(accessToken)
    M-->>A: [{ id, name, accessToken }]
    note over A: Busca page.id === pageId<br/>(sin validación de IG — no aplica para Messenger)

    note over A: MetaAssetUniquenessPolicy.enforce('messenger', pageId, agencyId)<br/>— la misma Page no puede conectarse en dos orgs<br/>de la misma agency. Distintas Pages del mismo<br/>Business Manager SÍ pueden ir a orgs distintas.

    note over A: Persiste Connection con:<br/>accessToken = page.accessToken (Page Access Token, NO el SUSER)<br/>tokenType = system_user_manual<br/>channel = messenger

    A->>M: subscribePageToApp(pageId, page.accessToken)
    M-->>A: OK

    note over A: Emite MetaConnectionEstablishedIntegrationEvent<br/>→ CommunicationsModule crea ChannelAccount<br/>  externalAccountId = pageId

    A-->>P: { connectionId }
    P-->>U: Conexión establecida

Diferencias clave respecto al flujo de Instagram ​

AspectoInstagram ManualMessenger Manual
Scopes6 (incluye instagram_basic, instagram_manage_messages)4 (solo Pages + Messenger)
Validación de IG Business AccountSí — la Page debe tener una IG Business Account vinculadaNo aplica
Graph API call para PagesgetMyAccountsWithIggetMyAccounts
externalAccountId en el integration eventigBusinessAccount.id (ID de la cuenta IG)pageId (ID de la Facebook Page)
Config persistidaIncluye igBusinessAccountId e igUsernameSolo pageId y pageName

Errores y modos de falla ​

Código de errorHTTPCuándo ocurre
META_CONNECTION.TOKEN_WILL_EXPIRE400El token tiene fecha de expiración (expiresAt !== 0 o dataAccessExpiresAt !== 0). El cliente debe regenerar el token seleccionando "Nunca" como expiración.
META_CONNECTION.TOKEN_LACKS_SCOPES400Al token le faltan uno o más de los 4 scopes requeridos. La respuesta incluye la lista de scopes faltantes en metadata.missing.
META.PAGE_NOT_ACCESSIBLE400El pageId proporcionado no aparece en la lista de Pages administradas por el token. Verificar que el System User tenga la Page asignada como asset.
META.ASSET_ALREADY_CONNECTED409Ya existe una conexión para ese pageId dentro de la misma agency (en cualquiera de sus orgs). Distintas Pages del mismo Business Manager SÍ pueden conectarse en orgs distintas.
META_CONNECTION.INVALID_ACCESS_TOKEN400El token proporcionado es inválido o fue revocado antes de la validación.

Decisión de diseño: por qué se almacena el Page Access Token y no el SUSER ​

El token que se persiste en la base de datos es el Page Access Token (page.accessToken del Graph API), no el System User token que el cliente pegó en el formulario.

Razón técnica: los endpoints de Messenger Platform que DaraMex usa para operar requieren un token scoped a la Page:

  • POST /me/messages — enviar mensajes de Messenger. Requiere el Page token (no el SUSER).
  • POST /{pageId}/subscribed_apps — suscribir la Page al webhook para recibir eventos de Messenger. Requiere el Page token.

El SUSER es un token a nivel de usuario de sistema, útil para llamadas de administración, pero los endpoints de mensajería y webhooks exigen el token de la Page específica. Este mismo razonamiento aplica al flujo OAuth — ver complete-meta-messenger-connect.command.ts para el comentario equivalente.

Páginas relacionadas ​