API de conversiones para mensajes empresariales: guía de incorporación

La API de conversiones es una herramienta de Meta para empresas que permite a los partners de mensajería para empresas compartir los datos (para los cuales tienen permisos) de sus clientes directamente desde sus servidores y que está diseñada para cumplir automáticamente con los controles de privacidad de los usuarios de Meta. Esto permite a los partners de mensajería para empresas enviar de manera fiable los datos sobre interacciones valiosas entre sus clientes y los usuarios en los chats empresariales a fin de entender y mejorar el rendimiento de los anuncios de clic a WhatsApp, Messenger o Instagram de sus clientes, mejorando así la eficiencia operativa y haciendo crecer sus negocios.

Esta guía está diseñada para ayudar a los partners de mensajería para empresas a completar la integración técnica de la API de conversiones para WhatsApp, Messenger o Instagram en nombre de sus clientes. Abarca los siguientes temas:

Requisitos previos a la integración
Pasos de la integración
Envío de eventos con la API de conversiones
Verificación de eventos con el Administrador de eventos

Nota: La API de conversiones también permite a los anunciantes enviar a Meta eventos del sitio web, la aplicación, eventos offline (incluidas las tiendas físicas) y de CRM. Actualmente, los partners de mensajería para empresas que hayan integrado la API de conversiones para otros casos de uso todavía necesitan seguir los siguientes pasos a fin de integrar la API de conversiones para mensajes empresariales.

Anuncios de clic a Messenger

Requisitos previos a la integración

Antes de empezar la integración, es necesario asegurarse de que se establezcan las bases técnicas adecuadas y se concedan los accesos pertinentes para activos y plataformas específicos.

Crear una aplicación de desarrollador de Facebook

Si aún no tienes una, sigue las instrucciones para crearla.

Integrarla con la API de Messenger

Tener acceso avanzado a lo siguiente:

El permiso page_events.
- Necesitarás solicitar acceso avanzado para el permiso page_events en la sección “Permisos y funciones” del panel de aplicaciones para desarrolladores. Si ya tienes acceso avanzado para el permiso pages_messaging, el permiso page_events se deberá aprobar automáticamente para la aplicación cuando lo solicites.
La función de acceso estándar a la administración de anuncios. Puedes encontrar instrucciones adicionales aquí.
- Para poder utilizar la función de acceso avanzado, necesitarás haber realizado correctamente un total de 1500 llamadas a la API de marketing con una tasa de error inferior al 10 % en los últimos 15 días. Esto incluye las llamadas realizadas mediante la API de conversiones por un usuario con un rol en la aplicación.

Pasos de la integración

1. Obtener el identificador de acceso

Para poder llamar a la API de conjuntos de datos y la API de conversiones, necesitarás un identificador de acceso con los siguientes permisos:

page_events

Reutiliza el identificador generado en el inicio de sesión con Facebook para empresas.

2. Obtener el valor de page_id

Asegúrate de conocer el identificador de la página para la que quieres notificar eventos.

3. Configurar el conjunto de datos

Al compartir datos de eventos con Meta mediante la API de conversiones, Meta necesita saber el origen que está asociado con esos eventos. Los conjuntos de datos te permiten vincular y administrar datos de eventos de diferentes orígenes (como tu sitio web, tu aplicación para móviles, tu establecimiento físico o los chats empresariales) en un solo lugar. Puedes obtener más información sobre los conjuntos de datos aquí.

Los conjuntos de datos se crean mediante las plataformas de partners o directamente en el Administrador de eventos. La empresa es propietaria del conjunto de datos y, si la empresa trabaja con un socio, también se concederá acceso al conjunto de datos al socio.

Utiliza el valor de page_id y access_token para crear un conjunto de datos realizando una llamada POST a la API de conjuntos de datos. Si ya existe un valor de dataset_id asociado a la página, se devolverá ese identificador. A continuación, se muestra un ejemplo de llamada:

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 del inicio de sesión con Facebook para empresas, ahora puedes llamar a la API de conversiones para enviar eventos de mensajes a Meta.

Nota: Si la página está asociada a una cuenta empresarial y el permiso business_management se concede en la cuenta empresarial, el conjunto de datos aparecerá en dicha cuenta empresarial. De lo contrario, se ocultará al anunciante.

4. Recuperar el identificador específico de la página (PSID)

El identificador específico de la página (PSID) es un identificador que representa al usuario en una conversación entre este y una empresa. Este identificador se expone mediante el webhook de mensajes y se usa en la API de envío y recepción. También se utiliza en la API de conversiones al enviar eventos de conversión asignados a un usuario (PSID) concreto.

Asegúrate de conocer el PSID de la página para la que quieres notificar señales.

Enviar eventos con la API de conversiones

En la etapa final de la integración, ahora puedes enviar eventos mediante la API de conversiones con toda la información (access_token, page_id, dataset_id, PSID) obtenida en los pasos anteriores.

Durante el periodo de la campaña, dado que los eventos ocurren en tiempo real, notifica a Meta sobre estos eventos mediante la API de conversiones usando el valor de dataset_id y access_token. Realiza una solicitud POST a la siguiente API:

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

A continuación, se muestra un ejemplo de llamada a la API para un evento de compra único.

{
  "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>"
}

Verificar eventos con el Administrador de eventos

Una vez que se haya enviado correctamente un evento a Meta mediante la API de conversiones, deberías poder ver dicho evento reflejado en el Administrador de eventos para el conjunto de datos en particular. Puedes obtener más información sobre el Administrador de eventos y su uso aquí.

Nota: Si eres un socio, deberás dar instrucciones a tu anunciante sobre cómo acceder al conjunto de datos en el Administrador de eventos a fin de verificar que los eventos se reciben.

Anuncios de clic a WhatsApp

Requisitos previos a la integración

Antes de empezar la integración, es necesario asegurarse de que se establezcan las bases técnicas adecuadas y se concedan los accesos pertinentes para activos y plataformas específicos.

Crear una aplicación de desarrollador de Facebook

Si aún no tienes una, sigue las instrucciones para crearla.

Tener acceso avanzado a lo siguiente:

El permiso whatsapp_business_management.
El permiso whatsapp_business_manage_events.
- Necesitarás solicitar acceso avanzado para el permiso whatsapp_business_manage_events en la sección “Permisos y funciones” del panel de aplicaciones para desarrolladores. Si ya tienes acceso avanzado para el permiso whatsapp_business_messaging, el permiso whatsapp_business_manage_events se deberá aprobar automáticamente para la aplicación cuando lo solicites.
La función de acceso estándar a la administración de anuncios para permitir a la aplicación acceder a la API de marketing. Puedes encontrar instrucciones adicionales aquí.
- Para poder utilizar la función de acceso avanzado, necesitarás haber realizado correctamente un total de 1500 llamadas a la API de marketing con una tasa de error inferior al 10 % en los últimos 15 días. Esto incluye las llamadas realizadas mediante la API de conversiones por un usuario con un rol en la aplicación.

Haberse integrado con una de las dos opciones de integración de la Plataforma de WhatsApp Business:

API de nube, alojada por Meta (opción recomendada).
API local (*versión de la API de WhatsApp Business: 2.45.1): el campo ctwa_clid, que es obligatorio para enviar eventos con la API de conversiones, solo está disponible en el webhook de mensajes en la versión 2.45.1 y posteriores de la API de WhatsApp Business. Nota: Durante los dos próximos años, la Plataforma de WhatsApp Business va a realizar la transición completa a nuestra API de nube de nueva generación. La última versión admitida del cliente de la API local caducará el 23 de octubre de 2025. Obtén más información.

Haberse integrado con una solución de inicio de sesión para la autenticación y la autorización (registro insertado o inicio de sesión con Facebook para empresas)

Pasos de la integración

1. Obtener el identificador de acceso

Para poder llamar a la API de conjuntos de datos y la API de conversiones, necesitarás un identificador de acceso con el siguiente permiso:

whatsapp_business_management
whatsapp_business_manage_events

Si te has integrado con el registro insertado, te recomendamos que reutilices el identificador generado en el proceso de registro insertado. Como alternativa, puedes utilizar un identificador de acceso de usuario del sistema de integración empresarial, un identificador de acceso de usuario del sistema o un identificador de acceso de usuario siempre y cuando contenga los permisos necesarios.

2. Recuperar el identificador de la cuenta de WhatsApp Business

El identificador de la cuenta de WhatsApp Business (waba_id) se puede obtener al completar el proceso de registro insertado. Consulta los detalles.

3. Configurar la API de conjuntos de datos

Al compartir datos de eventos con Meta mediante la API de conversiones, Meta necesita saber el origen que está asociado con esos eventos. Los conjuntos de datos permiten a los socios de soluciones empresariales de Meta vincular y administrar datos de eventos de diferentes orígenes (como el sitio web, la aplicación para móviles, el establecimiento físico o los chats empresariales del cliente) en un solo lugar. Puedes obtener más información sobre los conjuntos de datos aquí. Los conjuntos de datos son propiedad del cliente y los socios de soluciones empresariales de Meta pueden acceder a ellos con los permisos necesarios.

Puedes utilizar el valor de whatsapp_business_account_id y access_token para crear un conjunto de datos realizando una llamada POST a la API de conjuntos de datos. Si ya existe un valor de dataset_id asociado a la cuenta de WhatsApp Business, se devolverá ese identificador. A continuación, se muestra un ejemplo de llamada:

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

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

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

La respuesta será un identificador que representa el valor de dataset_id. Ahora tenemos el conjunto de datos configurado y listo para su uso. A continuación, deberás recuperar el valor de ctwa_clid, que es necesario para realizar una llamada a la API de conversiones para enviar un evento.

4. Recuperar el identificador de clic a WhatsApp

El identificador de clic a WhatsApp (ctwa_clid) es un identificador personal y único de cada clic que se expone a la empresa cuando el usuario que entra en la conversación se ha originado a partir de un anuncio de clic a WhatsApp. Este identificador tiene que devolverse a Meta mediante una llamada a la API de conversiones (consulta la sección siguiente como referencia).

El campo ctwa_cli se obtiene a partir del objeto de referencia en el webhook de mensajes (API de nube | API local).

Cuando recibas el valor de ctwa_clid, almacénalo con la conversación. Cuando la conversión se ha producido dentro de una conversación, envía el valor de ctwa_clid correspondiente mediante la API de conversiones. A continuación se incluye un ejemplo de mensaje recibido con un objeto de referencia que contiene un valor de ctwa_clid:

{
  "data": [
    {
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher "
      },
      "wa_id": "16315551234"
    }
  ],
  "messages": [
    {
      "from": "12345678",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "referral": {
        "body": "This is a great product",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
        "headline": "Our new product",
        "image": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45"
        },
        "source_id": "1234567890",
        "source_type": "ad",
        "source_url": "https://fb.me/AAAAA"
      },
      "text": {
        "body": "Can I learn more about your business?"
      },
      "timestamp": "1678189586",
      "type": "text"
    }
  ]
}

Enviar eventos con la API de conversiones

En la etapa final de la integración, ahora puedes enviar eventos mediante la API de conversiones con toda la información (waba_id, dataset_id, ctwa_clid) obtenida en los pasos anteriores.

Durante el periodo de la campaña de un anunciante, los eventos ocurren en tiempo real. Notifica a Meta sobre estos eventos mediante la API de conversiones usando el valor de dataset_id y el identificador de acceso. Realiza una solicitud POST a la siguiente API:

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

A continuación, se muestra un ejemplo de llamada a la API para un evento de compra único.

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

Verificar eventos con el Administrador de eventos

Nota: Si eres un socio, deberás dar instrucciones a tu anunciante sobre cómo acceder al conjunto de datos en el Administrador de eventos a fin de verificar que los eventos se reciben.

Anuncios de clic a Instagram Direct

Requisitos previos a la integración

Antes de empezar la integración, es necesario asegurarse de que se establezcan las bases técnicas adecuadas y se concedan los accesos pertinentes para activos y plataformas específicos.

Crear una aplicación de desarrollador de Facebook

Si aún no tienes una, sigue las instrucciones para crearla.

Integrarla con la API de Messenger

Tener acceso avanzado a lo siguiente:

El permiso instagram_manage_events.
- Necesitarás solicitar acceso avanzado para el permiso instagram_manage_events en la sección “Permisos y funciones” del panel de aplicaciones para desarrolladores. Si ya tienes acceso avanzado para el permiso instagram_manage_messages, el permiso instagram_manage_events se deberá aprobar automáticamente para la aplicación.
La función de acceso estándar a la administración de anuncios. Puedes encontrar instrucciones adicionales aquí.
- Para poder utilizar la función de acceso avanzado, necesitarás haber realizado correctamente un total de 1500 llamadas a la API de marketing con una tasa de error inferior al 10 % en los últimos 15 días. Esto incluye las llamadas realizadas mediante la API de conversiones por un usuario con un rol en la aplicación.

Pasos de la integración

1. Obtener el identificador de acceso

Para poder llamar a la API de conjuntos de datos y la API de conversiones, necesitarás un identificador de acceso con los siguientes permisos:

instagram_manage_events

Reutiliza el identificador generado en el inicio de sesión con Facebook para empresas.

2. Obtener el valor de instagram_user_id

Asegúrate de conocer el valor de instagram_user_id de la cuenta de Instagram para la que quieres notificar eventos.

3. Configurar el conjunto de datos

Utiliza el valor de instagram_user_id y access_token para crear un conjunto de datos realizando una llamada POST a la API de conjuntos de datos. Si ya existe un valor de dataset_id asociado al usuario de Instagram, se devolverá ese identificador. A continuación, se muestra 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 del inicio de sesión con Facebook para empresas, ahora puedes llamar a la API de conversiones para enviar eventos de mensajes a Meta.

4. Recuperar el identificador específico de Instagram (IGSID)

El identificador específico de Instagram (IGSID) es un identificador que representa al usuario en una conversación entre este y una empresa. Este identificador se expone a través del webhook de mensajes y se usa en la API de envío y recepción. También se usa en la API de conversiones al enviar eventos de conversión asignados a un usuario (IGSID) concreto (consulta la sección siguiente para obtener más información).

Asegúrate de conocer el valor de IGSID de la cuenta de Instagram para la que quieres notificar eventos.

Enviar eventos con la API de conversiones

En la etapa final de la integración, ahora puedes enviar eventos mediante la API de conversiones con toda la información (dataset_id, identificador de acceso, instagram_user_id, IGSID) obtenida en los pasos anteriores.

Durante el periodo de la campaña, dado que los eventos ocurren en tiempo real, notifica a Meta sobre estos eventos mediante la API de conversiones usando el valor de dataset_id y el identificador de acceso. Realiza una solicitud POST a la siguiente API:

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

A continuación, se muestra un ejemplo de llamada a la API para un evento de compra único.

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

Verificar eventos con el Administrador de eventos

Nota: Si eres un socio, deberás dar instrucciones a tu anunciante sobre cómo acceder al conjunto de datos en el Administrador de eventos a fin de verificar que los eventos se reciben.

Preguntas frecuentes

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

R: La API de conversiones para mensajes empresariales ahora admite los tipos de eventos para mensajes empresariales siguientes:

Purchase
LeadSubmitted
InitiateCheckout
AddToCart
ViewContent
OrderCreated
OrderShipped
OrderDelivered
OrderCanceled
OrderReturned
CartAbandoned
QualifiedLead
RatingProvided
ReviewProvided

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 y los anuncios de clic a WhatsApp, pero no está disponible para la optimización de anuncios de Instagram en estos momentos. En el caso de los anuncios de clic a Instagram, 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