API de conversiones para mensajes comerciales

La API de conversiones permite a los anunciantes enviar eventos web, de la app, de la tienda física y de mensajes comerciales a Meta a través de un único punto de conexión en lugar de hacerlo a través de orígenes múltiples. Esta consolidación puede simplificar la pila de tecnología de un anunciante y crear una vista más completa dentro del administrador de eventos de Meta si se utilizan conjuntos de datos.

Esta documentación proporciona orientación para integrar eventos de mensajes comerciales en la API de conversiones. Los beneficios de usar la API de conversiones en relación con los mensajes comerciales incluyen, entre otros, los siguientes:

• Ver los resultados directamente en los informes del administrador de anuncios: los anunciantes pueden entender fácilmente los resultados de la campaña de clic para enviar mensajes directamente en las superficies de Meta en función de los resultados de importancia, por ejemplo, el número de compras y el costo por compra, en lugar de las conversaciones iniciadas.
• Simplificar la integración de datos: una API para ingresar y compartir datos mediante múltiples plataformas de mensajes (Messenger, WhatsApp) y canales (sitio web, app, tiendas, mensajes).
• Mejorar la medición de los socios: permite la atribución de la campaña de clic para enviar mensaje directamente en los paneles de los socios a mediante la API de estadísticas de anuncios.

Requisitos previos

Conjunto de datos

Los eventos de mensajes comerciales enviados mediante la API de conversiones deben estar asociados a un conjunto de datos.

Los conjuntos de datos permiten a los anunciantes conectar y administrar datos de eventos enviados desde fuentes de datos web, app, tiendas y mensajería de negocios a la API de Conversiones. En los conjuntos de datos, pueden figurar datos de eventos de cualquiera de las siguientes integraciones que decidas configurar:

• Píxel de Meta (eventos del sitio web)
• API de eventos de la app (incluidos el SDK de Facebook para iOS o Android y socios de medición de dispositivos móviles [MMP])
• API de conversiones offline (API heredada de Meta para eventos offline)

Los conjuntos de datos te permiten ver todas las actividades del cliente desde una interfaz única. Además, te permiten reducir el esfuerzo para que puedas compilar y mantener múltiples integraciones de API.

En el administrador de eventos, los anunciantes tienen diferentes opciones para crear un conjunto de datos en función del punto de partida. O bien puedes crear un conjunto de datos de cero en el administrador de eventos mediante vinculación durante un evento offline, a través de una app para celulares preexistente o durante la configuración de información de creación de eventos de mensajes. Ten en cuenta que es necesario vincular un conjunto de datos a una app antes de enviar eventos de apps para celulares a la API de conversiones y solo se puede vincular una app a un conjunto de datos. Consulta más detalles e instrucciones aquí.

Permisos

• Si deseas implementar una integración directa como anunciante, sigue las instrucciones que se encuentran aquí para obtener los requisitos y permisos.

• 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 de administración de anuncios.
  • Según los tipos de eventos, necesitas tener acceso avanzado al permiso page_events para eventos de Messenger o WhatsApp, o a instagram_manage_events para Instagram Direct.

Registro de socios

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

Consulta las Guías de la API de conversiones para mensajes, que contienen información sobre la integración e instrucciones paso a paso.

API de conjunto de datos para mensajes y WhatsApp

La API de conjunto de datos se usa para recuperar el dataset_id que se adjunta a una determinada página. Este dataset_id se usará más adelante en la API de conversiones. Para poder usar la API de conjunto de datos, necesitarás el permiso page_events en relación con eventos de Messenger o WhatsApp que el cliente otorgó a tu app mediante el inicio de sesión con Facebook para empresas o la extensión Meta Business.

Para recuperar el dataset_id, necesitas hacer una llamada GET a la API de conjunto de datos con page_id y access_token. Consulta el ejemplo de llamada a continuación:

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

La respuesta será un identificador, que representa el dataset_id. Si utilizas ese indicador y el token de acceso que recibiste previamente, ahora puedes llamar a la API de conversiones para enviar eventos de mensaje a Meta.

API de conjunto de datos para Instagram

La API de conjunto de datos se usa para recuperar el dataset_id que se adjunta a una determinada página. Este dataset_id se usará más adelante en la API de conversiones. Para poder usar la API de conjunto de datos, necesitarás que el permiso instagram_manage_events que tu cliente le concedió a tu app mediante el inicio de sesión con Facebook para empresas o la extensión Meta Business.

Para recuperar el dataset_id, debes hacer una llamada GET a la API de conjunto de datos con ig_user_id y access_token. Este es 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 dataset_id. Si utilizas ese indicador y el token de acceso que recibiste previamente, ahora puedes llamar a la API de conversiones para enviar eventos de mensaje a Meta.

Configuración

Configurar parámetros del evento de mensajes comerciales

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

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}

Cuando publicas en este perímetro, Meta crea nuevos eventos de mensajes comerciales. Para obtener más detalles, consulta el siguiente documento para desarrolladores.

Aquí información general de cómo encajan los parámetros en el esquema general de la carga útil.

En relación con los 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>"
}

En relación con los 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>"
}

En relación con los eventos de Instagram:

Ejemplo de solicitud de la API de conversiones a clic a Direct

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 de eventos de prueba en el administrador de eventos para realizar las pruebas:

• Ve al administrador de eventos y selecciona un conjunto de datos vinculado a la página
• Haz clic en la pestaña Eventos de prueba
• 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 completará con la carga útil que se rellenó automáticamente.
• Haz clic en el botón "Enviar"

Recorrido en video

Mira este video para ver una explicación paso a paso de cómo implementar una integración.

Se produjo un error

Tenemos problemas para reproducir este video.

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 clientes potenciales enviados y eventos de compra para mensajes empresariales. Ten en cuenta que los eventos de mensajes solo deben representar las interacciones de los clientes que ocurren en el hilo de mensajes, pero no las conversiones que ocurren en otros canales, como sitios web. Puedes distinguir fácilmente tus eventos si eliges el origen de la acción correspondiente durante su proceso de integración.

¿Hay alguna orientación por parte de Meta para mantener la misma app o usar distintas apps para realizar diferentes integraciones de API de conversiones?

R: es una práctica recomendada que un socio use una app para que Meta pueda identificar todos los eventos que envió el socio. Si eres socio y ya tienes múltiples apps, asegúrate de que el valor partner_agent esté configurado en el nombre de agente del socio que se te asignó. Habla con tu representante de Meta si no estás seguro.

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

R: incluso si una conversión se produce fuera del hilo de mensajes, deberás devolver ese evento a Meta mediante el producto correspondiente de la API de conversión. Por ejemplo, si se produce una conversión en tu sitio web, usa la API de conversiones para la web. Si la conversión se produce en tu app, usa la API de conversiones para los eventos de la app. Se seguirá asignando el evento al identificador del clic de la API de conversiones para la web. La lista completa de parámetros se puede encontrar aquí.

¿La API de conversiones permite optimizar anuncios que hacen clic para enviar mensajes?

A: la API de conversiones solo activa el acceso a la optimización de compras de anuncios que hacen clic a Messenger, pero no está disponible para la optimización de anuncios de WhatsApp en este momento. En relación con los anuncios que hacen clic a WhatsApp, puedes optimizar tus campañas publicitarias para impulsar más conversaciones.

¿Puedo reutilizar el conjunto de datos anterior para la API de conversiones para mensajes empresariales?

R: sí. Admitimos la posibilidad de vincular con conjuntos de datos anteriores. Puedes consultar las opciones disponibles y decidir qué opción es la correcta para tu negocio.

Si en estos momento estoy usando la API de conversiones para el sitio web, ¿agregar mensajes empresariales a la misma integración interferirá con mi integración previa?

A: no hay riesgo al agregar mensajes empresariales a tu actual integración de la CAPI. La atribución se basa en el identificador de la página o del conjunto de datos y no está relacionada con el identificador de la app.

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

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

¿Necesito deduplicar los eventos antes de enviarlos mediante la API de conversiones para mensajes empresariales?

R: Meta no ayuda a deduplicar eventos para la API de conversiones para mensajes empresariales, por lo que recomendamos a los anunciantes realizar la deduplicación antes de enviarlos mediante la API de conversiones para mensajes empresariales.

Más información

• Información general de la API de conversiones
• Uso de la API de conversiones
• Parámetros de la API de conversiones
• Prácticas recomendadas
• Plataforma de WhatsApp Business (Instalaciones locales o API de la nube) con las versiones 2.45.1 y superiores de la API del negocio.
• API de mensajes de Instagram