Trillet AI logo

Configure Meta Lead Ads

Choose the Facebook pages and lead forms that trigger calls from a call flow, and register the Meta webhook.

POSThttps://api.trillet.ai/v1/api/meta-lead/configure/{flowId}

When a lead is submitted on one of the configured forms, Meta notifies Trillet and the call flow calls the lead (after callDelaySeconds).

Before configuring, connect Meta with Install Meta Lead Ads. The Facebook user token saved by that step is the one used here.

Each entry in forms must be an object with formId (and formName), not a plain form ID string. Leads are matched to a flow by formId. String IDs are saved without an error, but leads from those forms never trigger a call.

If the call flow has an unpublished draft open in the editor, the configuration is saved to the draft only. Leads won't trigger calls with the new settings until the draft is published.

Headers

x-workspace-idstringrequired

Workspace identifier for the API. The call flow must belong to this workspace (or one of its sub-workspaces).

Path Parameters

flowIdstringrequired

The _id of the call flow. The flow must be active.

Request Body

selectedPagesarrayrequired

The Facebook pages and lead forms to monitor. At least one page is required. This replaces any pages configured before.

callDelaySecondsnumberdefault: 0

Seconds to wait after a lead arrives before calling.

clientIdstring

Your own Meta app ID. Leave it out to use Trillet's Meta app (the normal case after Install).

clientSecretstring

Your own Meta app secret. Only needed with clientId.

smartCallbackConfigobject

Retry schedule for leads who don't answer: {"enabled": boolean, "maxAttempts": number, "gaps": [{"days": number, "hours": number}]}. If left out, the flow's existing setting is kept (default: disabled, 5 attempts, 1 day apart).

complianceAcceptedboolean

Records that you accepted the lead-calling compliance terms. If left out, the existing value is kept.

Response Fields

messagestring

A summary of the result.

webhookUrlstring

The Trillet webhook URL registered with Meta.

flowIdstring

The call flow ID.

appIdstring

The Meta app ID used.

connectedPagesarray

The selectedPages you sent, as saved.

webhookRegisteredboolean

Whether the webhook was registered with Meta. The settings are saved even when this is false.

webhookWarningstring

Why webhook registration failed, or null.

Errors

StatusBodyWhen
400{"error": "Please select at least one page/form to connect"}selectedPages missing or empty
400{"error": "Invalid pathwayId"}flowId isn't a valid ID
403{"error": "Pathway does not belong to this workspace."}The flow belongs to another workspace
404{"error": "Pathway not found"}No call flow with that ID
404{"error": "Flow not found or inactive"}The flow exists but isn't active
500{"error": "Failed to configure Meta integration", "details": "..."}Unexpected server error
  • After Install Meta Lead Ads completes, Get Call Flow returns settings.metaIntegration.availablePages: the pages and lead forms the Meta account can see, already in the {pageId, pageName, forms: [{formId, formName, ...}]} shape this endpoint expects.
  • POST /v1/api/meta-lead/disconnect/{flowId} unsubscribes the pages and clears the Meta Lead Ads settings on the flow.
{
  "callDelaySeconds": 30,
  "selectedPages": [
    {
      "pageId": "111111111111111",
      "pageName": "My Business Page",
      "forms": [
        { "formId": "2222222222222222", "formName": "Spring promo" }
      ]
    }
  ]
}
{
  "message": "Meta integration configured successfully. Webhook registered for 1 page(s), 1 form(s).",
  "webhookUrl": "https://app.trillet.ai/v1/api/meta-lead/webhook",
  "flowId": "b7b7b7b7b7b7b7b7b7b7b7b7",
  "appId": "1234567890123456",
  "connectedPages": [
    {
      "pageId": "111111111111111",
      "pageName": "My Business Page",
      "forms": [
        { "formId": "2222222222222222", "formName": "Spring promo" }
      ]
    }
  ],
  "webhookRegistered": true,
  "webhookWarning": null
}

Last updated on