Vixiees integrates with Meta Ads (Facebook/Instagram Lead Ads) to automatically capture leads from ad forms.
Connecting Meta Ads
Requirements
- Facebook Business account with access to the page
- Administrator permissions on the Facebook page
- Lead Ads forms already set up
Steps to Connect
- Go to Settings > Integrations > Meta Ads
- Click Connect with Facebook
- Log in to your Facebook account
- Select the pages you want to connect
- Authorize the requested permissions
Data Synchronized
When connecting, Vixiees retrieves:
- List of Facebook pages
- Lead Ads forms for each page
- Fields of each form
Reconnecting the integration
If Meta Ads is already connected, the button changes to Reconnect. Clicking it shows a confirmation warning: reconnecting re-links the forms and may result in data loss, so it should only be done after changing Facebook accounts or when permissions need to be refreshed.
Configuring Forms
Field Mapping
- Select the form from the list
- For each field, choose the corresponding contact attribute
- Make sure to map email or phone (required)
- Optionally, assign a playbook and initial stage
- Save the changes
Required Fields
Each form must have at least one of the following mapped:
- Email or
- Phone
Without these fields, leads will be ignored.
Lead Capture
Automatic Flow
When someone completes a Lead Ads form:
- Meta sends the data to Vixiees via webhook
- Vixiees looks up or creates the contact
- The configured field mapping is applied
- The contact is assigned to the indicated playbook and stage
- The contact becomes available for the sales team
Existing Contacts
If the contact already exists (same email or phone):
- Their data is updated with the new information
- The form submission is recorded in their history
- If they were in a closed stage, they can be reassigned to the form's playbook
Playbooks and Assignment
Per-form configuration
Each form can have:
| Field | Description |
|---|---|
| Playbook | Which playbook leads are assigned to |
| Initial stage | Which stage of the playbook they start in |
No configuration
If no playbook is configured, the account's default playbook is used.
Ad Information
With ad read permissions, Vixiees can capture:
| Field | Description |
|---|---|
| Ad name | The ad that generated the lead |
| Ad group | The ad set |
| Page | The Facebook page |
This information appears in the contact's history.
Required permissions
To retrieve ad data:
- ads_management
- ads_read
Custom Fields
Besides the standard fields, you can map:
- Custom form fields
- Vixiees custom attributes
Mapping is flexible and allows any combination.
Form History
Each form submission is recorded on the contact:
- Date and time of submission
- Form used
- Full responses
- Ad information (when available)
Webhook log
Every time Meta sends a lead to Vixiees, the event is recorded in the integration's Webhook log tab, along with the exact outcome of that submission.
What each entry shows
- The date of the event
- The form it came from
- The result: contact created, contact updated, error, or skipped
- If the event created or updated a contact, a direct link to that contact
- Technical identifiers (page, form, leadgen, ad, ad group) and the received payload
When a lead doesn't create a contact
If the event doesn't create or update a contact, the log explains the exact reason:
| Reason | What it means |
|---|---|
| The page in the webhook doesn't belong to any account with an active integration | The page was disconnected, or the webhook reached the wrong account |
| The page or form was not found in this account | Missing configuration |
| The form is not configured | No email or phone field mapped |
| The account is deactivated | The event was skipped; this is expected, not an error |
| The call to the Meta API failed | The token expired or the request timed out — may require reconnecting |
| Internal error while creating or updating the contact | Unexpected error; contact support if it keeps happening |
| The payload could not be read | Meta sent an event in an unrecognized format |
Each reason includes an on-screen hint about what to check or fix.
Fields with errors on a created contact
A contact can be created or updated successfully and still have one or more custom fields that couldn't be saved (for example, a value that doesn't match the configured options). In that case, the log entry shows how many fields failed right next to the result, with no need to check a separate list.
Conclusion
The Meta Ads integration allows you to:
- Automatically capture leads from Facebook and Instagram
- Map fields flexibly
- Assign leads to the correct playbook
- Keep a complete form history
- Diagnose exactly why a lead didn't create a contact, event by event
Relevant Scenarios
- Lead generation campaigns: Leads from ads arrive directly in Vixiees
- Multiple forms: Each form can go to a different playbook
- Campaign tracking: Identify which ad generated each lead
- Troubleshooting: Quickly find out why a specific lead didn't turn into a contact
Was this article helpful?