# Formulários de Leads do Facebook

Está veiculando anúncios no Facebook para capturar leads? Esta integração envia automaticamente esses leads para o <span data-t="appName">Your AI Connector</span>, para que você possa fazer o acompanhamento via WhatsApp, SMS ou qualquer outro canal conectado — sem mover um dedo.

Ela funciona conectando os Facebook Lead Ads ao <span data-t="appName">Your AI Connector</span> por meio de uma plataforma de automação (como Pabbly, Zapier ou Make). Essas plataformas atuam como uma ponte entre o Facebook e o <span data-t="appName">Your AI Connector</span>, transmitindo as informações do lead de um para o outro usando a API (uma forma de diferentes softwares trocarem dados automaticamente).

---

## Pré-requisitos

Antes de começar, certifique-se de ter:

- Acesso ao **Gerenciador de Anúncios do Facebook** com permissão para criar Lead Ads.
- **Uma conta** com uma chave de API ativa (gere uma em **Configurações → Integrações → Chave de API** — veja [Acesso à API](api-access.md) para os passos exatos).
- **Uma conta em uma plataforma de automação** — Pabbly Connect, Zapier ou Make (Integromat). Este guia usa o Pabbly como exemplo, mas os passos são semelhantes em qualquer plataforma.
- **Uma lista de contatos** no <span data-t="appName">Your AI Connector</span> onde os novos leads serão adicionados — veja [Organizando Listas e Contatos](../get-started/list-and-contact-management.md).

---

## Visão geral

A integração funciona em três etapas:

1. Um potencial cliente preenche seu Formulário de Lead do Facebook.
2. Sua plataforma de automação detecta o novo lead e envia as informações para o <span data-t="appName">Your AI Connector</span> automaticamente (usando duas chamadas de API).
3. O <span data-t="appName">Your AI Connector</span> cria o contato e o adiciona à lista que você especificar.

A partir daí, uma transmissão, uma campanha ou um Agente de IA que você designou cuida do resto — seja uma mensagem de boas-vindas com IA, uma sequência de gotejamento ou um acompanhamento manual.

---

## Passo 1: Crie seu Formulário de Lead do Facebook

1. Abra o **Gerenciador de Anúncios do Facebook**.
2. Crie uma nova campanha com o objetivo de **Cadastros**.
3. No nível do anúncio, escolha **Formulário instantâneo** como o método de cadastro.
4. Crie seu formulário com os campos de que você precisa. No mínimo, inclua:
   - **Nome**
   - **Número de telefone** (com código do país)
   - Opcional: Sobrenome, e-mail
5. Publique o anúncio ou salve o formulário como rascunho para teste.

---

## Passo 2: Teste o Formulário de Lead

Antes de conectar a automação, envie um lead de teste:

1. No Gerenciador de Anúncios, vá para o seu Formulário de Lead.
2. Clique em **Visualizar** e preencha o formulário com dados de teste.
3. Confirme se o lead de teste aparece na sua **Central de Cadastros do Facebook** (em Ferramentas de Publicação na sua Página do Facebook, ou no Gerenciador de Anúncios em "Cadastros").

Esta entrada de teste será usada para configurar o mapeamento de campos na sua plataforma de automação.

---

## Passo 3: Configure a Automação

### Conecte o Facebook Lead Ads como Gatilho

1. Faça login na sua plataforma de automação (Pabbly, Zapier ou Make).
2. Crie um novo fluxo de trabalho / cenário / zap.
3. Defina o **gatilho** como "Facebook Lead Ads - New Lead".
4. Conecte sua conta do Facebook e selecione a Página e o Formulário de Leads.
5. Busque o lead de teste para confirmar se a conexão funciona e para mapear os campos.

### Configure a Chamada de API 1: Criar Contato

Adicione uma etapa de ação com uma Requisição HTTP / Webhook / API:

- **Método:** `POST`
- **URL:** `https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY`
- **Cabeçalhos:**
  ```
  Content-Type: application/json
  ```
- **Corpo (JSON):**
  ```json
  {
    "firstName": "{{first_name}}",
    "lastName": "{{last_name}}",
    "phone": "{{phone_number}}",
    "email": "{{email}}"
  }
  ```

Substitua `{{placeholders}}` pelos mapeamentos de campo reais da sua etapa de gatilho.

::: warning
**Importante:** O número de telefone deve incluir o código do país (por exemplo, `+1` para os EUA ou `+31` para os Países Baixos). Se o seu formulário de lead coletar o número de telefone sem o código do país, adicione uma etapa de formatação em sua automação para prefixá-lo.
:::


A resposta da API retorna o ID do novo contato em `data.contactId`. Salve esse valor — você precisará dele para a próxima etapa.

> **Você pode pular a segunda chamada.** O `POST /v1/contacts` também aceita `listId` (uma lista) ou `listIds` (várias) no corpo da criação, o que adiciona o novo contato a essas listas na mesma requisição. Use a versão de duas etapas abaixo apenas se sua plataforma de automação precisar que o contato exista antes de decidir qual lista usar.

### Configure a Chamada de API 2: Adicionar Contato à Lista

Adicione uma segunda etapa de ação:

- **Método:** `POST`
- **URL:** `https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY`
- **Cabeçalhos:**
  ```
  Content-Type: application/json
  ```
- **Corpo (JSON):**
  ```json
  {
    "contactId": "{{contact_id_from_previous_step}}",
    "listId": "YOUR_LIST_ID"
  }
  ```

Substitua `YOUR_LIST_ID` pelo ID real da sua lista de contatos (veja [Como encontrar o ID da sua lista](#finding-your-list-id) abaixo) e mapeie `contactId` para o `data.contactId` retornado pela primeira chamada da API.

---

## Encontrando o ID da sua Lista

1. No Your AI Connector, clique em **Contatos** e, em seguida, na aba **Listas**.
2. Abra o menu da linha ("⋯") ao lado da lista desejada e clique em **Copiar ID da lista**.

Veja [Organizando Listas e Contatos](../get-started/list-and-contact-management.md) para o passo a passo completo da página de Listas.

---

## Passo 4: Teste o Fluxo de Trabalho Completo

1. Envie outro lead de teste através do seu formulário do Facebook (ou repita o lead de teste existente na sua plataforma de automação).
2. Verifique o Your AI Connector para confirmar:
   - O **contato** foi criado com o nome, número de telefone e e-mail corretos.
   - O contato foi **adicionado à lista correta**.
3. Se você tiver uma transmissão, campanha ou Agente de IA configurado para enviar mensagens a essa lista automaticamente, confirme se ele é acionado conforme o esperado.

---

## Referência de Dados

Abaixo estão exemplos dos dados enviados e recebidos durante a integração.

### Criar Contato - Solicitação

```json
POST <span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?apiKey=YOUR_API_KEY

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+15551234567",
  "email": "jane@example.com"
}
```

### Criar Contato - Resposta

```json
{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}
```

### Adicionar Contato à Lista - Solicitação

```json
POST <span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/lists?apiKey=YOUR_API_KEY

{
  "contactId": "abc123xyz",
  "listId": "LIST_ID"
}
```

---

## Dicas

- **Tratamento de duplicatas:** se um contato com o mesmo número de telefone já existir, a chamada de criação retorna `{"success": false, "error_code": 409}` e não retorna o contato existente. Crie uma ramificação em `error_code` (o status HTTP é 200) e procure o contato com `GET /v1/contacts?phoneNumber=...` antes da chamada de adição à lista.
- **Múltiplos formulários:** crie fluxos de trabalho de automação separados para diferentes formulários de leads, cada um direcionado a uma lista diferente e a uma transmissão, campanha ou Agente de IA diferente.
- **Notificações de erro:** configure sua plataforma de automação para notificá-lo se uma chamada de API falhar, para que você não perca leads.

---

## Próximos passos

- [Migrando de Campanhas para Transmissões & Agentes](../moving-from-campaigns.md) — configure algo para enviar mensagens automaticamente a novos leads.
- [Acesso à API](api-access.md) — documentação completa da API para integrações avançadas.
- [Webhooks](webhooks.md) — seja notificado quando contatos forem criados ou marcados.