Ad Events

Overview

Every offer served through the Advertising.chat fetch API generates a stream of ad events that powers reporting and optimization: the fetch itself, message lifecycle notifications, clicks on tracked action links, and conversions. Events are journaled and aggregated for the reports you see in the Advertising.chat Console.

Concepts

Every event belongs to the org (account) that owns the API key used for the original fetch request.

Events are linked back to the fetch that served the ad by the fetch id — the messageId property of the fetch response. You pass that value as fetchEventId when you report events; that is what ties message deliveries, clicks, and conversions to a specific creative, line item, and ad unit in reporting.

Events may also carry a subscriber — the opaque, application-assigned identifier for the end user that you pass in the fetch request. It is used for frequency capping and unique-reach reporting.

Event types

Event type	Description	How it is recorded
fetch	An offer was requested and served.	Recorded automatically by the fetch API.
send	The message containing the offer was sent to the subscriber.	Reported by your application.
deliver	The message was delivered to the subscriber's device.	Reported by your application.
read	The subscriber read the message.	Reported by your application.
click	The subscriber followed a tracked action link.	Recorded automatically by the click-tracking redirect, or reported by your application.
conversion	The subscriber completed a tracked activity (purchase, signup, ...).	Conversion pixel, offline conversion upload, or reported by your application.

Reporting events

Report lifecycle events by POSTing to the event API with your API key (query parameter key, or an Authorization: Bearer <key> header):

POST https://ads.advertising.chat/v1/event
Content-Type: application/json

{
  "version": 2,
  "eventType": "deliver",
  "fetchEventId": "<messageId from the fetch response>",
  "timestamp": 1720000000000,
  "subscriber": "<opaque subscriber id>",
  "eventData": { }
}

Field	Description
version	Must be 2.
eventType	One of send, deliver, read, click, conversion.
fetchEventId	The messageId returned by the fetch that served the ad. Required — events that cannot be associated with a fetch are rejected.
timestamp	Optional. Unix-epoch milliseconds at which the event occurred.
subscriber	Optional. Used only if no subscriber was present on the fetch request.
eventData	Optional. Arbitrary JSON to associate with the event, available in journal reports.

A successful request returns 201 Created. If the event cannot be recorded (for example, an invalid eventType or fetchEventId), the API returns 422 Unprocessable Entity.

Click tracking

Action links in rendered offers are automatically wrapped in tracking URLs (optionally shortened). When the subscriber follows the link, Advertising.chat records a click event and redirects the request to the original target URL, so no work is required in your application to track clicks.

Conversion tracking

Conversion pixel

Embed a tracking pixel on a post-click page (for example, an order confirmation page) to record conversions:

GET https://ads.advertising.chat/v1/event?key=<your API key>&name=<activity>&value=<value>&cur=<currency>

The request returns a 1×1 transparent GIF. name identifies the tracked activity; value and cur optionally record a monetary value and currency for the conversion.

Offline conversions

Conversions that happen outside the browser (for example, in a call center) can be uploaded directly:

POST https://ads.advertising.chat/v1/event/offlineConversion

{
  "messageId": "<messageId from the fetch response>",
  "eventData": { }
}

Custom events

Applications can also record custom named events against an offer using the legacy (version-less) event body:

POST https://ads.advertising.chat/v1/event

{
  "messageId": "<messageId from the fetch response>",
  "eventName": "<application-defined name>",
  "eventData": { }
}

The response contains the eventId assigned to the recorded event. Custom events are available in journal reports.