Conversion Reporting

POST

external

businesses

{business_id}

conversion_events

Conversion Reporting

curl --request POST \
  --url https://api.example.com/external/v1/businesses/{business_id}/conversion_events \
  --header 'Content-Type: application/json' \
  --data '
{
  "cnct_tracking_id": "<string>",
  "event_name": "<string>",
  "sendout_id": "<string>",
  "attribution": {
    "attribution.meta_ctwa.ctwa_clid": "<string>",
    "attribution.meta_ctwa.ad_id": "<string>"
  },
  "payload": {
    "payload.currency": "<string>",
    "payload.value": 123,
    "payload.order_id": "<string>",
    "payload.content_type": "<string>",
    "payload.content_ids": [
      "<string>"
    ],
    "payload.num_items": 123,
    "payload.contents": [
      {
        "id": "<string>",
        "quantity": 123,
        "item_price": 123
      }
    ],
    "payload.event_time": 123
  }
}
'

import requests

url = "https://api.example.com/external/v1/businesses/{business_id}/conversion_events"

payload = {
    "cnct_tracking_id": "<string>",
    "event_name": "<string>",
    "sendout_id": "<string>",
    "attribution": {
        "attribution.meta_ctwa.ctwa_clid": "<string>",
        "attribution.meta_ctwa.ad_id": "<string>"
    },
    "payload": {
        "payload.currency": "<string>",
        "payload.value": 123,
        "payload.order_id": "<string>",
        "payload.content_type": "<string>",
        "payload.content_ids": ["<string>"],
        "payload.num_items": 123,
        "payload.contents": [
            {
                "id": "<string>",
                "quantity": 123,
                "item_price": 123
            }
        ],
        "payload.event_time": 123
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    cnct_tracking_id: '<string>',
    event_name: '<string>',
    sendout_id: '<string>',
    attribution: {
      'attribution.meta_ctwa.ctwa_clid': '<string>',
      'attribution.meta_ctwa.ad_id': '<string>'
    },
    payload: {
      'payload.currency': '<string>',
      'payload.value': 123,
      'payload.order_id': '<string>',
      'payload.content_type': '<string>',
      'payload.content_ids': ['<string>'],
      'payload.num_items': 123,
      'payload.contents': [{id: '<string>', quantity: 123, item_price: 123}],
      'payload.event_time': 123
    }
  })
};

fetch('https://api.example.com/external/v1/businesses/{business_id}/conversion_events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/external/v1/businesses/{business_id}/conversion_events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'cnct_tracking_id' => '<string>',
    'event_name' => '<string>',
    'sendout_id' => '<string>',
    'attribution' => [
        'attribution.meta_ctwa.ctwa_clid' => '<string>',
        'attribution.meta_ctwa.ad_id' => '<string>'
    ],
    'payload' => [
        'payload.currency' => '<string>',
        'payload.value' => 123,
        'payload.order_id' => '<string>',
        'payload.content_type' => '<string>',
        'payload.content_ids' => [
                '<string>'
        ],
        'payload.num_items' => 123,
        'payload.contents' => [
                [
                                'id' => '<string>',
                                'quantity' => 123,
                                'item_price' => 123
                ]
        ],
        'payload.event_time' => 123
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/external/v1/businesses/{business_id}/conversion_events"

	payload := strings.NewReader("{\n  \"cnct_tracking_id\": \"<string>\",\n  \"event_name\": \"<string>\",\n  \"sendout_id\": \"<string>\",\n  \"attribution\": {\n    \"attribution.meta_ctwa.ctwa_clid\": \"<string>\",\n    \"attribution.meta_ctwa.ad_id\": \"<string>\"\n  },\n  \"payload\": {\n    \"payload.currency\": \"<string>\",\n    \"payload.value\": 123,\n    \"payload.order_id\": \"<string>\",\n    \"payload.content_type\": \"<string>\",\n    \"payload.content_ids\": [\n      \"<string>\"\n    ],\n    \"payload.num_items\": 123,\n    \"payload.contents\": [\n      {\n        \"id\": \"<string>\",\n        \"quantity\": 123,\n        \"item_price\": 123\n      }\n    ],\n    \"payload.event_time\": 123\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/external/v1/businesses/{business_id}/conversion_events")
  .header("Content-Type", "application/json")
  .body("{\n  \"cnct_tracking_id\": \"<string>\",\n  \"event_name\": \"<string>\",\n  \"sendout_id\": \"<string>\",\n  \"attribution\": {\n    \"attribution.meta_ctwa.ctwa_clid\": \"<string>\",\n    \"attribution.meta_ctwa.ad_id\": \"<string>\"\n  },\n  \"payload\": {\n    \"payload.currency\": \"<string>\",\n    \"payload.value\": 123,\n    \"payload.order_id\": \"<string>\",\n    \"payload.content_type\": \"<string>\",\n    \"payload.content_ids\": [\n      \"<string>\"\n    ],\n    \"payload.num_items\": 123,\n    \"payload.contents\": [\n      {\n        \"id\": \"<string>\",\n        \"quantity\": 123,\n        \"item_price\": 123\n      }\n    ],\n    \"payload.event_time\": 123\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/external/v1/businesses/{business_id}/conversion_events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cnct_tracking_id\": \"<string>\",\n  \"event_name\": \"<string>\",\n  \"sendout_id\": \"<string>\",\n  \"attribution\": {\n    \"attribution.meta_ctwa.ctwa_clid\": \"<string>\",\n    \"attribution.meta_ctwa.ad_id\": \"<string>\"\n  },\n  \"payload\": {\n    \"payload.currency\": \"<string>\",\n    \"payload.value\": 123,\n    \"payload.order_id\": \"<string>\",\n    \"payload.content_type\": \"<string>\",\n    \"payload.content_ids\": [\n      \"<string>\"\n    ],\n    \"payload.num_items\": 123,\n    \"payload.contents\": [\n      {\n        \"id\": \"<string>\",\n        \"quantity\": 123,\n        \"item_price\": 123\n      }\n    ],\n    \"payload.event_time\": 123\n  }\n}"

response = http.request(request)
puts response.read_body

When a customer clicks a Click-to-WhatsApp (CTWA) ad and later purchases on your site, Connectly can forward that conversion event to Meta’s Conversions API on your behalf — so the originating ad gets credit in Ads Manager. You send the event to Connectly; you never need to talk to Meta directly.

Endpoint

POST https://api.connectly.ai/external/v1/businesses/{business_id}/conversion_events

Integration journey

Get your API key

Open the Connectly inbox → Settings → General → API Key. Create a new key with all scopes unchecked (full access) or reuse an existing one if you still have the plaintext. The key is shown only once — copy and store it securely. Never expose it client-side or commit it to source control.

Enable purchase tracking in your campaign

In the Flow Builder, open the Audience step of your Click-to-WhatsApp card and tick “Track purchases completed on my own site and report them to the Ads Manager”. Without this, carousel CTA links will not carry the required tracking parameters.

Capture tracking parameters at landing

Once your campaign sends, Connectly auto-appends five query parameters to every CTA link:

?cnct_tracking_id=<value>&sendout_id=<value>&ctwa_clid=<value>&ad_id=<value>&attribution_source=meta_ctwa

Persist all five values when the customer lands on your site — store them in the session or against the customer record — so they’re available at checkout.

Call the conversion endpoint on purchase

When the customer completes a purchase, POST a single conversion event to Connectly with the tracking parameters captured at landing.

Verify in Ads Manager

Connectly forwards the event to Meta. Conversions typically appear in Meta Events Manager and roll up into Ads Manager attribution within a few hours.

Request body

Top-level fields

cnct_tracking_id

string

required

Verbatim copy of the cnct_tracking_id query parameter from the landing URL. Identifies the originating WhatsApp/CTWA session at the customer level.

event_name

string

required

Meta CAPI event name. Accepted values: "Purchase" or "ViewContent". Any other value returns 400 INVALID_ARGUMENT.

sendout_id

string

required

Verbatim copy of the sendout_id query parameter from the landing URL. Credits the conversion to the correct Connectly campaign.

attribution

object

required

CTWA attribution data.

Show attribution fields

attribution.meta_ctwa.ctwa_clid

string

required

Verbatim copy of the ctwa_clid query parameter from the landing URL. Forwarded to Meta CAPI as user_data.ctwa_clid to credit the originating ad.

attribution.meta_ctwa.ad_id

string

required

Verbatim copy of the ad_id query parameter from the landing URL. Used in Connectly’s per-ad conversion analytics — not forwarded to Meta CAPI directly.

payload

object

required

Per-event detail. For Purchase, currency and value are required.

Show payload fields

payload.currency

string

required

ISO 4217 currency code (e.g. "USD", "BRL", "MXN"). Required for Purchase.

payload.value

number

required

Total order value as a decimal (e.g. 99.97). Must be ≥ 0. Required for Purchase.

payload.order_id

string

Your internal order reference. Strongly recommended — Connectly passes this to Meta as the event_id deduplication key so the CAPI event and your browser pixel don’t double-count the same purchase. Keep it stable per order; the request is safe to retry.

payload.content_type

string

"product" for SKU-level catalog matching, or "product_group" for group-level.

payload.content_ids

string[]

Array of SKU or product IDs matching your Meta product catalog. Max 100 items.

payload.num_items

integer

Total cart size — sum of contents[].quantity.

payload.contents

object[]

Per-line-item detail. Preferred over content_ids alone when quantity matters. Max 100 items.

Show contents[] fields

string

required

SKU or product ID matching your Meta catalog. Items without an id are silently skipped.

quantity

integer

Units of this item. Without it, multi-item orders appear as single-item orders to Meta’s bid optimizer.

item_price

number

Per-unit price. Enables Meta to compute revenue per item for value-based bidding.

payload.event_time

integer

Unix epoch timestamp (seconds) of when the order occurred. Defaults to receive-time if omitted. Important for batched or backfilled events — Meta rejects events older than 7 days.

Example request

curl -i -X POST "https://api.connectly.ai/external/v1/businesses/<BUSINESS_ID>/conversion_events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
    "cnct_tracking_id": "<value from URL>",
    "event_name": "Purchase",
    "sendout_id": "<value from URL>",
    "attribution": {
      "meta_ctwa": {
        "ctwa_clid": "<value from URL>",
        "ad_id": "<value from URL>"
      }
    },
    "payload": {
      "currency": "USD",
      "value": 99.97,
      "order_id": "ORD-7821",
      "content_type": "product",
      "content_ids": ["sku-1", "sku-2"],
      "num_items": 2,
      "contents": [
        { "id": "sku-1", "quantity": 1, "item_price": 49.99 },
        { "id": "sku-2", "quantity": 1, "item_price": 49.98 }
      ],
      "event_time": 1746480000
    }
  }'

Response

{ "events_received": 1 }

events_received: 1 confirms Connectly received and recorded the event. Connectly logs the conversion to your campaign analytics regardless of whether the Meta CAPI forward succeeds. If Meta rejects the event, you receive a non-200 response with Meta’s verbatim error message.

Error responses

HTTP status	When
`400 INVALID_ARGUMENT`	Missing or invalid required fields; missing `currency`/`value` for a `Purchase` event; unsupported `event_name`; or Meta rejected the forwarded event.
`401 Unauthenticated`	Missing or invalid `X-API-KEY`.
`404 NOT_FOUND`	Business not found, or the business has no WhatsApp Cloud channel configured.

Notes

Send one event per API call. For multi-item orders, include all items in the contents[] array within a single Purchase event — do not send multiple POST requests for the same order.

cnct_tracking_id, sendout_id, ctwa_clid, and ad_id must be captured from the landing page URL at visit time and passed back when the customer converts — which may happen later in the same session.
Set event_time to the actual order timestamp, not the time you call the API. This matters if you flush events in batches or run backfills.
order_id doubles as Meta’s dedup key — keep it stable per order so retries are safe.

Get your API key

Enable purchase tracking in your campaign

Capture tracking parameters at landing

Once your campaign sends, Connectly auto-appends five query parameters to every CTA link:

?cnct_tracking_id=<value>&sendout_id=<value>&ctwa_clid=<value>&ad_id=<value>&attribution_source=meta_ctwa

Persist all five values when the customer lands on your site — store them in the session or against the customer record — so they’re available at checkout.

Call the conversion endpoint on purchase

When the customer completes a purchase, POST a single conversion event to Connectly with the tracking parameters captured at landing.

Verify in Ads Manager

Connectly forwards the event to Meta. Conversions typically appear in Meta Events Manager and roll up into Ads Manager attribution within a few hours.

Request body

cnct_tracking_id

string

required

Verbatim copy of the cnct_tracking_id query parameter from the landing URL. Identifies the originating WhatsApp/CTWA session at the customer level.

event_name

string

required

Meta CAPI event name. Accepted values: "Purchase" or "ViewContent". Any other value returns 400 INVALID_ARGUMENT.

sendout_id

string

required

Verbatim copy of the sendout_id query parameter from the landing URL. Credits the conversion to the correct Connectly campaign.

attribution

object

required

CTWA attribution data.

Show attribution fields

attribution.meta_ctwa.ctwa_clid

string

required

Verbatim copy of the ctwa_clid query parameter from the landing URL. Forwarded to Meta CAPI as user_data.ctwa_clid to credit the originating ad.

attribution.meta_ctwa.ad_id

string

required

Verbatim copy of the ad_id query parameter from the landing URL. Used in Connectly’s per-ad conversion analytics — not forwarded to Meta CAPI directly.

payload

object

required

Per-event detail. For Purchase, currency and value are required.

Show payload fields

payload.currency

string

required

ISO 4217 currency code (e.g. "USD", "BRL", "MXN"). Required for Purchase.

payload.value

number

required

Total order value as a decimal (e.g. 99.97). Must be ≥ 0. Required for Purchase.

payload.order_id

string

payload.content_type

string

"product" for SKU-level catalog matching, or "product_group" for group-level.

payload.content_ids

string[]

Array of SKU or product IDs matching your Meta product catalog. Max 100 items.

payload.num_items

integer

Total cart size — sum of contents[].quantity.

payload.contents

object[]

Per-line-item detail. Preferred over content_ids alone when quantity matters. Max 100 items.

Show contents[] fields

string

required

SKU or product ID matching your Meta catalog. Items without an id are silently skipped.

quantity

integer

Units of this item. Without it, multi-item orders appear as single-item orders to Meta’s bid optimizer.

item_price

number

Per-unit price. Enables Meta to compute revenue per item for value-based bidding.

payload.event_time

integer

Unix epoch timestamp (seconds) of when the order occurred. Defaults to receive-time if omitted. Important for batched or backfilled events — Meta rejects events older than 7 days.

curl -i -X POST "https://api.connectly.ai/external/v1/businesses/<BUSINESS_ID>/conversion_events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
    "cnct_tracking_id": "<value from URL>",
    "event_name": "Purchase",
    "sendout_id": "<value from URL>",
    "attribution": {
      "meta_ctwa": {
        "ctwa_clid": "<value from URL>",
        "ad_id": "<value from URL>"
      }
    },
    "payload": {
      "currency": "USD",
      "value": 99.97,
      "order_id": "ORD-7821",
      "content_type": "product",
      "content_ids": ["sku-1", "sku-2"],
      "num_items": 2,
      "contents": [
        { "id": "sku-1", "quantity": 1, "item_price": 49.99 },
        { "id": "sku-2", "quantity": 1, "item_price": 49.98 }
      ],
      "event_time": 1746480000
    }
  }'

Error responses

HTTP status	When
`400 INVALID_ARGUMENT`	Missing or invalid required fields; missing `currency`/`value` for a `Purchase` event; unsupported `event_name`; or Meta rejected the forwarded event.
`401 Unauthenticated`	Missing or invalid `X-API-KEY`.
`404 NOT_FOUND`	Business not found, or the business has no WhatsApp Cloud channel configured.

Send one event per API call. For multi-item orders, include all items in the contents[] array within a single Purchase event — do not send multiple POST requests for the same order.

cnct_tracking_id, sendout_id, ctwa_clid, and ad_id must be captured from the landing page URL at visit time and passed back when the customer converts — which may happen later in the same session.
Set event_time to the actual order timestamp, not the time you call the API. This matters if you flush events in batches or run backfills.
order_id doubles as Meta’s dedup key — keep it stable per order so retries are safe.

Get your API key

Enable purchase tracking in your campaign

Capture tracking parameters at landing

Once your campaign sends, Connectly auto-appends five query parameters to every CTA link:

?cnct_tracking_id=<value>&sendout_id=<value>&ctwa_clid=<value>&ad_id=<value>&attribution_source=meta_ctwa

Persist all five values when the customer lands on your site — store them in the session or against the customer record — so they’re available at checkout.

Call the conversion endpoint on purchase

When the customer completes a purchase, POST a single conversion event to Connectly with the tracking parameters captured at landing.

Verify in Ads Manager

Connectly forwards the event to Meta. Conversions typically appear in Meta Events Manager and roll up into Ads Manager attribution within a few hours.

Request body

cnct_tracking_id

string

required

Verbatim copy of the cnct_tracking_id query parameter from the landing URL. Identifies the originating WhatsApp/CTWA session at the customer level.

event_name

string

required

Meta CAPI event name. Accepted values: "Purchase" or "ViewContent". Any other value returns 400 INVALID_ARGUMENT.

sendout_id

string

required

Verbatim copy of the sendout_id query parameter from the landing URL. Credits the conversion to the correct Connectly campaign.

attribution

object

required

CTWA attribution data.

Show attribution fields

attribution.meta_ctwa.ctwa_clid

string

required

Verbatim copy of the ctwa_clid query parameter from the landing URL. Forwarded to Meta CAPI as user_data.ctwa_clid to credit the originating ad.

attribution.meta_ctwa.ad_id

string

required

Verbatim copy of the ad_id query parameter from the landing URL. Used in Connectly’s per-ad conversion analytics — not forwarded to Meta CAPI directly.

payload

object

required

Per-event detail. For Purchase, currency and value are required.

Show payload fields

payload.currency

string

required

ISO 4217 currency code (e.g. "USD", "BRL", "MXN"). Required for Purchase.

payload.value

number

required

Total order value as a decimal (e.g. 99.97). Must be ≥ 0. Required for Purchase.

payload.order_id

string

payload.content_type

string

"product" for SKU-level catalog matching, or "product_group" for group-level.

payload.content_ids

string[]

Array of SKU or product IDs matching your Meta product catalog. Max 100 items.

payload.num_items

integer

Total cart size — sum of contents[].quantity.

payload.contents

object[]

Per-line-item detail. Preferred over content_ids alone when quantity matters. Max 100 items.

Show contents[] fields

string

required

SKU or product ID matching your Meta catalog. Items without an id are silently skipped.

quantity

integer

Units of this item. Without it, multi-item orders appear as single-item orders to Meta’s bid optimizer.

item_price

number

Per-unit price. Enables Meta to compute revenue per item for value-based bidding.

payload.event_time

integer

Unix epoch timestamp (seconds) of when the order occurred. Defaults to receive-time if omitted. Important for batched or backfilled events — Meta rejects events older than 7 days.

curl -i -X POST "https://api.connectly.ai/external/v1/businesses/<BUSINESS_ID>/conversion_events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
    "cnct_tracking_id": "<value from URL>",
    "event_name": "Purchase",
    "sendout_id": "<value from URL>",
    "attribution": {
      "meta_ctwa": {
        "ctwa_clid": "<value from URL>",
        "ad_id": "<value from URL>"
      }
    },
    "payload": {
      "currency": "USD",
      "value": 99.97,
      "order_id": "ORD-7821",
      "content_type": "product",
      "content_ids": ["sku-1", "sku-2"],
      "num_items": 2,
      "contents": [
        { "id": "sku-1", "quantity": 1, "item_price": 49.99 },
        { "id": "sku-2", "quantity": 1, "item_price": 49.98 }
      ],
      "event_time": 1746480000
    }
  }'

Error responses

HTTP status	When
`400 INVALID_ARGUMENT`	Missing or invalid required fields; missing `currency`/`value` for a `Purchase` event; unsupported `event_name`; or Meta rejected the forwarded event.
`401 Unauthenticated`	Missing or invalid `X-API-KEY`.
`404 NOT_FOUND`	Business not found, or the business has no WhatsApp Cloud channel configured.

Send one event per API call. For multi-item orders, include all items in the contents[] array within a single Purchase event — do not send multiple POST requests for the same order.

cnct_tracking_id, sendout_id, ctwa_clid, and ad_id must be captured from the landing page URL at visit time and passed back when the customer converts — which may happen later in the same session.
Set event_time to the actual order timestamp, not the time you call the API. This matters if you flush events in batches or run backfills.
order_id doubles as Meta’s dedup key — keep it stable per order so retries are safe.

Reports API

Report Webhooks

​Endpoint

​Integration journey

​Request body

​Top-level fields

​Example request

​Response

​Error responses

​Notes

​Request body

​Error responses

​Request body

​Error responses

Endpoint

Integration journey

Request body

Top-level fields

Example request

Response

Error responses

Notes

Request body

Error responses

Request body

Error responses