Enviando eventos WhatsApp de conversão em AWS Mensagens sociais para o usuário final

Se você veicular campanhas “Anúncios que clicam para WhatsApp”Meta, poderá enviar eventos de conversão (como compras, leads ou visualizações de conteúdo) de volta Meta para atribuição e otimização de anúncios. Envie esses eventos diretamente pelo AWS End User Messaging Social, sem chamar a Meta Graph API.

AWS O End User Messaging Social fornece duas APIs para esse fluxo de trabalho:

• CreateWhatsAppDataset— Cria (ou recupera) o conjunto de dados de conversões para sua conta WhatsApp comercial (WABA). Um conjunto de dados é o contêiner Meta usado para receber e atribuir seus eventos de conversão.

• SendWhatsAppConversionEvent— Envia um ou mais eventos de conversão para a API de Meta conversões, onde eles são atribuídos ao clique no anúncio que iniciou a WhatsApp conversa.

Como funciona o acompanhamento de eventos de conversão

O fluxo de trabalho de ponta a ponta é:

1. Um cliente clica no anúncio “Clique para WhatsApp” Meta e inicia uma conversa com sua empresa.

2. A mensagem de entrada chega ao destino configurado do evento (tópico do Amazon SNS EventBridge, Amazon ou Amazon Connect). Ele inclui um ctwa_clid (ID de clique para clicar) que identifica o WhatsApp clique no anúncio. Seu aplicativo deve capturar e armazenar esse valor.

3. Quando ocorre uma conversão (por exemplo, o cliente faz uma compra), seu aplicativo liga SendWhatsAppConversionEvent com os detalhes do evento ctwa_clid e.

4. AWS O End User Messaging Social encaminha o evento para a API de Meta conversões para atribuição.

O ctwa_clid é incluído no referral objeto da carga útil do webhook de mensagem de entrada quando um cliente inicia uma conversa a partir de um anúncio. O exemplo a seguir mostra a parte relevante da mensagem do 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"
    }
  ]
}

Armazene o ctwa_clid valor do referral objeto. Passe-o user_data de cada evento de conversão que você enviar para essa conversa. Para obter mais informações sobre o webhook de referência, consulte Componentes de webhooks na documentação do Meta desenvolvedor.

Pré-requisitos

Antes de enviar eventos de conversão, você precisa do seguinte:

• Uma conta WhatsApp comercial (WABA) vinculada à sua AWS conta.

• Uma campanha ativa “Anúncios que clicam para WhatsApp” ativadaMeta.

• Seu aplicativo deve capturar o webhook ctwa_clid da mensagem recebida quando um cliente inicia uma conversa com um clique no anúncio. Esse valor é gerado por Meta e não pode ser fabricado.

Importante

Se você vinculou sua conta WhatsApp comercial (WABA) antes de 6 de agosto de 2026, deverá refazer o fluxo de inscrição para conceder permissões ao usuário AWS final Messaging Social para enviar eventos de conversão. Siga as etapas de 1 a 14 em “Inscrever-se pelo console” em Inscrever-se e selecione o WABA existente e o número de telefone já associados à sua AWS conta. WhatsApp Em seguida, você pode pular as etapas restantes.

Etapa 1: criar um conjunto de dados de conversões

Antes de enviar eventos de conversão, você deve criar um conjunto de dados de conversões para seu WABA. Cada WABA tem exatamente um conjunto de dados (isso é imposto por). Meta A operação é idempotente: se um conjunto de dados já existir, o ID do conjunto de dados existente será retornado.

O exemplo a seguir cria ou recupera o conjunto de dados de um WABA. waba-idSubstitua pelo ARN da sua conta WhatsApp comercial vinculada (WABA) (por exemplo,arn:aws:social-messaging:us-east-1:123456789012:waba/a1b2c3d4e5example).

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

A resposta contém o ID do conjunto de dados. Salve esse valor. Você o passa como datasetId parâmetro toda vez que envia um evento de conversão.

{
    "datasetId": "123456789012345"
}

Etapa 2: enviar eventos de conversão

Depois de criar um conjunto de dados, você pode enviar eventos de conversão para Meta usar a SendWhatsAppConversionEvent API. Cada chamada entrega um ou mais eventos à API de Meta conversões para atribuição.

O conteúdo do evento que você envia no event-data parâmetro segue o formato Meta servidor-evento da API Conversions. AWS O End User Messaging Social encaminha esse conteúdo paraMeta. Para ver a lista completa dos campos de eventos, consulte a referência de parâmetros Meta de eventos do servidor na documentação do Meta desenvolvedor.

Enviar um evento de conversão de compra

O exemplo a seguir relata uma Purchase conversão. Substitua os valores dos espaços reservados pelos seus próprios.

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
            }
        }
    ]
}'

A resposta contém um ID de solicitação que identifica seu envio:

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

Envie um evento de conversão de leads

Non-purchase tipos de eventos, como LeadSubmitted não exigemcustom_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"
            }
        }
    ]
}'

Envie vários eventos em uma solicitação

A data matriz aceita vários eventos em uma única chamada. Metapermite até 1.000 eventos por solicitação.

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
            }
        }
    ]
}'

Referência do evento de conversão

O event-data parâmetro é um objeto JSON com uma data matriz contendo um ou mais objetos de evento. As tabelas a seguir descrevem os campos mais usados para conversões de “Anúncios que clicam em WhatsApp”. Metaé a fonte confiável do conteúdo do evento; consulte a referência de parâmetros de Meta eventos do servidor na documentação do Meta desenvolvedor para obter a especificação completa.

Campos de evento obrigatórios

Campo	Tipo	Description
event_name	String	O tipo de conversão. Case-sensitive. Os valores comuns incluem PurchaseLeadSubmitted, ViewContent e.
event_time	Número	A hora em que a conversão aconteceu, como um timestamp Unix em segundos. Deve estar nos últimos 7 dias e não no futuro.
action_source	String	Deve ser business_messaging.
messaging_channel	String	O canal de mensagens. Use whatsapp.
user_data	Objeto	Informações usadas para combinar o evento com o clique no anúncio. Consulte Campos obrigatórios de user_data.

Campos obrigatórios de user_data

A tabela a seguir descreve os campos obrigatórios no user_data objeto.

Campo	Tipo	Description
whatsapp_business_account_id	String	Seu ID numérico Meta WhatsApp de conta comercial (nas Configurações Meta comerciais).
ctwa_clid	String	O ID de clique para WhatsApp clicar do webhook de mensagens recebidas da conversa iniciada pelo anúncio. Metavalida esse valor; ele não pode ser fabricado.

Importante

Se você incluir informações de identificação pessoal (PII)user_data, como endereços de e-mail ou números de telefone, deverá fornecer os valores como hashes. SHA-256 Metarejeita PII sem hash. O ctwa_clid valor não está codificado.

O objeto custom_data

Para Purchase eventos, você deve incluir o custom_data objeto com os seguintes campos:

Campo	Tipo	Description
currency	String	O código monetário ISO 4217 (por exemplo,USD).
value	Número	O valor monetário da conversão.

Tratamento de erros

Como o AWS End User Messaging Social encaminha o conteúdo do seu evento paraMeta, a maioria dos problemas de conteúdo do evento surge como um. InvalidParametersException A mensagem de erro inclui o motivo relatado porMeta, por exemplo: um nome de evento não reconhecido, um horário do evento fora da janela permitida, moeda ausente para uma compra, PII sem hash ou uma mensagem inválida. ctwa_clid

Erro	Status HTTP	Significado
InvalidParametersException	400	O conteúdo da solicitação ou do evento era inválido. A mensagem de erro descreve o problema específico.
ResourceNotFoundException	404	O WABA ou o conjunto de dados especificado não foram encontrados.
AccessDeniedByMetaException	403	Metarejeitou a solicitação devido a permissões (por exemplo, o token de Meta acesso subjacente não tem a permissão necessária ou é inválido).
ThrottledRequestException	429	A taxa de solicitação excedeu o limite permitido. Novas tentativas com recuo exponencial.
DependencyException	502	Uma dependência downstream (Meta) retornou um erro. Tentável novamente.
InternalServiceException	500	Ocorreu um erro interno. Tentável novamente.