@getlatedev/node 0.2.1285 → 0.2.1287

package/src/generated/types.gen.ts

@@ -4483,6 +4483,74 @@ export type ConnectWelcomeScreen = {
     } | null;
 };
 
+/**
+ * The ad that opened the conversation, enriched from the ads Zernio syncs for
+ * the account owner. null when the conversation did not start from a Meta
+ * referral (ad click or ig.me / m.me ref link).
+ *
+ * Meta's referral carries the ad ID but no campaign or ad set ID. When the ad
+ * is in your synced ads (`GET /v1/ads`), `synced` is true and the ad name,
+ * campaign, ad set and ad account come from there. Otherwise `synced` is false,
+ * `name` falls back to the ad title (Instagram, Facebook) or headline (WhatsApp)
+ * Meta sent with the click, and the other fields are null.
+ *
+ * A team member limited to some profiles, or an API key scoped to profiles, is
+ * enriched only from the ads it can list with `GET /v1/ads`; any other ad comes
+ * back `synced` false.
+ *
+ * A non-null object with `adId` null is a referral that is not an ad click:
+ * an ig.me / m.me ref link (`name` null) or a WhatsApp click on a post
+ * (`ctwa_source_type` post, `name` is Meta's headline). Nothing is looked up
+ * in your ads for it and `synced` is false.
+ *
+ */
+export type ConversationAdAttribution = {
+    /**
+     * Meta's ad ID: `meta_ad_id` on Instagram and Facebook, `ctwa_source_id` on WhatsApp when `ctwa_source_type` is `ad`. Accepted by `GET /v1/ads/{adId}`.
+     */
+    adId: (string) | null;
+    /**
+     * The synced ad's name, else the ad title or headline Meta sent.
+     */
+    name: (string) | null;
+    /**
+     * True when the ad was found in your synced ads.
+     */
+    synced: boolean;
+    /**
+     * Meta campaign ID. Synced ads only.
+     */
+    campaignId: (string) | null;
+    /**
+     * Campaign name. Synced ads only.
+     */
+    campaignName: (string) | null;
+    /**
+     * Meta ad set ID. Synced ads only.
+     */
+    adSetId: (string) | null;
+    /**
+     * Ad set name. Synced ads only.
+     */
+    adSetName: (string) | null;
+    /**
+     * Meta ad account ID (act_...). Synced ads only.
+     */
+    adAccountId: (string) | null;
+    /**
+     * Ad account name. Synced ads only.
+     */
+    adAccountName: (string) | null;
+    /**
+     * The post the ad promotes, from the synced ad or else Meta's `post_id` on the click.
+     */
+    platformPostId: (string) | null;
+    /**
+     * True when the ad was created outside Zernio (synced from Ads Manager), false when created through Zernio, null when not synced.
+     */
+    isExternal: (boolean) | null;
+} | null;
+
 /**
  * A Google Ads conversion action, e.g. a WEBPAGE conversion created via
  * `createConversionAction`. Returned by `listConversionActions` and
@@ -7912,6 +7980,137 @@ export type region = 'US' | 'GB';
  */
 export type status24 = 'ordering' | 'awaiting_payment' | 'activating' | 'active' | 'suspended' | 'canceled' | 'failed';
 
+/**
+ * Click attribution for a conversation that started from a Meta ad or
+ * a ref-tagged ig.me / m.me link, as Meta sent it. Absent when the
+ * conversation did not originate from an attributable click. For the ad
+ * name, campaign and ad set read `adAttribution` instead.
+ *
+ * Captured from the referral Meta delivers for the click. If the same
+ * person later arrives through a different ad or link, the original
+ * values are kept, so the first referral wins; read the fresh referral
+ * per click on the `message.received` / `referral.received` webhooks
+ * instead. On Instagram Click-to-Direct Meta usually delivers the ad post
+ * first as an attachment-only `share` / `ig_post` message with no
+ * referral, then attaches the referral to the next message. One exception
+ * on WhatsApp: when Meta omits `ctwa_clid` from that referral, a later
+ * Meta automatic event can supply it and refresh `ctwa_captured_at`, so
+ * treat `ctwa_captured_at` as the time Zernio stored the value, not the
+ * time of the click.
+ *
+ * Two families of keys, one per surface. They never appear together:
+ *
+ * - `ctwa_*` is WhatsApp Click-to-WhatsApp. The ad ID is
+ * `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp.
+ * - `meta_ad_*` is Instagram Click-to-Direct, Facebook Messenger
+ * Click-to-Message, and ig.me / m.me ref links. The ad ID is
+ * `meta_ad_id` (ad clicks only; a link capture carries
+ * `meta_ad_ref` without it). `ctwa_clid` never appears on these
+ * platforms.
+ *
+ * Every key is optional and only the keys Meta supplied are returned, so
+ * read defensively. Meta does not send a campaign or ad set ID; they are
+ * resolved from your synced ads in `adAttribution`. More keys may be added
+ * over time. Treat any key you do not recognise as an opaque string.
+ *
+ * Key names differ from the `message.received` webhook on purpose. The
+ * webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`)
+ * while the stored conversation record uses the prefixed names below.
+ * Renaming either side would break existing integrations, so both
+ * spellings are kept.
+ *
+ */
+export type InboxConversationAdMetadata = {
+    /**
+     * WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it.
+     */
+    ctwa_clid?: string;
+    /**
+     * WhatsApp only. The Meta ad ID the user clicked (or the post ID when `ctwa_source_type` is post). This is the WhatsApp equivalent of meta_ad_id.
+     */
+    ctwa_source_id?: string;
+    /**
+     * WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).
+     */
+    ctwa_source_type?: string;
+    /**
+     * WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.
+     */
+    ctwa_source_url?: string;
+    /**
+     * WhatsApp only. Headline of the ad creative at click time.
+     */
+    ctwa_headline?: string;
+    /**
+     * WhatsApp only. Body text of the ad creative at click time.
+     */
+    ctwa_body?: string;
+    /**
+     * WhatsApp only. Media type of the ad creative, image or video.
+     */
+    ctwa_media_type?: string;
+    /**
+     * WhatsApp only. Image of the ad creative at click time (image ads).
+     */
+    ctwa_image_url?: string;
+    /**
+     * WhatsApp only. Video of the ad creative at click time (video ads).
+     */
+    ctwa_video_url?: string;
+    /**
+     * WhatsApp only. Thumbnail of the ad video at click time (video ads).
+     */
+    ctwa_thumbnail_url?: string;
+    /**
+     * WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured.
+     */
+    ctwa_captured_at?: string;
+    /**
+     * Instagram and Facebook only. The Meta ad ID the user clicked. Present for ad clicks; absent when the capture came from an ig.me / m.me ref link.
+     */
+    meta_ad_id?: string;
+    /**
+     * Instagram and Facebook only. Meta-supplied source identifier: ADS for ad clicks; SHORTLINK, SHORTLINKS or IGME-SOURCE-LINK for ref links (treat as opaque).
+     */
+    meta_ad_source?: string;
+    /**
+     * Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.
+     */
+    meta_ad_type?: string;
+    /**
+     * Instagram and Facebook only. The ref parameter passed through from the ad creative or the ig.me / m.me link.
+     */
+    meta_ad_ref?: string;
+    /**
+     * Instagram and Facebook only. Title of the ad creative at click time.
+     */
+    meta_ad_title?: string;
+    /**
+     * Instagram and Facebook only. Image of the ad creative at click time.
+     */
+    meta_ad_photo_url?: string;
+    /**
+     * Instagram and Facebook only. Video of the ad creative at click time.
+     */
+    meta_ad_video_url?: string;
+    /**
+     * Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.
+     */
+    meta_ad_post_id?: string;
+    /**
+     * Instagram and Facebook only. The catalogue product the user clicked, for product ads.
+     */
+    meta_ad_product_id?: string;
+    /**
+     * Instagram and Facebook only. The Meta flow the ad launched, for flow ads.
+     */
+    meta_ad_flow_id?: string;
+    /**
+     * Instagram and Facebook only. When Zernio stored this referral. Always present when an Instagram or Facebook referral was captured.
+     */
+    meta_ad_captured_at?: string;
+} | null;
+
 /**
  * Attachment snapshot inside an edit-history entry.
  */
@@ -13273,7 +13472,7 @@ export type Webhook = {
     /**
      * Events subscribed to
      */
-    events?: Array<('post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved' | 'post.external.created' | 'post.external.updated' | 'post.external.deleted' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'account.ads.sync_failed' | 'account.ads.sync_recovered' | 'analytics.synced' | 'message.received' | 'conversation.started' | 'conversation.control_changed' | 'call.received' | 'call.ended' | 'call.failed' | 'call.permission_request' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.played' | 'message.failed' | 'reaction.received' | 'referral.received' | 'comment.received' | 'review.new' | 'review.updated' | 'lead.received' | 'ad.status_changed' | 'ad.review.approved' | 'ad.review.rejected' | 'ad.video.processed' | 'whatsapp.template.status_updated' | 'whatsapp.template.category_updated' | 'whatsapp.account.name_status_updated' | 'whatsapp.account.quality_updated' | 'whatsapp.account.status_updated' | 'whatsapp.account.alert_received' | 'whatsapp.contact.identity_changed' | 'whatsapp.automatic_event' | 'whatsapp.number.activated' | 'whatsapp.number.declined' | 'whatsapp.number.action_required' | 'whatsapp.number.verification_required' | 'whatsapp.number.suspended' | 'whatsapp.number.reactivated' | 'whatsapp.number.released' | 'whatsapp.number.kyc_submitted' | 'phone_number.stock_available' | 'verification.approved' | 'verification.failed' | 'api.changelog.published' | 'sms.registration.action_required' | 'sms.registration.status_updated' | 'branded_calling.identity.status_updated' | 'branded_calling.identity.action_required' | 'branded_calling.number.status_updated' | 'rcs.agent.status_updated' | 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted' | 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded' | 'contact.tag_added' | 'contact.tag_removed' | 'contact.field_changed' | 'sequence.enrolled' | 'sequence.exited' | 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed' | 'support.run.completed' | 'support.run.failed')>;
+    events?: Array<('post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved' | 'post.external.created' | 'post.external.updated' | 'post.external.deleted' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'account.ads.sync_failed' | 'account.ads.sync_recovered' | 'analytics.synced' | 'message.received' | 'conversation.started' | 'conversation.control_changed' | 'call.received' | 'call.ended' | 'call.failed' | 'call.permission_request' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.played' | 'message.failed' | 'reaction.received' | 'referral.received' | 'comment.received' | 'review.new' | 'review.updated' | 'lead.received' | 'ad.status_changed' | 'ad.review.approved' | 'ad.review.rejected' | 'ad.delivery_issue' | 'campaign.budget.depleted' | 'ad_account.status_changed' | 'ad.video.processed' | 'whatsapp.template.status_updated' | 'whatsapp.template.category_updated' | 'whatsapp.account.name_status_updated' | 'whatsapp.account.quality_updated' | 'whatsapp.account.status_updated' | 'whatsapp.account.alert_received' | 'whatsapp.contact.identity_changed' | 'whatsapp.automatic_event' | 'whatsapp.number.activated' | 'whatsapp.number.declined' | 'whatsapp.number.action_required' | 'whatsapp.number.verification_required' | 'whatsapp.number.suspended' | 'whatsapp.number.reactivated' | 'whatsapp.number.released' | 'whatsapp.number.kyc_submitted' | 'phone_number.stock_available' | 'verification.approved' | 'verification.failed' | 'api.changelog.published' | 'sms.registration.action_required' | 'sms.registration.status_updated' | 'branded_calling.identity.status_updated' | 'branded_calling.identity.action_required' | 'branded_calling.number.status_updated' | 'rcs.agent.status_updated' | 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted' | 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded' | 'contact.tag_added' | 'contact.tag_removed' | 'contact.field_changed' | 'sequence.enrolled' | 'sequence.exited' | 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed' | 'support.run.completed' | 'support.run.failed')>;
     /**
      * Whether webhook delivery is enabled
      */
@@ -13306,6 +13505,26 @@ export type Webhook = {
     accountIds?: Array<(string)>;
 };
 
+/**
+ * The connected ads account the event belongs to.
+ */
+export type WebhookAdsAccount = {
+    /**
+     * Internal Zernio account ID (same as used in /v1/accounts/{accountId}).
+     */
+    accountId: string;
+    /**
+     * Internal Zernio profile ID this account belongs to.
+     */
+    profileId: string;
+    /**
+     * Ads connection platform (`metaads`, `googleads`, `tiktokads`, `linkedinads`, `pinterestads`, `xads`, ...).
+     */
+    platform: string;
+    username: string;
+    displayName?: (string) | null;
+};
+
 export type WebhookAdsSyncAccount = {
     /**
      * The ads connection's account ID (same as used in /v1/accounts/{accountId})
@@ -13706,6 +13925,126 @@ export type event5 = 'account.disconnected';
  */
 export type disconnectionType = 'intentional' | 'unintentional';
 
+/**
+ * Webhook payload for the `ad_account.status_changed` event. Fires when an ad
+ * account Zernio already tracked moves between `active`, `restricted`, `disabled`
+ * and `closed`, as read by Zernio's ad account discovery (Meta, Google, TikTok, X).
+ * An account seen for the first time, an account not seen in the last 48 hours,
+ * or a platform status Zernio does not recognize, never fires it.
+ *
+ * `restricted` means the account exists but cannot run ads normally until
+ * something is settled (Meta unpaid balance or risk review, TikTok limits or
+ * pending verification, X review). Each new status fires at most once per
+ * account per 24 hours.
+ *
+ */
+export type WebhookPayloadAdAccountStatusChanged = {
+    /**
+     * Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery.
+     */
+    id: string;
+    profiles?: WebhookProfiles;
+    /**
+     * Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do.
+     */
+    test?: boolean;
+    event: 'ad_account.status_changed';
+    account: WebhookAdsAccount;
+    adAccount: {
+        /**
+         * Platform-native ad account ID.
+         */
+        platformAdAccountId: string;
+        name: (string) | null;
+    };
+    status: {
+        previous: 'active' | 'restricted' | 'disabled' | 'closed';
+        current: 'active' | 'restricted' | 'disabled' | 'closed';
+        /**
+         * Platform-native status, forwarded verbatim (Meta `account_status` code such as `2`, Google `SUSPENDED`, TikTok `STATUS_LIMIT`, X `REJECTED`).
+         */
+        raw: string;
+    };
+    /**
+     * UTC time at which Zernio generated this event.
+     */
+    timestamp: string;
+};
+
+export type event6 = 'ad_account.status_changed';
+
+export type previous = 'active' | 'restricted' | 'disabled' | 'closed';
+
+export type current = 'active' | 'restricted' | 'disabled' | 'closed';
+
+/**
+ * Webhook payload for the `ad.delivery_issue` event. Fires when an ad Zernio
+ * already tracked moves into the platform's error state: Meta `WITH_ISSUES`
+ * (payment, policy and account problems), TikTok account punishment or missing
+ * balance, LinkedIn removals, and any platform status Zernio does not recognize
+ * yet (check `issue.raw`). Ads seen for the first time by a sync never fire it.
+ *
+ * Detected by Zernio's own ad sync, so it arrives within one sync cycle. Each
+ * ad fires at most once per 24 hours. On Meta, `ad.status_changed` with
+ * `WITH_ISSUES` can also fire for the same problem, straight from Meta's webhook.
+ *
+ */
+export type WebhookPayloadAdDeliveryIssue = {
+    /**
+     * Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery.
+     */
+    id: string;
+    profiles?: WebhookProfiles;
+    /**
+     * Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do.
+     */
+    test?: boolean;
+    event: 'ad.delivery_issue';
+    account: WebhookAdsAccount;
+    adObject: {
+        /**
+         * Always `AD`.
+         */
+        level: 'AD';
+        /**
+         * Platform-native ad ID.
+         */
+        platformId: string;
+        /**
+         * Platform-native ad account ID.
+         */
+        platformAdAccountId: string;
+        /**
+         * Zernio ad ID, usable with GET /v1/ads/{adId}.
+         */
+        adId: string;
+        name: string;
+    };
+    issue: {
+        /**
+         * Platform-native status string, forwarded verbatim (Meta `WITH_ISSUES`, TikTok `ADVERTISER_ACCOUNT_PUNISH`, LinkedIn `REMOVED`, ...).
+         */
+        raw: string;
+        /**
+         * What the platform says is wrong. Meta reports it per campaign; other networks send no message today, so it is empty there.
+         */
+        reasons: Array<{
+            message: string;
+        }>;
+    };
+    /**
+     * UTC time at which Zernio generated this event.
+     */
+    timestamp: string;
+};
+
+export type event7 = 'ad.delivery_issue';
+
+/**
+ * Always `AD`.
+ */
+export type level2 = 'AD';
+
 /**
  * Webhook payload for the `ad.review.approved` and `ad.review.rejected` events.
  * Emitted for every ad network Zernio syncs (Meta, Google, TikTok, LinkedIn,
@@ -13734,25 +14073,7 @@ export type WebhookPayloadAdReview = {
      */
     test?: boolean;
     event: 'ad.review.approved' | 'ad.review.rejected';
-    /**
-     * The connected ads account that owns the ad.
-     */
-    account: {
-        /**
-         * Internal Zernio account ID (same as used in /v1/accounts/{accountId}).
-         */
-        accountId: string;
-        /**
-         * Internal Zernio profile ID this account belongs to.
-         */
-        profileId: string;
-        /**
-         * Ads connection platform (`metaads`, `googleads`, `tiktokads`, `linkedinads`, `pinterestads`, `xads`, ...).
-         */
-        platform: string;
-        username: string;
-        displayName?: (string) | null;
-    };
+    account: WebhookAdsAccount;
     adObject: {
         /**
          * Always `AD`.
@@ -13791,12 +14112,7 @@ export type WebhookPayloadAdReview = {
     timestamp: string;
 };
 
-export type event6 = 'ad.review.approved' | 'ad.review.rejected';
-
-/**
- * Always `AD`.
- */
-export type level2 = 'AD';
+export type event8 = 'ad.review.approved' | 'ad.review.rejected';
 
 export type status38 = 'approved' | 'rejected';
 
@@ -13925,7 +14241,7 @@ export type WebhookPayloadAdStatusChanged = {
     timestamp: string;
 };
 
-export type event7 = 'ad.status_changed';
+export type event9 = 'ad.status_changed';
 
 /**
  * Hierarchy level the status applies to. Mirrors Meta's `level`. Creative-level events are not forwarded.
@@ -13996,7 +14312,7 @@ export type WebhookPayloadAdVideoProcessed = {
     timestamp: string;
 };
 
-export type event8 = 'ad.video.processed';
+export type event10 = 'ad.video.processed';
 
 /**
  * `ready`: usable as `video.id` on the create endpoints. `error`: Meta could not process it; upload again.
@@ -14079,7 +14395,7 @@ export type WebhookPayloadAnalyticsSynced = {
     timestamp: string;
 };
 
-export type event9 = 'analytics.synced';
+export type event11 = 'analytics.synced';
 
 export type WebhookPayloadApiChangelogPublished = {
     /**
@@ -14098,7 +14414,7 @@ export type WebhookPayloadApiChangelogPublished = {
     timestamp: string;
 };
 
-export type event10 = 'api.changelog.published';
+export type event12 = 'api.changelog.published';
 
 /**
  * Webhook payload for the `call.ended` event. Fires on call hangup
@@ -14173,7 +14489,7 @@ export type WebhookPayloadCallEnded = {
     timestamp: string;
 };
 
-export type event11 = 'call.ended';
+export type event13 = 'call.ended';
 
 /**
  * Webhook payload for the `call.failed` event. Fired when a call
@@ -14212,7 +14528,7 @@ export type WebhookPayloadCallFailed = {
     timestamp: string;
 };
 
-export type event12 = 'call.failed';
+export type event14 = 'call.failed';
 
 /**
  * Webhook payload for the `call.permission_request` event. Fires
@@ -14254,7 +14570,7 @@ export type WebhookPayloadCallPermissionRequest = {
     timestamp: string;
 };
 
-export type event13 = 'call.permission_request';
+export type event15 = 'call.permission_request';
 
 export type response = 'accept' | 'reject';
 
@@ -14313,7 +14629,63 @@ export type WebhookPayloadCallReceived = {
     timestamp: string;
 };
 
-export type event14 = 'call.received';
+export type event16 = 'call.received';
+
+/**
+ * Webhook payload for the `campaign.budget.depleted` event. Fires when a campaign
+ * Zernio already tracked stops delivering because its budget ran out. TikTok only:
+ * it is the one network that reports an exhausted budget on the ad. Meta and Google
+ * keep such ads `ACTIVE`, so they never fire it.
+ *
+ * Detected by Zernio's own ad sync. Each campaign fires at most once per 6 hours, so a
+ * daily budget that runs out again the next day is announced again.
+ *
+ */
+export type WebhookPayloadCampaignBudgetDepleted = {
+    /**
+     * Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery.
+     */
+    id: string;
+    profiles?: WebhookProfiles;
+    /**
+     * Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do.
+     */
+    test?: boolean;
+    event: 'campaign.budget.depleted';
+    account: WebhookAdsAccount;
+    adObject: {
+        /**
+         * Always `CAMPAIGN`.
+         */
+        level: 'CAMPAIGN';
+        /**
+         * Platform-native campaign ID.
+         */
+        platformId: string;
+        /**
+         * Platform-native ad account ID.
+         */
+        platformAdAccountId: string;
+        name: (string) | null;
+    };
+    budget: {
+        /**
+         * Platform-native status string, forwarded verbatim (TikTok `AD_STATUS_CAMPAIGN_EXCEED`).
+         */
+        raw: string;
+    };
+    /**
+     * UTC time at which Zernio generated this event.
+     */
+    timestamp: string;
+};
+
+export type event17 = 'campaign.budget.depleted';
+
+/**
+ * Always `CAMPAIGN`.
+ */
+export type level4 = 'CAMPAIGN';
 
 /**
  * Webhook payload for comment received events (Instagram, Facebook, Threads, YouTube, LinkedIn, Bluesky, Reddit, TikTok). X/Twitter does NOT fire this event. TikTok events carry only the author id: the comment.update webhook has no username, picture or owner flag.
@@ -14490,7 +14862,7 @@ export type WebhookPayloadComment = {
     timestamp: string;
 };
 
-export type event15 = 'comment.received';
+export type event18 = 'comment.received';
 
 export type platform15 = 'instagram' | 'facebook' | 'threads' | 'youtube' | 'linkedin' | 'bluesky' | 'reddit' | 'tiktok';
 
@@ -14536,7 +14908,7 @@ export type WebhookPayloadCommerceOrder = {
     };
 };
 
-export type event16 = 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded';
+export type event19 = 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded';
 
 export type type17 = 'order';
 
@@ -14579,7 +14951,7 @@ export type WebhookPayloadCommerceProduct = {
     };
 };
 
-export type event17 = 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted';
+export type event20 = 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted';
 
 export type type18 = 'product';
 
@@ -14619,7 +14991,7 @@ export type WebhookPayloadContactFieldChanged = {
     source: 'api' | 'workflow' | 'automation';
 };
 
-export type event18 = 'contact.field_changed';
+export type event21 = 'contact.field_changed';
 
 /**
  * Who wrote the field: the API or dashboard, a workflow set_field node, or an automation.
@@ -14651,7 +15023,7 @@ export type WebhookPayloadContactTag = {
     source: 'api' | 'workflow' | 'automation';
 };
 
-export type event19 = 'contact.tag_added' | 'contact.tag_removed';
+export type event22 = 'contact.tag_added' | 'contact.tag_removed';
 
 /**
  * Who answers a conversation changed under Meta's handover protocol. WhatsApp: Meta
@@ -14697,7 +15069,7 @@ export type WebhookPayloadConversationControlChanged = {
     timestamp: string;
 };
 
-export type event20 = 'conversation.control_changed';
+export type event23 = 'conversation.control_changed';
 
 /**
  * Who answers now. ai_agent: Meta Business Agent (WhatsApp); app: you; other: another app (a WhatsApp partner, or a Messenger / Instagram receiver such as Page Inbox).
@@ -14715,6 +15087,20 @@ export type previousOwner = 'app' | 'ai_agent' | 'other';
  * platform (Instagram, Messenger/Facebook, Telegram, WhatsApp, X, Reddit,
  * Bluesky, SMS, TikTok). Platform-agnostic: one subscription covers every DM platform.
  *
+ * `conversation.metadata` (the referral as Meta sent it) and
+ * `conversation.adAttribution` (the ad, campaign and ad set from your synced
+ * ads) are filled only when the message that created the conversation carried
+ * Meta's referral. That holds for WhatsApp Click-to-WhatsApp and Facebook
+ * Messenger Click-to-Message, and for ig.me / m.me ref links. On Instagram
+ * Click-to-Direct it usually does NOT: Meta creates the thread with the ad post
+ * itself, an attachment-only `share` / `ig_post` message with no referral, and
+ * attaches the referral to the next message. That conversation.started then
+ * has `adAttribution` null and no `metadata`. Read the click from `metadata.ad`
+ * and `metadata.referral` on the `message.received` that follows, or from
+ * `adAttribution` on `GET /v1/inbox/conversations` and
+ * `GET /v1/inbox/conversations/{conversationId}`, which carry it once the
+ * referral is stored.
+ *
  */
 export type WebhookPayloadConversationStarted = {
     /**
@@ -14727,7 +15113,10 @@ export type WebhookPayloadConversationStarted = {
     id: string;
     profiles?: WebhookProfiles;
     event: 'conversation.started';
-    conversation: InboxWebhookConversationDetail;
+    conversation: (InboxWebhookConversationDetail & {
+    metadata?: InboxConversationAdMetadata;
+    adAttribution: ConversationAdAttribution;
+});
     account: InboxWebhookAccount;
     /**
      * When the conversation document was created.
@@ -14739,7 +15128,7 @@ export type WebhookPayloadConversationStarted = {
     timestamp: string;
 };
 
-export type event21 = 'conversation.started';
+export type event24 = 'conversation.started';
 
 /**
  * Webhook payload for post.external.created / post.external.updated /
@@ -14776,7 +15165,7 @@ export type WebhookPayloadExternalPost = {
     timestamp: string;
 };
 
-export type event22 = 'post.external.created' | 'post.external.updated' | 'post.external.deleted';
+export type event25 = 'post.external.created' | 'post.external.updated' | 'post.external.deleted';
 
 /**
  * Webhook payload for lead.received events (Meta Lead Gen / Instant Forms).
@@ -14852,7 +15241,7 @@ export type WebhookPayloadLead = {
     timestamp: string;
 };
 
-export type event23 = 'lead.received';
+export type event26 = 'lead.received';
 
 export type platform16 = 'facebook';
 
@@ -15394,6 +15783,18 @@ export type WebhookPayloadMessage = {
                 flow_id?: string;
             };
         } | null;
+        /**
+         * Present with `referral` whenever the referral is attributable: on
+         * Instagram and Facebook every forwarded referral (an `ad_id` or a
+         * `ref`), on WhatsApp a referral carrying `ctwa_clid`, `source_id`,
+         * `source_url` or `headline`. The same click enriched from your
+         * synced ads: the ad name, campaign, ad set and ad account Zernio
+         * holds for this ad ID. Built from this message's referral, so it
+         * follows a returning click, while the conversation's
+         * `adAttribution` keeps the first one.
+         *
+         */
+        ad?: (ConversationAdAttribution);
         /**
          * WhatsApp only. Meta's own reason this message has no
          * renderable body. Present when Meta attached an error to the
@@ -15443,7 +15844,7 @@ export type WebhookPayloadMessage = {
     timestamp: string;
 };
 
-export type event24 = 'message.received';
+export type event27 = 'message.received';
 
 /**
  * Which Zernio surface produced the message. Always present and
@@ -15509,7 +15910,7 @@ export type WebhookPayloadMessageDeleted = {
     timestamp: string;
 };
 
-export type event25 = 'message.deleted';
+export type event28 = 'message.deleted';
 
 /**
  * Shared payload for message.delivered, message.read, message.played and
@@ -15577,7 +15978,7 @@ export type WebhookPayloadMessageDeliveryStatus = {
     timestamp: string;
 };
 
-export type event26 = 'message.delivered' | 'message.read' | 'message.played' | 'message.failed';
+export type event29 = 'message.delivered' | 'message.read' | 'message.played' | 'message.failed';
 
 /**
  * Webhook payload for message.edited events. Fires when the sender
@@ -15620,7 +16021,7 @@ export type WebhookPayloadMessageEdited = {
     timestamp: string;
 };
 
-export type event27 = 'message.edited';
+export type event30 = 'message.edited';
 
 /**
  * Webhook payload for message sent events (fired when a message is sent via the API, or from the WhatsApp Business app on Coexistence numbers)
@@ -15866,7 +16267,7 @@ export type WebhookPayloadMessageSent = {
     timestamp: string;
 };
 
-export type event28 = 'message.sent';
+export type event31 = 'message.sent';
 
 /**
  * Every platform whose outgoing messages Zernio observes. sms is absent on purpose: its carrier receipts update delivery status and never raise message.sent.
@@ -15924,7 +16325,7 @@ export type WebhookPayloadPhoneNumberStockAvailable = {
     timestamp: string;
 };
 
-export type event29 = 'phone_number.stock_available';
+export type event32 = 'phone_number.stock_available';
 
 /**
  * Webhook payload for post events
@@ -15979,7 +16380,7 @@ export type WebhookPayloadPost = {
     timestamp: string;
 };
 
-export type event30 = 'post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled';
+export type event33 = 'post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled';
 
 /**
  * Webhook payload for the per-platform terminal events
@@ -16103,7 +16504,7 @@ export type WebhookPayloadPostPlatform = {
     timestamp: string;
 };
 
-export type event31 = 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved';
+export type event34 = 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved';
 
 /**
  * Terminal status this event fires on. Matches the event suffix.
@@ -16168,7 +16569,7 @@ export type WebhookPayloadReaction = {
     timestamp: string;
 };
 
-export type event32 = 'reaction.received';
+export type event35 = 'reaction.received';
 
 export type action = 'added' | 'removed';
 
@@ -16247,7 +16648,7 @@ export type WebhookPayloadReferral = {
     timestamp: string;
 };
 
-export type event33 = 'referral.received';
+export type event36 = 'referral.received';
 
 /**
  * Webhook payload for the review.new event (new review posted on a connected account).
@@ -16279,7 +16680,7 @@ export type WebhookPayloadReviewNew = {
     timestamp: string;
 };
 
-export type event34 = 'review.new';
+export type event37 = 'review.new';
 
 /**
  * Webhook payload for the review.updated event. Fired when the reviewer edits their
@@ -16317,7 +16718,7 @@ export type WebhookPayloadReviewUpdated = {
     timestamp: string;
 };
 
-export type event35 = 'review.updated';
+export type event38 = 'review.updated';
 
 export type WebhookPayloadSequenceEnrollment = {
     /**
@@ -16350,7 +16751,7 @@ export type WebhookPayloadSequenceEnrollment = {
     exitReason?: 'completed' | 'replied' | 'manual' | 'failed' | 'unsubscribed';
 };
 
-export type event36 = 'sequence.enrolled' | 'sequence.exited';
+export type event39 = 'sequence.enrolled' | 'sequence.exited';
 
 /**
  * sequence.exited only. completed: the last step was sent; replied: the contact replied and the sequence exits on reply; manual: unenrolled through the API; failed: the step kept failing to send; unsubscribed: the contact opted out.
@@ -16371,7 +16772,7 @@ export type WebhookPayloadSupportRun = {
     run: SupportRun;
 };
 
-export type event37 = 'support.run.completed' | 'support.run.failed';
+export type event40 = 'support.run.completed' | 'support.run.failed';
 
 /**
  * Webhook payload for test deliveries
@@ -16392,7 +16793,7 @@ export type WebhookPayloadTest = {
     timestamp: string;
 };
 
-export type event38 = 'webhook.test';
+export type event41 = 'webhook.test';
 
 /**
  * Webhook payload for `whatsapp.account.alert_received`, forwarded from Meta's
@@ -16444,7 +16845,7 @@ export type WebhookPayloadWhatsAppAccountAlertReceived = {
     timestamp: string;
 };
 
-export type event39 = 'whatsapp.account.alert_received';
+export type event42 = 'whatsapp.account.alert_received';
 
 export type platform18 = 'whatsapp';
 
@@ -16500,7 +16901,7 @@ export type WebhookPayloadWhatsAppAccountNameStatusUpdated = {
     timestamp: string;
 };
 
-export type event40 = 'whatsapp.account.name_status_updated';
+export type event43 = 'whatsapp.account.name_status_updated';
 
 /**
  * Normalized from Meta's `decision` (REJECTED -> DECLINED, DEFERRED -> PENDING_REVIEW; the review is still open on DEFERRED, not a rejection).
@@ -16558,7 +16959,7 @@ export type WebhookPayloadWhatsAppAccountQualityUpdated = {
     timestamp: string;
 };
 
-export type event41 = 'whatsapp.account.quality_updated';
+export type event44 = 'whatsapp.account.quality_updated';
 
 /**
  * The Meta webhook field that reported the change.
@@ -16634,7 +17035,7 @@ export type WebhookPayloadWhatsAppAccountStatusUpdated = {
     timestamp: string;
 };
 
-export type event42 = 'whatsapp.account.status_updated';
+export type event45 = 'whatsapp.account.status_updated';
 
 /**
  * `active` only on a reinstatement (DISABLED_UPDATE with ban state REINSTATE).
@@ -16691,7 +17092,7 @@ export type WebhookPayloadWhatsAppContactIdentityChanged = {
     timestamp: string;
 };
 
-export type event43 = 'whatsapp.contact.identity_changed';
+export type event46 = 'whatsapp.contact.identity_changed';
 
 /**
  * Which Meta signal reported the change. `user_changed_number`: new phone number. `user_changed_user_id` and `user_id_update`: new BSUID.
@@ -16765,7 +17166,7 @@ export type WebhookPayloadWhatsAppTemplateCategoryUpdated = {
     timestamp: string;
 };
 
-export type event44 = 'whatsapp.template.category_updated';
+export type event47 = 'whatsapp.template.category_updated';
 
 /**
  * `scheduled` is Meta's 24h advance notice of an upcoming
@@ -16847,7 +17248,7 @@ export type WebhookPayloadWhatsAppTemplateStatusUpdated = {
     timestamp: string;
 };
 
-export type event45 = 'whatsapp.template.status_updated';
+export type event48 = 'whatsapp.template.status_updated';
 
 /**
  * New status. Forwarded verbatim from Meta's `event` field.
@@ -16914,7 +17315,7 @@ export type WebhookPayloadWorkflowRun = {
     error?: string;
 };
 
-export type event46 = 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed';
+export type event49 = 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed';
 
 /**
  * running on workflow.run.started; completed or exited (ended on purpose before the last node, e.g. a handoff) on workflow.run.completed; failed on workflow.run.failed.
@@ -17341,7 +17742,7 @@ export type WorkflowNode = {
      *
      * **trigger**: `{ triggerType: inbound_message|api_call|whatsapp_event|referral|story_mention|comment|reaction|lead_received, keywords:[string], matchType: any|contains|exact|regex, onlyFirstMessage:boolean, eventType: message_sent|message_delivered|message_read|message_failed|reaction, referral:{ ref, matchType: exact|prefix|any }, reaction:{ emojis:[string] }, comment:{ keywords:[string], matchType: any|contains|exact|regex, platformPostId }, leadReceived:{ formIds:[string], pageAccountIds:[string], consentCheckboxKey, defaultCountry, allowCrossProfile:boolean }, cooldownHours:int (1-720) }`. Default `triggerType` is `inbound_message` for legacy nodes. A workflow starts only on events of its own trigger type: `inbound_message` on a message, `referral` on an ig.me / m.me / click-to-message ad referral (standalone, or the first message carrying one; the two are deduplicated per conversation within 60 seconds), `story_mention` on an Instagram story mention, `reaction` on a reaction (Instagram, Facebook, WhatsApp, Telegram groups), `comment` on an Instagram or Facebook comment (the run starts with no conversation and its first `send_message`, which must be text (with optional buttons or quick replies) or cards and must follow the trigger directly (checked on save; on some Instagram accounts Meta refuses buttons and cards to commenters who do not follow the account), is sent as a private reply to the comment; the run then continues in the conversation that reply opens; when an active comment automation's keywords match the comment, the automation answers and the workflow does not start), `whatsapp_event` on a WhatsApp status of a message we sent (filtered by `eventType`), `api_call` only via `POST /v1/workflows/{workflowId}/trigger`, and `lead_received` (WhatsApp workflows only) when a Meta lead ad form is submitted. A `lead_received` trigger needs `leadReceived.consentCheckboxKey` and at least one of `formIds` or `pageAccountIds`; a form scope wins over a Page scope, then the earliest activated workflow. It starts only for leads submitted in the last hour and after the workflow was activated, whose consent checkbox (the form's custom disclaimer, see `POST /v1/ads/lead-forms`) is ticked, and whose phone number parses to a valid international number (`defaultCountry`, ISO 3166 alpha-2, defaults to the country of the workflow's WhatsApp number); otherwise the lead is marked `unreachable`. The Page and the WhatsApp number must be in the same profile unless `allowCrossProfile` is true. Every send or call reached first from the trigger must be a WhatsApp template (checked on save). `referral.matchType` defaults to `any`. `cooldownHours` (inbound_message, referral, story_mention, reaction, whatsapp_event and lead_received, where it defaults to 24) stops the same contact from starting the workflow again inside the window. A `whatsapp_event` workflow never starts on the status of a message a workflow, sequence or comment automation sent. A redelivered platform event never starts the same workflow twice.
      *
-     * **Variables** available from the start of every run (absent values are `''`): `lastMessage`, `inboundText`, `triggerText`, `conversationId`, `contact.name`, `contact.phone`, `contact.handle`, `contact.tags` (array), `contact.fields` (the contact's custom fields object), `contact.lastInteractionAt` (ISO date), `contact.lastInteractionHoursAgo` (number), `contact.isFollower` (Instagram, from the stored profile: true, false or `''` when unknown), `referral.ref`, `referral.source`, `referral.type`, `referral.adId`, `postback.payload`, `postback.title`, `quickReply.payload`, `quickReply.title`, `story.id`, `story.url`, `comment.id`, `comment.text`, `comment.platformPostId`, `reaction.emoji`, `reaction.action` (added|removed). `api_call` runs also get the request's `variables`, merged over these. `lead_received` runs also get `lead.id`, `lead.leadgenId`, `lead.formId`, `lead.formName`, `lead.adId`, `lead.adsetId`, `lead.campaignId` and every form answer by its key (`lead.full_name`, `lead.email`, `lead.phone_number`). Template `variableMapping` entries with `field: custom` interpolate `{{...}}` in `customValue`. An array or object interpolated into text renders as JSON.
+     * **Variables** available from the start of every run (absent values are `''`): `lastMessage`, `inboundText`, `triggerText`, `conversationId`, `contact.name`, `contact.phone`, `contact.handle`, `contact.tags` (array), `contact.fields` (the contact's custom fields object), `contact.lastInteractionAt` (ISO date), `contact.lastInteractionHoursAgo` (number), `contact.isFollower` (Instagram, from the stored profile: true, false or `''` when unknown), `referral.ref`, `referral.source`, `referral.type`, `referral.adId`, `referral.adTitle` (the ad title or headline Meta sent), `referral.adName` (the synced ad's name, else `referral.adTitle`), `referral.campaignName` (the synced ad's campaign), `postback.payload`, `postback.title`, `quickReply.payload`, `quickReply.title`, `story.id`, `story.url`, `comment.id`, `comment.text`, `comment.platformPostId`, `reaction.emoji`, `reaction.action` (added|removed). `api_call` runs also get the request's `variables`, merged over these. `lead_received` runs also get `lead.id`, `lead.leadgenId`, `lead.formId`, `lead.formName`, `lead.adId`, `lead.adsetId`, `lead.campaignId` and every form answer by its key (`lead.full_name`, `lead.email`, `lead.phone_number`). Template `variableMapping` entries with `field: custom` interpolate `{{...}}` in `customValue`. An array or object interpolated into text renders as JSON.
      *
      * **send_message**: `{ messageType: text|template|media|interactive|cards, text, template, media:{mediaType:image|video|audio|document, url,caption}, interactive, buttons, quickReplies, messageTag }`. `template` is `{name,language,variableMapping}` for `messageType: template` and `{ type: generic, elements:[{ title, subtitle, imageUrl, buttons }] }` (1 to 10 cards) for `messageType: cards`. `template` and `interactive` are WhatsApp-only. `interactive.type` is inferred from the payload shape when omitted; payloads with neither `type` nor an inferable shape are rejected.
      * Facebook and Instagram only (rejected with a 400 on other platforms; WhatsApp keeps `interactive`): `cards`, plus `buttons` on `text` (cards carry their own buttons) and `quickReplies` / `messageTag` on `text`, `media` and `cards`. `media` takes no `buttons` (a 400 at save). `buttons:[{ type: url|postback|phone, title, url, payload, phone, workflowId }]` (1 to 3, text only and the text then 640 characters at most, sent as Meta's button_template, `phone` Facebook-only, not inside cards), `quickReplies:[{ title, payload, imageUrl, workflowId }]` (1 to 13, not combined with `buttons`) and `messageTag: HUMAN_AGENT|CONFIRMED_EVENT_UPDATE|POST_PURCHASE_UPDATE|ACCOUNT_UPDATE` (Instagram accepts only `HUMAN_AGENT`). Titles are capped at 20 characters (80 for card titles and subtitles). A postback button or quick reply with no `payload` gets `zernio:workflow:<this workflow id>`, so a tap answers this workflow's pending `wait_for_reply` or restarts it; with `workflowId` (a 24-hex workflow id, not combined with `payload`) the tap starts that workflow instead.
@@ -28657,7 +29058,7 @@ export type CreateWebhookSettingsData = {
         /**
          * Events to subscribe to (at least one required)
          */
-        events: Array<('post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved' | 'post.external.created' | 'post.external.updated' | 'post.external.deleted' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'account.ads.sync_failed' | 'account.ads.sync_recovered' | 'analytics.synced' | 'message.received' | 'conversation.started' | 'conversation.control_changed' | 'call.received' | 'call.ended' | 'call.failed' | 'call.permission_request' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.played' | 'message.failed' | 'reaction.received' | 'referral.received' | 'comment.received' | 'review.new' | 'review.updated' | 'lead.received' | 'ad.status_changed' | 'ad.review.approved' | 'ad.review.rejected' | 'ad.video.processed' | 'whatsapp.template.status_updated' | 'whatsapp.template.category_updated' | 'whatsapp.account.name_status_updated' | 'whatsapp.account.quality_updated' | 'whatsapp.account.status_updated' | 'whatsapp.account.alert_received' | 'whatsapp.contact.identity_changed' | 'whatsapp.automatic_event' | 'whatsapp.number.activated' | 'whatsapp.number.declined' | 'whatsapp.number.action_required' | 'whatsapp.number.verification_required' | 'whatsapp.number.suspended' | 'whatsapp.number.reactivated' | 'whatsapp.number.released' | 'whatsapp.number.kyc_submitted' | 'phone_number.stock_available' | 'verification.approved' | 'verification.failed' | 'api.changelog.published' | 'sms.registration.action_required' | 'sms.registration.status_updated' | 'branded_calling.identity.status_updated' | 'branded_calling.identity.action_required' | 'branded_calling.number.status_updated' | 'rcs.agent.status_updated' | 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted' | 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded' | 'contact.tag_added' | 'contact.tag_removed' | 'contact.field_changed' | 'sequence.enrolled' | 'sequence.exited' | 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed' | 'support.run.completed' | 'support.run.failed')>;
+        events: Array<('post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved' | 'post.external.created' | 'post.external.updated' | 'post.external.deleted' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'account.ads.sync_failed' | 'account.ads.sync_recovered' | 'analytics.synced' | 'message.received' | 'conversation.started' | 'conversation.control_changed' | 'call.received' | 'call.ended' | 'call.failed' | 'call.permission_request' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.played' | 'message.failed' | 'reaction.received' | 'referral.received' | 'comment.received' | 'review.new' | 'review.updated' | 'lead.received' | 'ad.status_changed' | 'ad.review.approved' | 'ad.review.rejected' | 'ad.delivery_issue' | 'campaign.budget.depleted' | 'ad_account.status_changed' | 'ad.video.processed' | 'whatsapp.template.status_updated' | 'whatsapp.template.category_updated' | 'whatsapp.account.name_status_updated' | 'whatsapp.account.quality_updated' | 'whatsapp.account.status_updated' | 'whatsapp.account.alert_received' | 'whatsapp.contact.identity_changed' | 'whatsapp.automatic_event' | 'whatsapp.number.activated' | 'whatsapp.number.declined' | 'whatsapp.number.action_required' | 'whatsapp.number.verification_required' | 'whatsapp.number.suspended' | 'whatsapp.number.reactivated' | 'whatsapp.number.released' | 'whatsapp.number.kyc_submitted' | 'phone_number.stock_available' | 'verification.approved' | 'verification.failed' | 'api.changelog.published' | 'sms.registration.action_required' | 'sms.registration.status_updated' | 'branded_calling.identity.status_updated' | 'branded_calling.identity.action_required' | 'branded_calling.number.status_updated' | 'rcs.agent.status_updated' | 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted' | 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded' | 'contact.tag_added' | 'contact.tag_removed' | 'contact.field_changed' | 'sequence.enrolled' | 'sequence.exited' | 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed' | 'support.run.completed' | 'support.run.failed')>;
         /**
          * Enable or disable webhook delivery. Defaults to `true` when omitted.
          */
@@ -28723,7 +29124,7 @@ export type UpdateWebhookSettingsData = {
         /**
          * Events to subscribe to. Must contain at least one event if provided.
          */
-        events?: Array<('post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved' | 'post.external.created' | 'post.external.updated' | 'post.external.deleted' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'account.ads.sync_failed' | 'account.ads.sync_recovered' | 'analytics.synced' | 'message.received' | 'conversation.started' | 'conversation.control_changed' | 'call.received' | 'call.ended' | 'call.failed' | 'call.permission_request' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.played' | 'message.failed' | 'reaction.received' | 'referral.received' | 'comment.received' | 'review.new' | 'review.updated' | 'lead.received' | 'ad.status_changed' | 'ad.review.approved' | 'ad.review.rejected' | 'ad.video.processed' | 'whatsapp.template.status_updated' | 'whatsapp.template.category_updated' | 'whatsapp.account.name_status_updated' | 'whatsapp.account.quality_updated' | 'whatsapp.account.status_updated' | 'whatsapp.account.alert_received' | 'whatsapp.contact.identity_changed' | 'whatsapp.automatic_event' | 'whatsapp.number.activated' | 'whatsapp.number.declined' | 'whatsapp.number.action_required' | 'whatsapp.number.verification_required' | 'whatsapp.number.suspended' | 'whatsapp.number.reactivated' | 'whatsapp.number.released' | 'whatsapp.number.kyc_submitted' | 'phone_number.stock_available' | 'verification.approved' | 'verification.failed' | 'api.changelog.published' | 'sms.registration.action_required' | 'sms.registration.status_updated' | 'branded_calling.identity.status_updated' | 'branded_calling.identity.action_required' | 'branded_calling.number.status_updated' | 'rcs.agent.status_updated' | 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted' | 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded' | 'contact.tag_added' | 'contact.tag_removed' | 'contact.field_changed' | 'sequence.enrolled' | 'sequence.exited' | 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed' | 'support.run.completed' | 'support.run.failed')>;
+        events?: Array<('post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved' | 'post.external.created' | 'post.external.updated' | 'post.external.deleted' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'account.ads.sync_failed' | 'account.ads.sync_recovered' | 'analytics.synced' | 'message.received' | 'conversation.started' | 'conversation.control_changed' | 'call.received' | 'call.ended' | 'call.failed' | 'call.permission_request' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.played' | 'message.failed' | 'reaction.received' | 'referral.received' | 'comment.received' | 'review.new' | 'review.updated' | 'lead.received' | 'ad.status_changed' | 'ad.review.approved' | 'ad.review.rejected' | 'ad.delivery_issue' | 'campaign.budget.depleted' | 'ad_account.status_changed' | 'ad.video.processed' | 'whatsapp.template.status_updated' | 'whatsapp.template.category_updated' | 'whatsapp.account.name_status_updated' | 'whatsapp.account.quality_updated' | 'whatsapp.account.status_updated' | 'whatsapp.account.alert_received' | 'whatsapp.contact.identity_changed' | 'whatsapp.automatic_event' | 'whatsapp.number.activated' | 'whatsapp.number.declined' | 'whatsapp.number.action_required' | 'whatsapp.number.verification_required' | 'whatsapp.number.suspended' | 'whatsapp.number.reactivated' | 'whatsapp.number.released' | 'whatsapp.number.kyc_submitted' | 'phone_number.stock_available' | 'verification.approved' | 'verification.failed' | 'api.changelog.published' | 'sms.registration.action_required' | 'sms.registration.status_updated' | 'branded_calling.identity.status_updated' | 'branded_calling.identity.action_required' | 'branded_calling.number.status_updated' | 'rcs.agent.status_updated' | 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted' | 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded' | 'contact.tag_added' | 'contact.tag_removed' | 'contact.field_changed' | 'sequence.enrolled' | 'sequence.exited' | 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed' | 'support.run.completed' | 'support.run.failed')>;
         /**
          * Enable or disable webhook delivery
          */
@@ -28893,7 +29294,7 @@ export type TestWebhookData = {
         /**
          * Send a sample payload of this event instead of `webhook.test`. The sample is marked with `test: true`.
          */
-        event?: 'post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved' | 'post.external.created' | 'post.external.updated' | 'post.external.deleted' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'account.ads.sync_failed' | 'account.ads.sync_recovered' | 'analytics.synced' | 'message.received' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.played' | 'message.failed' | 'reaction.received' | 'referral.received' | 'conversation.started' | 'conversation.control_changed' | 'contact.tag_added' | 'contact.tag_removed' | 'contact.field_changed' | 'sequence.enrolled' | 'sequence.exited' | 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed' | 'support.run.completed' | 'support.run.failed' | 'call.received' | 'call.ended' | 'call.failed' | 'call.permission_request' | 'comment.received' | 'review.new' | 'review.updated' | 'ad.status_changed' | 'ad.review.approved' | 'ad.review.rejected' | 'ad.video.processed' | 'lead.received' | 'whatsapp.template.status_updated' | 'whatsapp.template.category_updated' | 'whatsapp.account.name_status_updated' | 'whatsapp.account.quality_updated' | 'whatsapp.account.status_updated' | 'whatsapp.account.alert_received' | 'whatsapp.contact.identity_changed' | 'whatsapp.number.activated' | 'whatsapp.number.declined' | 'whatsapp.number.action_required' | 'whatsapp.automatic_event' | 'whatsapp.number.verification_required' | 'whatsapp.number.suspended' | 'whatsapp.number.reactivated' | 'whatsapp.number.released' | 'whatsapp.number.kyc_submitted' | 'phone_number.stock_available' | 'sms.registration.action_required' | 'sms.registration.status_updated' | 'branded_calling.identity.status_updated' | 'branded_calling.identity.action_required' | 'branded_calling.number.status_updated' | 'rcs.agent.status_updated' | 'verification.approved' | 'verification.failed' | 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted' | 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded' | 'api.changelog.published';
+        event?: 'post.scheduled' | 'post.published' | 'post.failed' | 'post.partial' | 'post.cancelled' | 'post.recycled' | 'post.platform.published' | 'post.platform.failed' | 'post.platform.deleted' | 'post.tiktok.url_resolved' | 'post.external.created' | 'post.external.updated' | 'post.external.deleted' | 'account.connected' | 'account.disconnected' | 'account.ads.initial_sync_completed' | 'account.ads.sync_failed' | 'account.ads.sync_recovered' | 'analytics.synced' | 'message.received' | 'message.sent' | 'message.edited' | 'message.deleted' | 'message.delivered' | 'message.read' | 'message.played' | 'message.failed' | 'reaction.received' | 'referral.received' | 'conversation.started' | 'conversation.control_changed' | 'contact.tag_added' | 'contact.tag_removed' | 'contact.field_changed' | 'sequence.enrolled' | 'sequence.exited' | 'workflow.run.started' | 'workflow.run.completed' | 'workflow.run.failed' | 'support.run.completed' | 'support.run.failed' | 'call.received' | 'call.ended' | 'call.failed' | 'call.permission_request' | 'comment.received' | 'review.new' | 'review.updated' | 'ad.status_changed' | 'ad.review.approved' | 'ad.review.rejected' | 'ad.delivery_issue' | 'campaign.budget.depleted' | 'ad_account.status_changed' | 'ad.video.processed' | 'lead.received' | 'whatsapp.template.status_updated' | 'whatsapp.template.category_updated' | 'whatsapp.account.name_status_updated' | 'whatsapp.account.quality_updated' | 'whatsapp.account.status_updated' | 'whatsapp.account.alert_received' | 'whatsapp.contact.identity_changed' | 'whatsapp.number.activated' | 'whatsapp.number.declined' | 'whatsapp.number.action_required' | 'whatsapp.automatic_event' | 'whatsapp.number.verification_required' | 'whatsapp.number.suspended' | 'whatsapp.number.reactivated' | 'whatsapp.number.released' | 'whatsapp.number.kyc_submitted' | 'phone_number.stock_available' | 'sms.registration.action_required' | 'sms.registration.status_updated' | 'branded_calling.identity.status_updated' | 'branded_calling.identity.action_required' | 'branded_calling.number.status_updated' | 'rcs.agent.status_updated' | 'verification.approved' | 'verification.failed' | 'commerce.product.created' | 'commerce.product.updated' | 'commerce.product.deleted' | 'commerce.order.created' | 'commerce.order.updated' | 'commerce.order.refunded' | 'api.changelog.published';
     };
 };
 
@@ -29177,112 +29578,8 @@ export type ListInboxConversationsResponse = ({
              */
             fetchedAt?: (string) | null;
         } | null;
-        /**
-         * Click attribution for a conversation that started from a Meta ad or
-         * a ref-tagged ig.me / m.me link. Absent when the conversation did not
-         * originate from an attributable click.
-         *
-         * Captured from the referral Meta delivers for the click. If the same
-         * person later arrives through a different ad or link, the original
-         * values are kept, so the first referral wins; read the fresh referral
-         * per click on the `message.received` / `referral.received` webhooks
-         * instead. One exception on WhatsApp: when Meta omits `ctwa_clid`
-         * from that referral, a later Meta automatic event can supply it and
-         * refresh `ctwa_captured_at`, so treat `ctwa_captured_at` as the time
-         * Zernio stored the value, not the time of the click.
-         *
-         * Two families of keys, one per surface. They never appear together:
-         *
-         * - `ctwa_*` is WhatsApp Click-to-WhatsApp. The ad ID is
-         * `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp.
-         * - `meta_ad_*` is Instagram Click-to-Direct, Facebook Messenger
-         * Click-to-Message, and ig.me / m.me ref links. The ad ID is
-         * `meta_ad_id` (ad clicks only; a link capture carries
-         * `meta_ad_ref` without it). `ctwa_clid` never appears on these
-         * platforms.
-         *
-         * Every key is optional and only the keys Meta supplied are returned, so
-         * read defensively. Meta does not send a campaign or ad set ID, so none
-         * is exposed here. More keys may be added over time. Treat any key you
-         * do not recognise as an opaque string.
-         *
-         * Key names differ from the `message.received` webhook on purpose. The
-         * webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`)
-         * while the stored conversation record uses the prefixed names below.
-         * Renaming either side would break existing integrations, so both
-         * spellings are kept.
-         *
-         */
-        metadata?: {
-            /**
-             * WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it.
-             */
-            ctwa_clid?: string;
-            /**
-             * WhatsApp only. The Meta ad ID the user clicked. This is the WhatsApp equivalent of meta_ad_id.
-             */
-            ctwa_source_id?: string;
-            /**
-             * WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).
-             */
-            ctwa_source_type?: string;
-            /**
-             * WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.
-             */
-            ctwa_source_url?: string;
-            /**
-             * WhatsApp only. Headline of the ad creative at click time.
-             */
-            ctwa_headline?: string;
-            /**
-             * WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured.
-             */
-            ctwa_captured_at?: string;
-            /**
-             * Instagram and Facebook only. The Meta ad ID the user clicked. Present for ad clicks; absent when the capture came from an ig.me / m.me ref link.
-             */
-            meta_ad_id?: string;
-            /**
-             * Instagram and Facebook only. Meta-supplied source identifier: ADS for ad clicks; SHORTLINK, SHORTLINKS or IGME-SOURCE-LINK for ref links (treat as opaque).
-             */
-            meta_ad_source?: string;
-            /**
-             * Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.
-             */
-            meta_ad_type?: string;
-            /**
-             * Instagram and Facebook only. The ref parameter passed through from the ad creative or the ig.me / m.me link.
-             */
-            meta_ad_ref?: string;
-            /**
-             * Instagram and Facebook only. Title of the ad creative at click time.
-             */
-            meta_ad_title?: string;
-            /**
-             * Instagram and Facebook only. Image of the ad creative at click time.
-             */
-            meta_ad_photo_url?: string;
-            /**
-             * Instagram and Facebook only. Video of the ad creative at click time.
-             */
-            meta_ad_video_url?: string;
-            /**
-             * Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.
-             */
-            meta_ad_post_id?: string;
-            /**
-             * Instagram and Facebook only. The catalogue product the user clicked, for product ads.
-             */
-            meta_ad_product_id?: string;
-            /**
-             * Instagram and Facebook only. The Meta flow the ad launched, for flow ads.
-             */
-            meta_ad_flow_id?: string;
-            /**
-             * Instagram and Facebook only. When Zernio stored this referral. Always present when an Instagram or Facebook referral was captured.
-             */
-            meta_ad_captured_at?: string;
-        } | null;
+        metadata?: InboxConversationAdMetadata;
+        adAttribution?: ConversationAdAttribution;
     }>;
     pagination?: {
         hasMore?: boolean;
@@ -29680,81 +29977,8 @@ export type GetInboxConversationResponse = ({
              */
             fetchedAt?: (string) | null;
         } | null;
-        /**
-         * Ad-click attribution for a conversation that started from a Meta ad.
-         * Absent when the conversation did not originate from an ad click.
-         *
-         * Captured once, from the first inbound message Meta attaches the referral
-         * to, and never overwritten. If the same person later clicks a different
-         * ad, the original values are kept. On Instagram Click-to-Direct that is
-         * usually not the first message: Meta first delivers the ad post as an
-         * attachment-only `share` / `ig_post` message with no referral, then
-         * attaches the referral to the next message.
-         *
-         * This operation currently returns only the `meta_ad_*` family, which
-         * covers Instagram Click-to-Direct and Facebook Messenger
-         * Click-to-Message. WhatsApp Click-to-WhatsApp attribution (the `ctwa_*`
-         * keys, where the ad ID is `ctwa_source_id`) is returned by
-         * `GET /v1/inbox/conversations` instead.
-         *
-         * Every key is optional and only the keys Meta supplied are returned, so
-         * read defensively. Meta does not send a campaign or ad set ID, so none is
-         * exposed here. More keys may be added over time. Treat any key you do not
-         * recognise as an opaque string.
-         *
-         * Key names differ from the `message.received` webhook on purpose. The
-         * webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`)
-         * while the stored conversation record uses the prefixed names below.
-         * Renaming either side would break existing integrations, so both
-         * spellings are kept.
-         *
-         */
-        metadata?: {
-            /**
-             * The Meta ad ID the user clicked. Always present when a referral was captured.
-             */
-            meta_ad_id?: string;
-            /**
-             * Meta-supplied source identifier, for example ADS.
-             */
-            meta_ad_source?: string;
-            /**
-             * Meta-supplied referral type, for example OPEN_THREAD.
-             */
-            meta_ad_type?: string;
-            /**
-             * The ref parameter passed through from the ad creative.
-             */
-            meta_ad_ref?: string;
-            /**
-             * Title of the ad creative at click time.
-             */
-            meta_ad_title?: string;
-            /**
-             * Image of the ad creative at click time.
-             */
-            meta_ad_photo_url?: string;
-            /**
-             * Video of the ad creative at click time.
-             */
-            meta_ad_video_url?: string;
-            /**
-             * The organic post the ad promoted, when the ad was a boosted post.
-             */
-            meta_ad_post_id?: string;
-            /**
-             * The catalogue product the user clicked, for product ads.
-             */
-            meta_ad_product_id?: string;
-            /**
-             * The Meta flow the ad launched, for flow ads.
-             */
-            meta_ad_flow_id?: string;
-            /**
-             * When Zernio stored this referral. Always present when a referral was captured.
-             */
-            meta_ad_captured_at?: string;
-        } | null;
+        metadata?: InboxConversationAdMetadata;
+        adAttribution?: ConversationAdAttribution;
     };
 });