# Formularios de Meta (Lead Ads)

Cuando alguien llena un formulario de clientes potenciales de una de tus Páginas, Meteor guarda el lead, crea o actualiza el contacto en el CRM y te avisa con el evento **`lead.received`**. No necesitas conectarte a Meta: el lead te llega ya normalizado.

> Scope `contacts:read`, para el evento y para leer los formularios. Conectar Páginas y crear o archivar formularios se hace desde Automatizaciones → Formularios en el panel.

## Recibir los leads

Suscribe tu endpoint de eventos salientes a `lead.received` (ver [Webhooks](webhooks.html)). Si ya tienes uno, súmale el evento:

```ts
import { Met } from '@meteor.ia/sdk';

const met = new Met(process.env.MET_KEY!, { workspaceId: 42 });
const [ep] = await met.webhooks.subscriptions.list();
await met.webhooks.subscriptions.update(ep.id, {
  enabled_events: [...ep.enabled_events, 'lead.received'],
});
```

Cada evento trae:

```jsonc
{
  "type": "lead.received",
  "data": {
    "lead": {
      "id": "8c1f…",                 // el lead en Meteor
      "leadgen_id": "1234567890",    // el id del lead en Meta
      "form_id": "998877",
      "form_name": "Cotiza tu plan",
      "page_id": "556677",
      "platform": "ig",              // fb o ig
      "is_organic": false,
      "ad_id": "…", "ad_name": "…",
      "campaign_id": "…", "campaign_name": "…",
      "created_at": "2026-10-20T15:04:05+0000"
    },
    "answers": [
      { "key": "full_name", "label": "Nombre completo", "value": "Ana Pérez" },
      { "key": "email", "label": "Correo", "value": "ana@correo.co" }
    ],
    "contact_data": { "name": "Ana Pérez", "email": "ana@correo.co", "phone": "+573001234567" },
    "contact": { "id": 4512, "action": "created" }
  }
}
```

- `answers` va en el orden de las preguntas del formulario, con la etiqueta de cada una. Una respuesta de varias opciones llega unida con comas.
- `contact_data` son los datos de contacto que se reconocieron en las respuestas; un campo que el formulario no pidió llega `null`.
- `contact.action` es `created` si el contacto es nuevo y `updated` si ya existía. Si el lead no trae ni teléfono ni correo, `contact` es `null`.

Sale **una vez por lead nuevo que llega en vivo**. Los leads que se traen al sincronizar un formulario (leads de días anteriores) no lo emiten.

## Consultar los formularios

```ts
for await (const form of met.leadAds.iterateForms()) {
  console.log(form.id, form.name, form.page.connected, form.questions.map((q) => q.key));
}

const detalle = await met.leadAds.retrieveForm('998877');
console.log(detalle.leads_in_met);
```

`page.connected: false` quiere decir que la Página se desconectó: sus leads nuevos ya no llegan, aunque los guardados se conservan.