API de conversiones para mensajes empresariales

La API de conversiones permite a los anunciantes enviar eventos de la web, de la aplicación, de la tienda física y de mensajes empresariales a Meta mediante un extremo único y no mediante varios orígenes. Esta consolidación puede simplificar la pila de tecnología de un anunciante y crear una vista más completa en el Administrador de eventos de Meta gracias al uso de conjuntos de datos.

En esta documentación se proporciona orientación para integrar los eventos de mensajes empresariales en la API de conversiones. Entre los beneficios de usar la API de conversiones para los mensajes empresariales se incluyen los siguientes:

Consulta de los resultados directamente en los informes del Administrador de anuncios: los anunciantes pueden entender fácilmente los resultados de las campañas de clic para enviar mensajes en función de los resultados que importan directamente en las superficies de Meta, por ejemplo, el número de compras y el coste por compra, en lugar de las conversaciones iniciadas.
Simplificación de la integración de datos: una API para ingerir y compartir los datos en múltiples plataformas de mensajes (Messenger, WhatsApp) y canales (sitio web, aplicación, tiendas, mensajes).
Mejora de la medición de los socios: permite la atribución de las campañas de clic para enviar mensajes directamente en los paneles de los socios mediante la API de insights de anuncios.

Requisitos previos

Conjunto de datos

Los eventos de mensajes empresariales enviados mediante la API de conversiones deben asociarse a un conjunto de datos.

Los conjuntos de datos permiten a los anunciantes conectar los datos de eventos de los orígenes de eventos de mensajes empresariales, la tienda, la aplicación y la web a la API de conversiones y administrarlos. Los conjuntos de datos pueden mostrar datos de eventos de las siguientes integraciones, en función de las que decidas configurar:

Píxel de Meta (eventos del sitio web)
API de eventos de la aplicación (eventos de la aplicación, incluido el SDK de Facebook para iOS o Android, socios de medición de la actividad en móviles o MMP)
API de conversiones offline (API heredada de Meta para los eventos offline)

Los conjuntos de datos te permiten ver todas las actividades de los clientes desde una sola interfaz. También te permiten reducir el esfuerzo para crear y mantener varias integraciones de la API.

En el Administrador de eventos, los anunciantes tienen diferentes opciones para crear un conjunto de datos en función del punto de partida. También puedes crear un nuevo conjunto de datos en el Administrador de eventos mediante la vinculación de información durante la creación de un conjunto de eventos offline o mediante una aplicación para móviles existente o durante la creación de un conjunto de eventos de mensajes. Ten en cuenta que es necesario vincular un conjunto de datos a una aplicación para enviar eventos de la aplicación para móviles a la API de conversiones y solo se puede vincular una aplicación a un conjunto de datos. Consulta más detalles e instrucciones aquí.

Permisos

Para implementar una integración directa como anunciante, consulta los requisitos previos y los permisos en estas instrucciones.
Para implementar la integración de una plataforma de socios, necesitas tener lo siguiente:
- Acceso avanzado a los permisos ads_read, ads_management, pages_messaging, whatsapp_business_messaging, pages_show_list y instagram_manage_messages.
- La función de acceso estándar a la administración de anuncios.
- En función de los tipos de eventos, necesitas tener acceso avanzado al permiso page_events para eventos de Messenger o WhatsApp o instagram_manage_events para Instagram Direct.

Incorporación de socios

Si vas a implementar una integración con socios como plataforma, puedes usar los métodos de incorporación del inicio de sesión con Facebook para empresas (recomendado) o la extensión de Meta para empresas.

Consulta Guías de la API de conversiones para mensajes empresariales, que incluye guías de integración con instrucciones paso a paso.

API de conjuntos de datos para mensajes y WhatsApp

La API de conjuntos de datos se usa para recuperar el valor de dataset_id asociado a la página específica. Este valor de dataset_id se usa más adelante en la API de conversiones. Para poder usar la API de conjuntos de datos, necesitarás que el cliente conceda a la aplicación el permiso page_events para los eventos de Messenger o WhatsApp mediante el inicio de sesión con Facebook para empresas o la extensión de Meta para empresas.

Para recuperar el valor de dataset_id, tienes que hacer una llamada GET a la API de conjuntos de datos con page_id y access_token. Consulta el ejemplo de llamada siguiente:

https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}

La respuesta será un identificador, que representa el valor de dataset_id. Con este valor y el identificador de acceso recibido previamente, ahora puedes llamar a la API de conversiones para enviar eventos de mensajes a Meta.

API de conjuntos de datos para Instagram

La API de conjuntos de datos se usa para recuperar el valor de dataset_id asociado a la página específica. Este valor de dataset_id se usa más adelante en la API de conversiones. Para poder usar la API de conjuntos de datos, necesitarás que el cliente conceda a la aplicación el permiso instagram_manage_events mediante el inicio de sesión con Facebook para empresas o la extensión de Meta para empresas.

Para recuperar el valor de dataset_id, tienes que hacer una llamada GET a la API de conjuntos de datos con ig_user_id y access_token. A continuación se incluye un ejemplo de llamada:

https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}

La respuesta será un identificador, que representa el valor de dataset_id. Con este valor y el identificador de acceso recibido previamente, ahora puedes llamar a la API de conversiones para enviar eventos de mensajes a Meta.

Configuración

Configurar los parámetros de los eventos de mensajes empresariales

Puede consultar el conjunto actual de parámetros que se pueden enviar con la API de conversiones aquí. Para enviar eventos de mensajes empresariales, los siguientes campos se pueden compartir en la carga útil de datos de usuario para diferentes plataformas de mensajes:

Plataforma	Parámetro	Descripción
Messenger	`page_id`	Obligatorio para Messenger Identificador de la página de Facebook asociado a la empresa.
Messenger	`page_scoped_user_id`	Obligatorio para Messenger Los usuarios que interactúan con las páginas se identifican mediante identificadores de usuario específicos de la página (PSID). El PSID puede obtenerse de este webhook.
WhatsApp	`page_id`	Obligatorio para WhatsApp Identificador de la página de Facebook asociado a la empresa de WhatsApp.
WhatsApp	`ctwa_clid`	Obligatorio para WhatsApp `ctwa_clid` solo está disponible en el objeto de referencia en el webhook de mensajes, en las versiones 2.45.1 y posteriores de la API de WhatsApp Business (API local) o API de nube.
Instagram	`ig_account_id`	Obligatorio para Instagram Identificador de la cuenta de Instagram que está asociado a la empresa.
Instagram	`ig_sid`	Obligatorio para Instagram Los usuarios que interactúan con Instagram se identifican mediante identificadores de usuario específicos de Instagram (IGSID). El IGSID se puede obtener de este webhook.

Enviar eventos

Para enviar nuevos eventos, haz una solicitud POST a la API de conversiones desde esta ruta:

https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

Al realizar una publicación en este perímetro, Meta crea nuevos eventos de mensajes empresariales. Para obtener más información, consulta el siguiente documento para desarrolladores.

A continuación se ofrece información general sobre cómo se ajustan los parámetros al esquema general de la carga útil.

Para eventos de Messenger:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "messenger",
      "user_data": {
        "page_id": <PAGE_ID>,
        "page_scoped_user_id": <PSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

Para eventos de WhatsApp:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "page_id": <PAGE_ID>,
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

Para eventos de Instagram:

Ejemplo de solicitud a la API de conversiones de CTD

POST /{dataset_id}/events

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "instagram",
      "user_data": {
        "ig_account_id": <IG_ACCOUNT_ID>,
        "ig_sid": <IGSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

Solución de problemas

Utiliza la herramienta para probar eventos en el Administrador de eventos con fines de pruebas:

Ve al Administrador de eventos y selecciona un conjunto de datos vinculado a la página.
Haz clic en la pestaña “Probar eventos”.
Selecciona el canal de marketing y el canal de mensajes.
Haz clic en el botón Explorador de la API Graph.
El explorador de la API Graph se rellenará con la carga útil rellenada previamente.
Haz clic en el botón “Enviar”.

Vídeo con instrucciones

Si necesitas una explicación paso a paso de cómo implementar una integración, puedes ver este vídeo.

Se ha producido un error

Tenemos problemas para reproducir este vídeo.

Más información

Preguntas frecuentes

¿Qué tipo de eventos de mensajes admite la API de conversiones para mensajes empresariales?

R: La API de conversiones para mensajes empresariales actualmente solo admite eventos enviados por los clientes potenciales y de compra con los mensajes empresariales. Ten en cuenta que los eventos de mensajes solo deben representar las interacciones con los clientes que se producen en la conversación, no las conversiones que se producen en otros canales (como los sitios web). Puedes diferenciar fácilmente tus eventos si eliges el origen de acción correspondiente durante el proceso de integración.

¿Hay instrucciones de Meta para mantener las mismas aplicaciones o usar otras diferentes para diferentes integraciones de la API de conversiones?

R: Es una práctica recomendada que un socio use una aplicación para que Meta pueda identificar todos los eventos enviados por el socio. Si eres un socio que ya tiene varias aplicaciones, asegúrate de que el valor de partner_agent esté establecido en el nombre del agente del socio que se te ha asignado. Habla con tu representante de Meta en caso de duda.

Si una conversión se produce fuera de la conversación (por ejemplo, en mi sitio web o mi aplicación), ¿cómo pasamos los eventos a Meta?

R: Aunque una conversión se produzca fuera de la conversación, debes devolver ese evento a Meta con el producto pertinente de la API de conversiones. Por ejemplo, si se produce una conversión en el sitio web, usa la API de conversiones para la web. Si la conversión se produce en la aplicación, usa la API de conversiones para eventos de la aplicación. El evento se atribuirá al identificador del clic para la API de conversiones para la web. Puedes encontrar la lista completa de parámetros aquí.

¿La API de conversiones permite la optimización de anuncios de clic para enviar mensajes?

R: La API de conversiones permite acceder a la optimización de compras solo para los anuncios de clic a Messenger, pero no está disponible para la optimización de anuncios de WhatsApp en estos momentos. En el caso de los anuncios de clic a WhatsApp, puedes optimizar las campañas publicitarias para impulsar más conversaciones.

¿Puedo reutilizar el conjunto de datos existente con API de conversiones para mensajes empresariales?

R: Sí, admitimos la vinculación con un conjunto de datos existente; puedes consultar las opciones disponibles para decidir la opción correcta para tu empresa.

Si en la actualidad estoy usando la API de conversiones para el sitio web, ¿añadir mensajes empresariales a la misma integración interferirá con la integración existente?

R: Añadir mensajes empresariales a la integración actual de la API de conversiones no implica ningún riesgo. La atribución se basa en el identificador de la página o el conjunto de datos y no está relacionada con el identificador de la aplicación.

¿Cuántos conjuntos de datos se pueden vincular a una página?

R: Solo puedes vincular un conjunto de datos a una página.

¿Tengo que eliminar los eventos duplicados antes de enviarlos con la API de conversiones para mensajes empresariales?

R: Meta no ayuda a eliminar los eventos duplicados de la API de conversiones para mensajes empresariales, por lo que animamos a los anunciantes a eliminarlos antes de enviarlos con la API de conversiones para mensajes empresariales.

Más información

Información general sobre la API de conversiones
Usar la API de conversiones
Parámetros de la API de conversiones
Prácticas recomendadas
Plataforma de WhatsApp Business (API local o API de nube) con las versiones 2.45.1 y posteriores de la API de WhatsApp Business
API de mensajes de Instagram