API de Conversões

API de Conversões para mensagens empresariais

A API de Conversões permite que os anunciantes enviem eventos da web, do app e da loja física, bem como eventos de mensagens empresariais, à Meta por meio de um único ponto de extremidade em vez de várias fontes. Essa consolidação pode simplificar o recurso de tecnologia de um anunciante e criar uma visão mais abrangente no Gerenciador de Eventos da Meta usando conjuntos de dados.

Esta documentação fornece orientações para você integrar eventos de mensagens empresariais à API de Conversões. Os benefícios de usar a API de Conversões para mensagens empresariais incluem (mas não se limitam a):

  • Veja os resultados diretamente nos relatórios do Gerenciador de Anúncios: os anunciantes podem compreender facilmente os resultados da campanha de clique para mensagem com base em informações relevantes disponibilizadas pelas superfícies da Meta (por exemplo, o número de compras e o custo por compra, em vez de conversas iniciadas).
  • Simplifique a integração de dados: use uma API para processar e compartilhar dados em várias plataformas de mensagens (Messenger, WhatsApp) e canais (site, app, lojas, mensagens).
  • Melhore a mensuração do parceiro: habilite a atribuição de uma campanha de clique para mensagem diretamente nos painéis de parceiros por meio da API de Insights sobre Anúncios.

Pré-requisitos

Conjunto de dados

Os eventos de mensagens empresariais enviados através da API de Conversões precisam estar associados a um conjunto de dados.

Com os conjuntos de dados, os anunciantes podem conectar e gerenciar dados de eventos a partir de fontes de eventos de mensagens empresariais, da web, do app e da loja à API de Conversões. Os conjuntos de dados podem mostrar dados de eventos de qualquer uma destas integrações que você escolher configurar:

  • Pixel da Meta (eventos do site)
  • API de Eventos do App (eventos do app, incluindo o SDK do Facebook para iOS ou Android, Parceiros de Métricas para Aplicativos)
  • API de Conversões Offline (antiga API da Meta para eventos offline)

Com os conjuntos de dados, você pode visualizar todas as atividades do cliente em uma única interface. Eles também simplificam o processo de criar e manter várias integrações de API.

No Gerenciador de Eventos, os anunciantes têm diferentes opções para criar um conjunto de dados dependendo do ponto de partida. Você também pode gerar um novo conjunto de dados no Gerenciador de Eventos durante a criação do conjunto de eventos offline, por meio de um app para celular existente ou durante a criação do conjunto de eventos de mensagens. Antes de enviar eventos do app à API de Conversões, é preciso vincular um app único a um conjunto de dados. Veja mais detalhes e instruções aqui.

Permissões

Integração de parceiros

Se estiver implementando uma plataforma de parceiro, será possível usar o Login do Facebook para Empresas (recomendado) ou a Extensão da Meta para Empresas como métodos de integração.

Consulte o Conversions API for Business Messaging Guidebooks, que contém guias de integração com instruções passo a passo.

API do Conjunto de Dados para mensagens e WhatsApp

A API do Conjunto de Dados é usada para recuperar o dataset_id que está anexado à página fornecida. Esse dataset_id será usado mais tarde na API de Conversões. Para poder usar a API do Conjunto de Dados, será preciso obter a permissão page_events para eventos do Messenger ou do WhatsApp, que é concedida pelo cliente ao seu app através do Login do Facebook para Empresas ou da Extensão da Meta para Empresas.

Para recuperar o dataset_id, faça uma chamada GET à API do Conjunto de Dados com a page_id e o access_token. Veja o exemplo de chamada abaixo:

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

A resposta será um ID, que representa o dataset_id. Com esse ID e o token de acesso recebido anteriormente, você pode chamar a API de Conversões para enviar eventos de mensagens à Meta.

API do Conjunto de Dados para o Instagram

A API do Conjunto de Dados é usada para recuperar o dataset_id que está anexado à página fornecida. Esse dataset_id será usado mais tarde na API de Conversões. Para poder usar a API do Conjunto de Dados, será preciso obter a permissão instagram_manage_events, que é concedida pelo cliente ao seu app através do Login do Facebook para Empresas ou da Extensão da Meta para Empresas.

Para recuperar o dataset_id, faça uma chamada GET à API do Conjunto de Dados com o ig_user_id e o access_token. Veja um exemplo de chamada:

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

A resposta será um ID, que representa o dataset_id. Com esse ID e o token de acesso recebido anteriormente, você pode chamar a API de Conversões para enviar eventos de mensagens à Meta.

Configuração

Configurar parâmetros de evento de mensagens empresariais

Consulte aqui o conjunto atual de parâmetros que podem ser enviados usando a API de Conversões. Para enviar eventos de mensagens empresariais, os campos a seguir podem ser compartilhados na carga de dados do usuário para diferentes plataformas de mensagem:

PlataformaParâmetroDescrição

Messenger

page_id

Obrigatório para o Messenger

Identificação da Página do Facebook associada à empresa.

Messenger

page_scoped_user_id

Obrigatório para o Messenger

Os usuários que interagem com Páginas são identificados por números de identificação do usuário no escopo da Página (PSID, pelas iniciais em inglês). O PSID pode ser obtido a partir deste webhook.

WhatsApp

page_id

Obrigatório para o WhatsApp

Identificação da Página do Facebook associada ao WhatsApp Business.

WhatsApp

ctwa_clid

Obrigatório para o WhatsApp

ctwa_clid só está disponível a partir do objeto referral do webhook de mensagens na WhatsApp Business API v2.45.1 e em versões posteriores (API Local) ou API de Nuvem.

Instagram

ig_account_id

Obrigatório para o Instagram

Número de identificação da conta do Instagram associada à empresa.

Instagram

ig_sid

Obrigatório para o Instagram

Os usuários que interagem com o Instagram são identificados por números de identificação do usuário com escopo do Instagram (IGSID, pelas iniciais em inglês). O IGSID pode ser obtido a partir deste webhook.


Como enviar eventos

Para enviar novos eventos, faça uma solicitação POST à API de Conversões a partir deste caminho:

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

Quando você publica nesta borda, a Meta cria novos eventos de mensagens empresariais. Para mais detalhes, consulte este documento para desenvolvedores.

Confira uma visão geral de como os parâmetros se ajustam ao esquema geral da carga:

Para eventos do 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 do 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 do Instagram:

Exemplo de solicitação da CAPI (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>"
}

Solução de problemas

Para testar, use a ferramenta Eventos de Teste no Gerenciador de Eventos:

  • Acesse o Gerenciador de Eventos e selecione um conjunto de dados vinculado à página.
  • Clique na aba Eventos de Teste.
  • Selecione o canal de marketing e o de mensagens.
  • Clique no botão Explorador da Graph API.
  • O Explorador da Graph API será preenchido com a carga predefinida.
  • Clique no botão Enviar.

Passo a passo em vídeo

Veja este vídeo para conferir uma explicação passo a passo de como implementar uma integração.

Ocorreu um erro
Estamos tendo problemas ao reproduzir este vídeo.
Saiba mais

Perguntas frequentes

Que tipo de eventos de mensagens são compatíveis com a API de Conversões para mensagens empresariais?

R. No momento, a API de Conversões para mensagens empresariais é compatível apenas com cadastros enviados e eventos de compra. Observe que os eventos de mensagens devem representar apenas interações com os clientes que ocorrem no tópico das mensagens, e não conversões que acontecem em outros canais, como sites. É possível diferenciar seus eventos escolhendo a fonte de ação correspondente durante o processo de integração.

Há orientação da Meta sobre usar um ou vários apps para diferentes integrações da API de Conversões?

R. Como uma boa prática, o parceiro deve usar um único app para que a Meta possa identificar todos os eventos enviados por ele. Se você for um parceiro que possui vários apps, defina partner_agent como o nome do agente de parceiro atribuído a você. Em caso de dúvidas, fale com seu representante da Meta.

Quando uma conversão ocorre fora do tópico da mensagem (por exemplo, no meu site ou app), como posso enviar os eventos à Meta?

R. Se uma conversão acontecer fora do tópico da mensagem, você ainda poderá enviar esse evento à Meta usando o produto relevante da API de Conversões. Por exemplo, se acontecer uma conversão no site, use a API de Conversões para a web. Caso a conversão ocorra no app, use a API de Conversões para eventos do app. O evento ainda será atribuído ao ID de clique para a API de Conversões para a web. A lista completa de parâmetros pode ser encontrada aqui.

A API de Conversões permite a otimização de anúncios de clique para mensagem?

R. A API de Conversões permite o acesso à otimização de compras apenas para anúncios de clique para o Messenger. No entanto, ela não está disponível no momento para otimização de anúncios do WhatsApp. Para anúncios de clique para o WhatsApp, você pode otimizar suas campanhas para gerar mais conversas.

Posso reutilizar o conjunto de dados existente com a API de Conversões para mensagens empresariais?

R. Sim, aceitamos a vinculação com um conjunto de dados existente. Consulte as opções disponíveis para decidir a opção certa para sua empresa.

Se eu já estiver usando a API de Conversões para o site, adicionar mensagens empresariais interferirá na minha integração?

R. Não há riscos em adicionar mensagens empresariais à sua integração da CAPI existente. A atribuição é baseada na identificação da página/do conjunto de dados e não está relacionada com o ID do app.

Quantos conjuntos de dados podem ser vinculados a uma página?

R. Só é possível associar um conjunto de dados a uma página.

Preciso desduplicar eventos antes de enviá-los usando a API de Conversões para mensagens empresariais?

R. A Meta não ajuda a desduplicar eventos para a API de Conversões para mensagens empresariais. Por isso, recomendamos que os anunciantes realizem a desduplicação antes de enviar os eventos usando a API em questão.

Veja também