> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversion API (CAPI)

> Como a Morada.ai envia os eventos de conversão da conversa para a Meta, em qual conjunto de dados eles caem e quais parâmetros usar para segmentar por empreendimento.

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.

<Info>
  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.
</Info>

<Tip>
  Primeira vez usando os eventos? Vá direto para [Primeiros passos](#primeiros-passos) e volte depois para a referência de parâmetros.
</Tip>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="O evento é enviado para a Meta">
    O evento chega no conjunto de dados da sua conta, junto com os parâmetros de segmentação.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

```mermaid theme={null}
flowchart TD
    A["Evento gerado na conversa"] --> B{"O lead veio de anúncio<br/>de Click to WhatsApp?"}
    B -->|"Não"| C["Conjunto de dados<br/>da integração"]
    B -->|"Sim"| D{"Sua WABA já tem<br/>conjunto vinculado?"}
    D -->|"Sim"| E["Conjunto vinculado à WABA"]
    D -->|"Não"| F["A Morada cria e vincula<br/>um conjunto à sua WABA"]
    F --> E
```

### 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              |

<Note>
  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.
</Note>

### 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**.

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Pegue o identificador do empreendimento">
    Você vai usar o `property_id` como filtro. Veja [como descobrir o identificador do empreendimento](#como-descobrir-o-identificador-do-empreendimento) logo abaixo. No exemplo, o Loteamento Solar é `d4e5f6a7-8901-23ab-cdef-4567890123de`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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:

<AccordionGroup>
  <Accordion title="ConversationStarted">
    | Parâmetro      | Descrição           |
    | -------------- | ------------------- |
    | `content_name` | `Conversa iniciada` |
  </Accordion>

  <Accordion title="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) |
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="AppointmentScheduled">
    | Parâmetro          | Descrição                                 |
    | ------------------ | ----------------------------------------- |
    | `content_name`     | `Visita agendada`                         |
    | `property_id`      | Identificador do empreendimento da visita |
    | `appointment_date` | Data e hora da visita                     |
  </Accordion>

  <Accordion title="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                           |
  </Accordion>

  <Accordion title="LeadEngajado">
    | Parâmetro      | Descrição       |
    | -------------- | --------------- |
    | `content_name` | `Lead engajado` |
  </Accordion>
</AccordionGroup>

## 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

<Steps>
  <Step title="Abra o empreendimento na plataforma">
    Vá em **Empreendimentos** e clique no empreendimento que você quer segmentar.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

Se você prefere buscar pela API, o mesmo identificador vem em [Listar Produtos](/api-reference/endpoint/listar-produtos), no campo `productId`:

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

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

Para achar um empreendimento pelo nome, use [Buscar Produto por Nome](/api-reference/endpoint/buscar-produto-nome). A autenticação está em [Introdução à API](/api-reference/introducao).

<Note>
  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.
</Note>

## 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 |

<Warning>
  `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.
</Warning>

## Exemplo de evento

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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](/guias/dashboards/analise-campanhas) da plataforma, que cruza o investimento com o funil real dentro da Morada.
  </Accordion>
</AccordionGroup>