Envío WhatsApp de eventos de conversión en AWS Mensajería para usuarios finales en redes sociales

Si publicas campañas con el lema «Anuncios que hacen clic WhatsApp»Meta, puedes enviar los eventos de conversión (como compras, clientes potenciales o visualizaciones de contenido) a Meta fin de atribuirlos y optimizarlos. Envía estos eventos directamente a través de las redes sociales de mensajería para usuarios AWS finales, sin necesidad de utilizar la API Meta Graph.

AWS End User Messaging Social proporciona dos API para este flujo de trabajo:

• CreateWhatsAppDataset— Crea (o recupera) el conjunto de datos de conversiones para tu cuenta WhatsApp empresarial (WABA). Un conjunto de datos es el contenedor que Meta utiliza para recibir y atribuir tus eventos de conversión.

• SendWhatsAppConversionEvent— Envía uno o más eventos de conversión a la API de Meta conversiones, donde se atribuyen al clic en el anuncio que inició la WhatsApp conversación.

Cómo funciona el seguimiento de eventos de conversión

El flujo de trabajo de principio a fin es:

1. Un cliente hace clic en tu anuncio WhatsApp «Haz clic para» Meta e inicia una conversación con tu empresa.

2. El mensaje entrante llega al destino del evento que hayas configurado (tema de Amazon SNS EventBridge, Amazon o Amazon Connect). Incluye un ctwa_clid (identificador de clic a clic) que identifica el WhatsApp clic en el anuncio. La aplicación debe capturar y almacenar este valor.

3. Cuando se produce una conversión (por ejemplo, cuando el cliente realiza una compra), la aplicación llama SendWhatsAppConversionEvent con los detalles del evento ctwa_clid y.

4. AWS End User Messaging Social reenvía el evento a la API de Meta conversiones para su atribución.

ctwa_clidSe incluye en el referral objeto de la carga útil de los webhooks de los mensajes entrantes cuando un cliente inicia una conversación desde un anuncio. En el siguiente ejemplo, se muestra la parte correspondiente del mensaje del webhook:

{
  "messages": [
    {
      "from": "12345678",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "referral": {
        "body": "This is a great product",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",
        "headline": "Our new product",
        "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"
    }
  ]
}

Almacene el ctwa_clid valor del referral objeto. Añádelo a cada evento user_data de conversión que envíes para esta conversación. Para obtener más información sobre el webhook de referencia, consulta los componentes de los Webhooks en la documentación para Meta desarrolladores.

Requisitos previos

Antes de enviar eventos de conversión, necesitas lo siguiente:

• Una cuenta WhatsApp empresarial (WABA) vinculada a tu AWS cuenta.

• Hay una campaña activa de «Anuncios que hacen clic WhatsApp». Meta

• Tu aplicación debe capturar el webhook ctwa_clid de los mensajes entrantes cuando un cliente inicia una conversación haciendo clic en un anuncio. Este valor lo genera Meta y no se puede fabricar.

importante

Si has vinculado tu cuenta WhatsApp empresarial (WABA) antes del 6 de agosto de 2026, debes volver a iniciar sesión para conceder permisos a AWS End User Messaging Social para enviar eventos de conversión. Sigue los pasos del 1 al 14 de la sección «Registrarse a través de la consola» en la sección Registrarse y selecciona la WABA y el número de teléfono existentes que ya están asociados a tu cuenta. WhatsApp AWS A continuación, puedes saltarte los pasos restantes.

Paso 1: Crea un conjunto de datos de conversiones

Antes de poder enviar eventos de conversión, debes crear un conjunto de datos de conversiones para tu WABA. Cada WABA tiene exactamente un conjunto de datos (esto lo exigeMeta). La operación es idempotente: si ya existe un conjunto de datos, se devuelve el ID del conjunto de datos existente.

El siguiente ejemplo crea o recupera el conjunto de datos para una WABA. waba-idSustitúyelo por el ARN de tu cuenta WhatsApp empresarial vinculada (WABA) (por ejemplo,). arn:aws:social-messaging:us-east-1:123456789012:waba/a1b2c3d4e5example

aws socialmessaging create-whatsapp-dataset \
    --region us-east-1 \
    --id waba-id

La respuesta contiene el ID del conjunto de datos. Guarde este valor. Lo pasas como datasetId parámetro cada vez que envías un evento de conversión.

{
    "datasetId": "123456789012345"
}

Paso 2: Enviar eventos de conversión

Después de crear un conjunto de datos, puedes enviar los eventos de conversión a Meta través de la SendWhatsAppConversionEvent API. Cada llamada envía uno o más eventos a la API de Meta conversiones para su atribución.

El contenido del evento que envías en el event-data parámetro sigue el formato servidor-evento de la API de Meta conversiones. AWS End User Messaging Social reenvía este contenido a. Meta Para ver la lista completa de campos de eventos, consulta la referencia a los parámetros Meta de eventos del servidor en la Meta documentación para desarrolladores.

Envía un evento de conversión de compra

En el siguiente ejemplo, se informa de una Purchase conversión. Sustituya los valores de los marcadores de posición por los suyos propios.

aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            },
            "custom_data": {
                "currency": "USD",
                "value": 99.99
            }
        }
    ]
}'

La respuesta contiene un identificador de solicitud que identifica tu envío:

{
    "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}

Envía un evento de conversión de clientes potenciales

Non-purchase tipos de eventos como los LeadSubmitted que no se requierencustom_data.

aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "LeadSubmitted",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            }
        }
    ]
}'

Envía varios eventos en una sola solicitud

La data matriz acepta varios eventos en una sola llamada. Metapermite hasta 1000 eventos por solicitud.

aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "ViewContent",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            }
        },
        {
            "event_name": "Purchase",
            "event_time": 1720000500,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            },
            "custom_data": {
                "currency": "USD",
                "value": 149.00
            }
        }
    ]
}'

Referencia de eventos de conversión

El event-data parámetro es un objeto JSON con una data matriz que contiene uno o más objetos de evento. En las tablas siguientes se describen los campos que se utilizan con más frecuencia en las conversiones de «anuncios que generan clics WhatsApp». Metaes la fuente fiable del contenido de los eventos; consulta la referencia a los parámetros Meta de eventos entre servidores en la documentación para Meta desarrolladores para ver las especificaciones completas.

Campos de eventos obligatorios

Campo	Tipo	Description (Descripción)
event_name	Cadena	El tipo de conversión. Case-sensitive. Los valores comunes incluyen PurchaseLeadSubmitted, yViewContent.
event_time	Número	La hora a la que se produjo la conversión, expresada en segundos como marca de tiempo de Unix. Debe estar dentro de los últimos 7 días y no en el futuro.
action_source	Cadena	Debe ser business_messaging.
messaging_channel	Cadena	El canal de mensajería. Utilice whatsapp.
user_data	Objeto	Información utilizada para hacer coincidir el evento con el clic en el anuncio. Consulte Campos obligatorios de user_data.

Campos obligatorios de user_data

En la siguiente tabla se describen los campos obligatorios del user_data objeto.

Campo	Tipo	Description (Descripción)
whatsapp_business_account_id	Cadena	El identificador numérico Meta WhatsApp de tu cuenta empresarial (desde la configuración Meta empresarial).
ctwa_clid	Cadena	El identificador de clic a WhatsApp clic que aparece en el webhook de mensajes entrantes de la conversación que inició el anuncio. Metavalida este valor; no se puede fabricar.

importante

Si incluye información de identificación personal (PII)user_data, como direcciones de correo electrónico o números de teléfono, debe proporcionar los valores en forma de hashes. SHA-256 Metarechaza la PII sin hash. El ctwa_clid valor no está codificado.

El objeto custom_data

En el Purchase caso de los eventos, debes incluir el custom_data objeto con los siguientes campos:

Campo	Tipo	Description (Descripción)
currency	Cadena	El código de moneda ISO 4217 (por ejemplo,USD).
value	Número	El valor monetario de la conversión.

Gestión de errores

Dado que AWS End User Messaging Social reenvía el contenido de tu evento aMeta, la mayoría de los problemas relacionados con el contenido de los eventos surgen como un. InvalidParametersException El mensaje de error incluye el motivo por el que informaMeta, por ejemplo: un nombre de evento no reconocido, la hora del evento fuera del plazo permitido, la moneda faltante para una compra, la información de identificación personal no cifrada o una información no válida. ctwa_clid

Error	Estado HTTP	Significado
InvalidParametersException	400	El contenido de la solicitud o el evento no era válido. El mensaje de error describe el problema específico.
ResourceNotFoundException	404	No se encontró el WABA o el conjunto de datos especificados.
AccessDeniedByMetaException	403	Metarechazó la solicitud debido a los permisos (por ejemplo, el token de Meta acceso subyacente carece del permiso requerido o no es válido).
ThrottledRequestException	429	La tasa de solicitudes superó el límite permitido. Vuelva a intentarlo con retroceso exponencial.
DependencyException	502	Una dependencia descendente (Meta) devolvió un error. Se puede volver a intentar.
InternalServiceException	500	Se ha producido un error interno. Se puede volver a intentar.