How to send events to Pixel from the bot

To transfer events from the bot’s workflow, you need to have a business account. You can register here.

How to create a new pixel

Choose API Conversions.

Attention! If the following window opens up during the Conversion API configuration, it’s better to leave the settings and start again.

If the following window opens up during the Conversion API configuration, it’s better to leave the settings and start again.

Choose the Pixel you need.

Generate an access token and save it in a safe place.

How to transfer events to Facebook

To transfer events to Facebook, you have to have your own domain set up in the mini-landing. It has to be approved on Facebook, and Saving values from cookies to client variables has to be turned on for Facebook in the mini-landing’s settings:

Now, there will be an automatically filled-out variable _fbp in the card of the client that came from the mini-landing. This variable can be transferred to Pixel with the event.

You need to configure the following settings in the block through which you want to transfer the event:

URL of the function:

https://store.mavibot.ai/function/fb_pixel

Example parameters:

{
  "pixel_id": "#{pixel_id}",
  "access_token": "#{access_token}",
  "event_name": "Entered the bot",
  "event_source_url": "https://my_best_site.com",
  "action_source": "chat",
  "fbp": "#{_fbp}",
  "fbc": "#{_fbc}"
}

Mandatory parameters

pixel_id — ID of the pixel.

access_token — the token for accessing the API.

event_name — the name of the event. You can use standard names such as Lead, PageView, Purchase, and so on (see more here), as well as your own names, such as Entered the bot.

event_source_url — the domain approved on Facebook.

fbp — the client’s browser ID.

Optional parameters

action_source — (other by default) this field lets you specify where exactly the conversion happened. Information about where events happened helps make sure that your advertisements are shown to the right audience.

You can set the following values in the action_source field:

Value Description
email Conversion took place through email
website Conversion took place on a site
phone_call Conversion took place through the phone
chat Conversion took place through a messenger, SMS, or an online chat
physical_store Conversion took place in a physical store
system_generated Conversion happened automatically, i.e. as a result of a monthly subscription renewal
business_messaging Conversion occurred in a conversation after the customer clicked a Click-to-WhatsApp ad
other Conversion happened another way

How to test events

To test events, add the test_event_code parameter with the text stored in the Testing messages tab to the request body.

{
  "pixel_id": "#{pixel_id}",
  "access_token": "#{access_token}",
  "event_name": "Entered the bot",
  "event_source_url": "https://my_best_site.com",
  "fbp": "#{_fbp}",
  "fbc": "#{_fbc}",
  "test_event_code": "TEST11421"
}

Attention! Don’t forget to delete the test_event_code parameter from the request when launching the production version.

Additional optional parameters

fn — first name.

ln — last name.

email — the client’s email.

phone — the client’s phone number.

fbc — click ID.

gender — the client’s gender (f — female, m — male).

country — country.

state — state.

city — city.

index — the client’s postal index (ZIP code).

external_id — any unique client ID, e.g. user ID or ID of third-party cookie files.

client_ip_address — the client’s IP address.

client_user_agent — user agent of the client’s browser.

You can also transfer your own parameters into Pixel. To do this, add the optional my_params parameter and specify your own fields in it.

Example:

{
  "my_params": {
    "value1": "Hello",
    "val2": "Hi"
  }
}

Full example

{
  "pixel_id": "#{pixel_id}",
  "access_token": "#{access_token}",
  "event_name": "Entered the bot",
  "event_source_url": "https://my_best_site.com",
  "email": "[email protected]",
  "phone": "1234567890",
  "currency": "USD",
  "value": "142.52",
  "test_event_code": "TEST11421",
  "external_id": "#{client_id}",
  "fn": "#{name}",
  "gender": "m",
  "post_index": "12345",
  "my_params": {
    "value1": "Hello",
    "val2": "Hi"
  }
}

Attention! Don’t forget to delete the test_event_code parameter from the request when launching the production version.

How to add a promotional account

First, you need to open access to your account.

Save and move to the Related Objects → Add Objects tab.

Then add your promotional account.

Click-to-WhatsApp Ad Conversions

An addition to the documentation for the fb_pixel_event() function.

Meta* marks each click from a Click-to-WhatsApp ad with a ctwa_clid click identifier. It is received together with the customer's first WhatsApp message and is used to attribute a conversion from the conversation to a specific ad — similar to how pixel events are attributed to a website click.

Signature

fb_pixel_event(
    event_name,
    pixel_id,
    access_token,
    event_source_url,
    action_source,
    fbc,
    test_event_code,
    data,
    ctwa_clid,
    messaging_channel
)

New parameters

Parameter Description
ctwa_clid Click identifier for a Click-to-WhatsApp ad. If this parameter is not provided, the ctwa_clid client variable, which is saved automatically by the bot, is used. Optional.
messaging_channel The messaging channel where the conversion occurred. Defaults to whatsapp. Optional.

New action_source value

The following value is available for action_source:

Value Description
business_messaging The conversion occurred in a conversation after the customer clicked a Click-to-WhatsApp ad.

An event is sent as a messaging conversion if at least one of the following conditions is met:

  • action_source="business_messaging" is provided;
  • ctwa_clid is provided;
  • messaging_channel is provided.

In this case, Meta* receives the action_source + messaging_channel + ctwa_clid combination. Without this combination, the ad click will not be attributed to the conversion.

The website value must not be used for messaging conversions: the event will reach the pixel, but it will not be attributed to the ad.

Client variables

When a customer sends a WhatsApp message after clicking an ad, the bot saves the click data to the customer's client variables. You do not need to populate these variables manually.

Variable Description
ctwa_clid Click identifier. Automatically added to the event.
ctwa_clid_time Time when the identifier was received, in Unix time format. It can be used to determine how much time has passed since the click.
wa_ads_data Ad data in JSON format: ad URL, ad ID (source_id), title, description, creative type, and creative URL.

The click identifier is automatically taken from the client variable, so you do not need to pass it to the function explicitly.

The customer's phone number is automatically added to the event if it is not provided in data.

The event_source_url parameter is not used for messaging conversions.

Limitations

The click identifier is received only with the customer's first message after they click the button in the ad. It is not included in subsequent messages. Therefore, the event can be sent at any point during the conversation, but only if the first message originated from the ad.

Meta provides ctwa_clid for clicks from the Facebook and Instagram apps on Android and iOS.

The identifier is not provided when the customer clicks from a browser or clicks a regular post instead of the ad button. Conversions from such interactions cannot be attributed to the ad.

If the customer clicks another ad later, the variables are overwritten. The conversion is attributed to the most recent ad the customer came from.

If the click identifier is missing both from the function parameters and the client variables, the function returns the following error and the event is not sent:

No ctwa_clid variable in client variables