# Formulários de Leads do Facebook
Está a publicar anúncios no Facebook para captar leads? Esta integração envia automaticamente essas leads para o Your AI Connector, para que possa fazer o acompanhamento via WhatsApp, SMS ou qualquer outro canal ligado — sem ter de mover um dedo.
Funciona ao ligar os Facebook Lead Ads ao Your AI Connector através de uma plataforma de automatização (como o Pabbly, Zapier ou Make). Estas plataformas funcionam como uma ponte entre o Facebook e o Your AI Connector, transmitindo as informações das leads de um para o outro através da API (uma forma de diferentes softwares trocarem dados automaticamente).
---
## Pré-requisitos
Antes de começar, certifique-se de que tem:
- Acesso ao **Gestor de Anúncios do Facebook** com permissão para criar Lead Ads.
- **Uma conta** com uma chave API ativa (gere uma em **Definições → Integrações → Chave API** — consulte [Acesso à API](api-access.md) para ver os passos exatos).
- **Uma conta numa plataforma de automatização** — Pabbly Connect, Zapier ou Make (Integromat). Este guia utiliza o Pabbly como exemplo, mas os passos são semelhantes em qualquer plataforma.
- **Uma lista de contactos** no Your AI Connector onde as novas leads serão adicionadas — consulte [Organizar Listas e Contactos](../get-started/list-and-contact-management.md).
---
## Visão geral
A integração funciona em três fases:
1. Um potencial cliente preenche o seu Formulário de Leads do Facebook.
2. A sua plataforma de automatização deteta a nova lead e envia a informação para o Your AI Connector automaticamente (utilizando duas chamadas de API).
3. O Your AI Connector cria o contacto e adiciona-o à lista que especificou.
A partir daí, uma difusão, uma campanha ou um Agente de IA que tenha atribuído trata do resto — seja uma mensagem de boas-vindas com IA, uma sequência de e-mails ou um acompanhamento manual.
---
## Passo 1: Crie o seu Formulário de Lead do Facebook
1. Abra o **Facebook Ads Manager**.
2. Crie uma nova campanha com o objetivo **Leads**.
3. Ao nível do anúncio, escolha **Formulário Instantâneo** como método de lead.
4. Crie o seu formulário com os campos de que necessita. No mínimo, inclua:
- **Nome próprio**
- **Número de telefone** (com código de país)
- Opcional: Apelido, e-mail
5. Publique o anúncio ou guarde o formulário como rascunho para testes.
---
## Passo 2: Teste o Formulário de Lead
Antes de ligar a automatização, submeta um lead de teste:
1. No Ads Manager, vá ao seu Formulário de Lead.
2. Clique em **Pré-visualizar** e preencha o formulário com dados de teste.
3. Confirme que o lead de teste aparece no seu **Facebook Lead Center** (em Ferramentas de Publicação na sua Página de Facebook, ou no Ads Manager em "Leads").
Esta entrada de teste será utilizada para configurar o mapeamento de campos na sua plataforma de automatização.
---
## Passo 3: Configure a Automatização
### Ligue o Facebook Lead Ads como o Gatilho
1. Inicie sessão na sua plataforma de automatizaçã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. Ligue a sua conta do Facebook e selecione a Página e o Formulário de Leads.
5. Obtenha o lead de teste para confirmar que a ligação funciona e para mapear os campos.
### Configurar Chamada de API 1: Criar Contacto
Adicione um passo de ação com um Pedido 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 o `{{placeholders}}` pelos mapeamentos de campo reais do seu passo 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 leads recolher o número de telefone sem um código de país, adicione um passo de formatação na sua automatização para o prefixar.
:::
A resposta da API devolve o ID do novo contacto em `data.contactId`. Guarde esse valor — irá precisar dele para o passo seguinte.
> **Pode ignorar 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 contacto a essas listas no mesmo pedido. Utilize a versão de dois passos abaixo apenas se a sua plataforma de automatização precisar que o contacto exista antes de decidir qual a lista a utilizar.
### Configurar Chamada de API 2: Adicionar Contacto à Lista
Adicione um segundo passo 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 contactos (consulte [Encontrar o ID da sua lista](#finding-your-list-id) abaixo) e mapeie `contactId` para o `data.contactId` devolvido pela primeira chamada à API.
---
## Encontrar o seu ID de Lista
1. No Your AI Connector, clique em **Contactos** e, em seguida, no separador **Listas**.
2. Abra o menu da linha ("⋯") junto à lista pretendida e clique em **Copiar ID da lista**.
Consulte [Organizar Listas e Contactos](../get-started/list-and-contact-management.md) para ver o guia completo da página de Listas.
---
## Passo 4: Testar o Fluxo de Trabalho Completo
1. Submeta outra lead de teste através do seu formulário do Facebook (ou repita a lead de teste existente na sua plataforma de automatização).
2. Verifique o Your AI Connector para confirmar:
- O **contacto** foi criado com o nome, número de telefone e e-mail corretos.
- O contacto foi **adicionado à lista correta**.
3. Se tiver uma difusão, campanha ou Agente de IA configurado para enviar mensagens automaticamente para essa lista, confirme se é acionado conforme esperado.
---
## Referência de Dados
Abaixo estão exemplos dos dados enviados e recebidos durante a integração.
### Criar Contacto - Pedido
```json
POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
{
"firstName": "Jane",
"lastName": "Smith",
"phone": "+15551234567",
"email": "jane@example.com"
}
```
### Criar Contacto - Resposta
```json
{
"success": true,
"data": {
"message": "Successfully created new contact",
"contactId": "abc123xyz",
"listsAdded": []
}
}
```
### Adicionar Contacto à Lista - Pedido
```json
POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
{
"contactId": "abc123xyz",
"listId": "LIST_ID"
}
```
---
## Dicas
- **Tratamento de duplicados:** se um contacto com o mesmo número de telefone já existir, a chamada de criação devolve `{"success": false, "error_code": 409}` e não devolve o contacto existente. Crie uma ramificação em `error_code` (o estado HTTP é 200) e procure o contacto com `GET /v1/contacts?phoneNumber=...` antes da chamada para adicionar à lista.
- **Múltiplos formulários:** crie fluxos de trabalho de automatização separados para diferentes formulários de leads, cada um direcionado para uma lista diferente e para uma difusão, campanha ou Agente de IA diferente.
- **Notificações de erro:** configure a sua plataforma de automatização para o notificar caso uma chamada à API falhe, para que não perca leads.
---
## Próximos Passos
- [Transição de Campanhas para Transmissões e 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) — receba notificações quando contactos forem criados ou etiquetados.