Conversion API (CAPI)

A Conversion API (CAPI) envia para a Meta os marcos que acontecem dentro da conversa entre o lead e a Mia. Em vez de a Meta enxergar apenas o clique no anúncio, ela passa a receber o que aconteceu depois: o imóvel apresentado, a simulação feita, a visita agendada e a qualificação do lead.

Com esses eventos, a Meta otimiza a entrega para perfis parecidos com quem avança no funil, não apenas com quem clica no anúncio.

Primeira vez usando os eventos? Vá direto para Primeiros passos e volte depois para a referência de parâmetros.

O que é?

Integração servidor a servidor entre a Morada.ai e a Meta. Cada marco da conversa vira um evento de conversão enviado em tempo real para um conjunto de dados (o dataset do Gerenciador de Eventos). Os eventos ficam disponíveis para otimização de campanha, conversões personalizadas e criação de públicos.

Como funciona

O lead entra em contato

O lead clica no anúncio de Click to WhatsApp, preenche um formulário Meta Lead Ads ou chega por outro canal conectado.

A Mia conduz a conversa

A cada marco relevante (imóvel apresentado, simulação de financiamento, visita agendada, qualificação), a plataforma gera um evento.

O evento é enviado para a Meta

O evento chega no conjunto de dados da sua conta, junto com os parâmetros de segmentação.

Você usa os eventos nas campanhas

No Gerenciador de Eventos, os eventos viram conversões personalizadas e públicos, e passam a ser objetivo de otimização.

Onde os eventos chegam

Esta é a parte que mais gera dúvida na primeira configuração, porque a Meta trata o tráfego de WhatsApp de um jeito diferente do resto. Sua WABA (WhatsApp Business Account) é a conta que envia as mensagens do seu número. A Meta só aceita eventos de anúncios de Click to WhatsApp no conjunto de dados vinculado a essa WABA. Um Pixel de site, sozinho, não recebe esses eventos.

As três situações possíveis

Situação	O que acontece
Você já tem um conjunto de dados vinculado à WABA	Todos os eventos caem nesse conjunto, tanto os de anúncio quanto os de conversas orgânicas. É o cenário recomendado
Nenhum conjunto vinculado à WABA	No primeiro evento de Click to WhatsApp, a Morada cria um conjunto, vincula à sua WABA e passa a usá-lo para todos os eventos
Você configurou um Pixel que não é o vinculado à WABA	Vale o conjunto vinculado à WABA. O Pixel anterior mantém todo o histórico dele e deixa de receber eventos novos

A integração sempre converge para um único conjunto de dados: o que está vinculado à sua WABA. Se você quer que tudo caia num conjunto específico (por exemplo, o Pixel que já usa nos relatórios), vincule esse conjunto à WABA no Gerenciador de Eventos, nas configurações do conjunto de dados. A partir do próximo evento, a integração passa a usar ele.

Como saber qual conjunto está recebendo

No Gerenciador de Eventos, abra Fontes de dados e procure o conjunto vinculado à sua conta do WhatsApp Business. Na visão geral dele você vê os eventos chegando com os nomes descritos abaixo. Se você não encontrar nenhum evento, confirme antes se já houve conversa vinda de anúncio depois da ativação da integração: sem tráfego de Click to WhatsApp, o vínculo com a WABA ainda não foi criado.

Primeiros passos

O caminho completo, do primeiro evento até a campanha otimizada, usando como exemplo o empreendimento Loteamento Solar.

Confirme que os eventos estão chegando

No Gerenciador de Eventos, abra o conjunto de dados vinculado à sua WABA e veja a atividade recente. Você deve ver eventos como ConversationStarted e QualifiedLead.

Pegue o identificador do empreendimento

Você vai usar o property_id como filtro. Veja como descobrir o identificador do empreendimento logo abaixo. No exemplo, o Loteamento Solar é d4e5f6a7-8901-23ab-cdef-4567890123de.

Decida qual marco vale como conversão

Visita agendada costuma ser o marco mais próximo da venda; lead qualificado dá mais volume para a Meta aprender. Você pode criar as duas e testar.

Crie a conversão personalizada

No Gerenciador de Eventos, vá em Conversões personalizadas e crie uma nova a partir do conjunto de dados. Para o exemplo, filtre pelo evento InitiateCheckout (é o nome que a visita agendada recebe em campanhas de Click to WhatsApp) com property_id igual a d4e5f6a7-8901-23ab-cdef-4567890123de.

Use a conversão como objetivo da campanha

No Gerenciador de Anúncios, selecione essa conversão personalizada como evento de otimização da campanha do Loteamento Solar.

O property_id é um identificador exato, não o nome comercial do empreendimento. Na conversão personalizada, use a condição é igual a com o valor completo, sem espaços em volta.

Eventos enviados

Evento	Quando é gerado na conversa
`ConversationStarted`	A Mia inicia o atendimento a um novo lead
`MediaViewed`	O lead recebe foto, vídeo ou outro arquivo do empreendimento
`ViewContent`	A Mia apresenta um imóvel específico ao lead
`FinancingSimulation`	O lead faz uma simulação de financiamento com a Mia
`AppointmentScheduled`	Uma visita é agendada
`QualifiedLead`	O lead é qualificado e passa para o corretor
`DealStatus`	O deal muda de estágio no funil, fora da qualificação
`LeadEngajado`	O lead demonstra engajamento consistente na conversa

Parâmetros de cada evento

Os parâmetros seguem em custom_data e são o que você usa para filtrar e segmentar no Gerenciador de Eventos. Dois deles acompanham todos os eventos:

Parâmetro	Descrição
`campaign`	Campanha de origem do lead
`medium`	Mídia ou canal de origem do lead

Os demais variam por evento:

ConversationStarted

Parâmetro	Descrição
`content_name`	`Conversa iniciada`

MediaViewed

Parâmetro	Descrição
`content_name`	Nome do empreendimento cuja mídia foi enviada
`property_id`	Identificador do empreendimento
`content_category`	Tipo do arquivo enviado (imagem, vídeo, documento)

ViewContent

Parâmetro	Descrição
`content_name`	Nome do empreendimento apresentado
`property_id`	Identificador do empreendimento
`value`	Valor do imóvel
`currency`	Moeda do valor (`BRL`)
`quantity`	Quantidade de unidades apresentadas

FinancingSimulation

Parâmetro	Descrição
`content_name`	`Simulação de financiamento`
`value`	Valor do imóvel simulado
`currency`	Moeda do valor (`BRL`)
`down_payment`	Valor de entrada simulado
`financing_term`	Prazo do financiamento simulado

AppointmentScheduled

Parâmetro	Descrição
`content_name`	`Visita agendada`
`property_id`	Identificador do empreendimento da visita
`appointment_date`	Data e hora da visita

QualifiedLead e DealStatus

Parâmetro	Descrição
`status`	Status atual do deal
`stage`	Estágio atual do deal no funil
`stage_type`	Tipo do estágio, que identifica a etapa de qualificação
`external_status`	Status equivalente no seu CRM

LeadEngajado

Parâmetro	Descrição
`content_name`	`Lead engajado`

Segmentação por empreendimento

Um mesmo evento pode se referir a empreendimentos diferentes: o ViewContent de hoje pode ser de um lançamento e o de amanhã, de outro. Dois parâmetros resolvem isso:

property_id identifica o empreendimento de forma estável, mesmo que o nome comercial mude. É o que você usa como filtro.
content_name traz o nome do empreendimento, para leitura direta nos relatórios.

Hoje o property_id acompanha os seguintes eventos:

Evento	`property_id`
`AppointmentScheduled`	Disponível
`MediaViewed`	Em implementação
`ViewContent`	Em implementação

Enquanto MediaViewed e ViewContent não carregam o identificador, segmente esses dois eventos por campaign.

Como descobrir o identificador do empreendimento

Abra o empreendimento na plataforma

Vá em Empreendimentos e clique no empreendimento que você quer segmentar.

Copie o identificador da barra de endereço

O endereço fica no formato app.morada.ai/properties/d4e5f6a7-8901-23ab-cdef-4567890123de. O trecho depois de /properties/ é o property_id.

Se você prefere buscar pela API, o mesmo identificador vem em Listar Produtos, no campo productId:

curl -H "x-morada-api-key: SUA_CHAVE_API" \
  "https://mia-gateway.morada.ai/products?page=1&size=50"

{
  "products": [
    {
      "productId": "d4e5f6a7-8901-23ab-cdef-4567890123de",
      "productName": "Loteamento Solar",
      "status": "Lançamento"
    }
  ]
}

Para achar um empreendimento pelo nome, use Buscar Produto por Nome. A autenticação está em Introdução à API.

O identificador é o mesmo nos três lugares: property_id no evento da Meta, productId na API e o trecho final da URL do empreendimento na plataforma.

Nomes de evento em campanhas de Click to WhatsApp

Para tráfego vindo de anúncios de Click to WhatsApp, a Meta aceita apenas uma lista fechada de nomes de evento. Quando o lead chega por esse caminho, três eventos são enviados com o nome padronizado equivalente:

Evento gerado na conversa	Nome recebido pela Meta
`MediaViewed`	`ViewContent`
`AppointmentScheduled`	`InitiateCheckout`
`DealStatus`	`LeadSubmitted`

Nesses casos, custom_data.original_event_name preserva o nome original do evento, e os demais parâmetros continuam iguais. Leads que não vieram de anúncio de Click to WhatsApp mantêm o nome original do evento. É por isso que a mesma visita agendada pode aparecer como AppointmentScheduled em um relatório e como InitiateCheckout em outro: o que muda é a origem do lead.

Dados do lead

Cada evento também leva os identificadores que a Meta usa para casar a conversão com a pessoa que clicou no anúncio:

Campo	Descrição
`external_id`	Identificador do lead na Morada.ai
`em`	E-mail do lead, com hash
`ph`	Telefone do lead, com hash
`ctwa_clid`	Identificador do clique no anúncio de Click to WhatsApp
`lead_id`	Identificador do lead no formulário Meta Lead Ads, quando a origem for formulário

em e ph são dados pessoais do lead. Eles são enviados sempre com hash SHA-256, conforme exigido pela Meta, e nunca em texto puro.

Exemplo de evento

{
  "event_name": "ViewContent",
  "action_source": "business_messaging",
  "messaging_channel": "whatsapp",
  "user_data": {
    "external_id": "c3d4e5f6-7890-12ab-cdef-3456789012cd",
    "em": ["4b2c9f1e8a7d3c5b6e0f9a2d4c7b1e8f3a5d9c2b6e0f4a8d1c3b7e5f9a2d6c0b"],
    "ph": ["7e1f4a9c2d8b5e0f3a6c9d2b7e4f1a8c5d0b3e6f9a2c7d4b1e8f5a0c3d6b9e2f"],
    "ctwa_clid": "ARBxK9mQ2vLp7TnW4sZd"
  },
  "custom_data": {
    "content_name": "Loteamento Solar",
    "property_id": "d4e5f6a7-8901-23ab-cdef-4567890123de",
    "value": 320000,
    "currency": "BRL",
    "quantity": 1,
    "campaign": "Lançamento Zona Sul",
    "medium": "Click to WhatsApp"
  }
}

O campo action_source indica a origem do evento: business_messaging para leads vindos de anúncio de Click to WhatsApp e chat para as demais origens.

Perguntas frequentes

Preciso criar um Pixel ou conjunto de dados novo?

Não. Se a sua WABA já tem um conjunto de dados vinculado, a integração usa ele. Se não tiver, um conjunto é criado e vinculado no primeiro evento vindo de anúncio.

Já uso um Pixel nos meus relatórios. Perco o histórico dele?

Não. O Pixel mantém todo o histórico. O que muda é que os eventos novos passam a cair no conjunto vinculado à WABA. Para continuar usando o mesmo Pixel, vincule ele à sua WABA no Gerenciador de Eventos.

Por que não vejo nenhum evento no conjunto de dados?

Confirme se já houve conversa vinda de anúncio de Click to WhatsApp depois da ativação. Sem esse tráfego, o vínculo entre a WABA e o conjunto ainda não foi criado, e não há evento de anúncio para exibir.

Leads que não vieram de anúncio também geram eventos?

Sim. Eles são enviados com action_source igual a chat e servem para análise e criação de públicos. A otimização de campanha usa os eventos de Click to WhatsApp, que carregam o ctwa_clid.

Em quanto tempo o evento aparece no Gerenciador de Eventos?

O envio acontece assim que o marco ocorre na conversa. O Gerenciador de Eventos exibe o evento logo em seguida.

Posso escolher quais eventos são enviados?

O conjunto de eventos é padrão para todos os clientes. Se você precisa de um recorte específico, fale com o seu CSM.

Por que vejo ViewContent em vez de MediaViewed?

Em campanhas de Click to WhatsApp, a Meta aceita apenas nomes da lista dela. O nome original do evento fica preservado em custom_data.original_event_name.

Onde vejo o desempenho das campanhas com esses eventos?

No Gerenciador de Anúncios, pela conversão personalizada que você criou, e na Análise de Campanhas da plataforma, que cruza o investimento com o funil real dentro da Morada.

Começando

Aplicativo Mobile

Mia - Assistente IA

Talk - Atendimento Humano

Fila de Distribuição

WhatsApp

Outros Canais

Leads e Contatos

Empreendimentos

Dashboards

Administração

Integrações

Suporte

Conversion API (CAPI)

O que é?

Como funciona

Onde os eventos chegam

As três situações possíveis

Como saber qual conjunto está recebendo

Primeiros passos

Eventos enviados

Parâmetros de cada evento

Segmentação por empreendimento

Como descobrir o identificador do empreendimento

Nomes de evento em campanhas de Click to WhatsApp

Dados do lead

Exemplo de evento

Perguntas frequentes

​O que é?

​Como funciona

​Onde os eventos chegam

​As três situações possíveis

​Como saber qual conjunto está recebendo

​Primeiros passos

​Eventos enviados

​Parâmetros de cada evento

​Segmentação por empreendimento

​Como descobrir o identificador do empreendimento

​Nomes de evento em campanhas de Click to WhatsApp

​Dados do lead

​Exemplo de evento

​Perguntas frequentes

O que é?

Como funciona

Onde os eventos chegam

As três situações possíveis

Como saber qual conjunto está recebendo

Primeiros passos

Eventos enviados

Parâmetros de cada evento

Segmentação por empreendimento

Como descobrir o identificador do empreendimento

Nomes de evento em campanhas de Click to WhatsApp

Dados do lead

Exemplo de evento

Perguntas frequentes