late-sdk 0.0.644 → 0.0.646

data/lib/zernio-sdk/models/list_inbox_conversations200_response_data_inner.rb

@@ -47,6 +47,8 @@ module Zernio
 
     attr_accessor :instagram_profile
 
+    attr_accessor :metadata
+
     class EnumAttributeValidator
       attr_reader :datatype
       attr_reader :allowable_values
@@ -85,7 +87,8 @@ module Zernio
         :'status' => :'status',
         :'unread_count' => :'unreadCount',
         :'url' => :'url',
-        :'instagram_profile' => :'instagramProfile'
+        :'instagram_profile' => :'instagramProfile',
+        :'metadata' => :'metadata'
       }
     end
 
@@ -115,7 +118,8 @@ module Zernio
         :'status' => :'String',
         :'unread_count' => :'Integer',
         :'url' => :'String',
-        :'instagram_profile' => :'ListInboxConversations200ResponseDataInnerInstagramProfile'
+        :'instagram_profile' => :'ListInboxConversations200ResponseDataInnerInstagramProfile',
+        :'metadata' => :'ListInboxConversations200ResponseDataInnerMetadata'
       }
     end
 
@@ -200,6 +204,10 @@ module Zernio
       if attributes.key?(:'instagram_profile')
         self.instagram_profile = attributes[:'instagram_profile']
       end
+
+      if attributes.key?(:'metadata')
+        self.metadata = attributes[:'metadata']
+      end
     end
 
     # Show invalid properties with the reasons. Usually used together with valid?
@@ -259,7 +267,8 @@ module Zernio
           status == o.status &&
           unread_count == o.unread_count &&
           url == o.url &&
-          instagram_profile == o.instagram_profile
+          instagram_profile == o.instagram_profile &&
+          metadata == o.metadata
     end
 
     # @see the `==` method
@@ -271,7 +280,7 @@ module Zernio
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [id, platform, account_id, account_username, participant_id, participant_name, participant_picture, participant_verified_type, last_message, updated_time, status, unread_count, url, instagram_profile].hash
+      [id, platform, account_id, account_username, participant_id, participant_name, participant_picture, participant_verified_type, last_message, updated_time, status, unread_count, url, instagram_profile, metadata].hash
     end
 
     # Builds the object from hash

data/lib/zernio-sdk/models/list_inbox_conversations200_response_data_inner_metadata.rb

@@ -0,0 +1,309 @@
+=begin
+#Zernio API
+
+#API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api 
+
+The version of the OpenAPI document: 1.0.4
+Contact: support@zernio.com
+Generated by: https://openapi-generator.tech
+Generator version: 7.19.0
+
+=end
+
+require 'date'
+require 'time'
+
+module Zernio
+  # Ad-click attribution for a conversation that started from a Meta ad. Absent when the conversation did not originate from an ad click.  Captured from the referral Meta attaches to the first inbound message after the click, which is the only message that carries it. If the same person later clicks a different ad, the original values are kept, so the first ad wins. 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 and Facebook Messenger     Click-to-Message. The ad ID is `meta_ad_id`. `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. 
+  class ListInboxConversations200ResponseDataInnerMetadata < ApiModelBase
+    # 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.
+    attr_accessor :ctwa_clid
+
+    # WhatsApp only. The Meta ad ID the user clicked. This is the WhatsApp equivalent of meta_ad_id.
+    attr_accessor :ctwa_source_id
+
+    # WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).
+    attr_accessor :ctwa_source_type
+
+    # WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.
+    attr_accessor :ctwa_source_url
+
+    # WhatsApp only. Headline of the ad creative at click time.
+    attr_accessor :ctwa_headline
+
+    # WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured.
+    attr_accessor :ctwa_captured_at
+
+    # Instagram and Facebook only. The Meta ad ID the user clicked. Always present when an Instagram or Facebook referral was captured.
+    attr_accessor :meta_ad_id
+
+    # Instagram and Facebook only. Meta-supplied source identifier, for example ADS.
+    attr_accessor :meta_ad_source
+
+    # Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.
+    attr_accessor :meta_ad_type
+
+    # Instagram and Facebook only. The ref parameter passed through from the ad creative.
+    attr_accessor :meta_ad_ref
+
+    # Instagram and Facebook only. Title of the ad creative at click time.
+    attr_accessor :meta_ad_title
+
+    # Instagram and Facebook only. Image of the ad creative at click time.
+    attr_accessor :meta_ad_photo_url
+
+    # Instagram and Facebook only. Video of the ad creative at click time.
+    attr_accessor :meta_ad_video_url
+
+    # Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.
+    attr_accessor :meta_ad_post_id
+
+    # Instagram and Facebook only. The catalogue product the user clicked, for product ads.
+    attr_accessor :meta_ad_product_id
+
+    # Instagram and Facebook only. The Meta flow the ad launched, for flow ads.
+    attr_accessor :meta_ad_flow_id
+
+    # Instagram and Facebook only. When Zernio stored this referral. Always present when an Instagram or Facebook referral was captured.
+    attr_accessor :meta_ad_captured_at
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'ctwa_clid' => :'ctwa_clid',
+        :'ctwa_source_id' => :'ctwa_source_id',
+        :'ctwa_source_type' => :'ctwa_source_type',
+        :'ctwa_source_url' => :'ctwa_source_url',
+        :'ctwa_headline' => :'ctwa_headline',
+        :'ctwa_captured_at' => :'ctwa_captured_at',
+        :'meta_ad_id' => :'meta_ad_id',
+        :'meta_ad_source' => :'meta_ad_source',
+        :'meta_ad_type' => :'meta_ad_type',
+        :'meta_ad_ref' => :'meta_ad_ref',
+        :'meta_ad_title' => :'meta_ad_title',
+        :'meta_ad_photo_url' => :'meta_ad_photo_url',
+        :'meta_ad_video_url' => :'meta_ad_video_url',
+        :'meta_ad_post_id' => :'meta_ad_post_id',
+        :'meta_ad_product_id' => :'meta_ad_product_id',
+        :'meta_ad_flow_id' => :'meta_ad_flow_id',
+        :'meta_ad_captured_at' => :'meta_ad_captured_at'
+      }
+    end
+
+    # Returns attribute mapping this model knows about
+    def self.acceptable_attribute_map
+      attribute_map
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      acceptable_attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'ctwa_clid' => :'String',
+        :'ctwa_source_id' => :'String',
+        :'ctwa_source_type' => :'String',
+        :'ctwa_source_url' => :'String',
+        :'ctwa_headline' => :'String',
+        :'ctwa_captured_at' => :'Time',
+        :'meta_ad_id' => :'String',
+        :'meta_ad_source' => :'String',
+        :'meta_ad_type' => :'String',
+        :'meta_ad_ref' => :'String',
+        :'meta_ad_title' => :'String',
+        :'meta_ad_photo_url' => :'String',
+        :'meta_ad_video_url' => :'String',
+        :'meta_ad_post_id' => :'String',
+        :'meta_ad_product_id' => :'String',
+        :'meta_ad_flow_id' => :'String',
+        :'meta_ad_captured_at' => :'Time'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `Zernio::ListInboxConversations200ResponseDataInnerMetadata` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      acceptable_attribute_map = self.class.acceptable_attribute_map
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!acceptable_attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `Zernio::ListInboxConversations200ResponseDataInnerMetadata`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'ctwa_clid')
+        self.ctwa_clid = attributes[:'ctwa_clid']
+      end
+
+      if attributes.key?(:'ctwa_source_id')
+        self.ctwa_source_id = attributes[:'ctwa_source_id']
+      end
+
+      if attributes.key?(:'ctwa_source_type')
+        self.ctwa_source_type = attributes[:'ctwa_source_type']
+      end
+
+      if attributes.key?(:'ctwa_source_url')
+        self.ctwa_source_url = attributes[:'ctwa_source_url']
+      end
+
+      if attributes.key?(:'ctwa_headline')
+        self.ctwa_headline = attributes[:'ctwa_headline']
+      end
+
+      if attributes.key?(:'ctwa_captured_at')
+        self.ctwa_captured_at = attributes[:'ctwa_captured_at']
+      end
+
+      if attributes.key?(:'meta_ad_id')
+        self.meta_ad_id = attributes[:'meta_ad_id']
+      end
+
+      if attributes.key?(:'meta_ad_source')
+        self.meta_ad_source = attributes[:'meta_ad_source']
+      end
+
+      if attributes.key?(:'meta_ad_type')
+        self.meta_ad_type = attributes[:'meta_ad_type']
+      end
+
+      if attributes.key?(:'meta_ad_ref')
+        self.meta_ad_ref = attributes[:'meta_ad_ref']
+      end
+
+      if attributes.key?(:'meta_ad_title')
+        self.meta_ad_title = attributes[:'meta_ad_title']
+      end
+
+      if attributes.key?(:'meta_ad_photo_url')
+        self.meta_ad_photo_url = attributes[:'meta_ad_photo_url']
+      end
+
+      if attributes.key?(:'meta_ad_video_url')
+        self.meta_ad_video_url = attributes[:'meta_ad_video_url']
+      end
+
+      if attributes.key?(:'meta_ad_post_id')
+        self.meta_ad_post_id = attributes[:'meta_ad_post_id']
+      end
+
+      if attributes.key?(:'meta_ad_product_id')
+        self.meta_ad_product_id = attributes[:'meta_ad_product_id']
+      end
+
+      if attributes.key?(:'meta_ad_flow_id')
+        self.meta_ad_flow_id = attributes[:'meta_ad_flow_id']
+      end
+
+      if attributes.key?(:'meta_ad_captured_at')
+        self.meta_ad_captured_at = attributes[:'meta_ad_captured_at']
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      true
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          ctwa_clid == o.ctwa_clid &&
+          ctwa_source_id == o.ctwa_source_id &&
+          ctwa_source_type == o.ctwa_source_type &&
+          ctwa_source_url == o.ctwa_source_url &&
+          ctwa_headline == o.ctwa_headline &&
+          ctwa_captured_at == o.ctwa_captured_at &&
+          meta_ad_id == o.meta_ad_id &&
+          meta_ad_source == o.meta_ad_source &&
+          meta_ad_type == o.meta_ad_type &&
+          meta_ad_ref == o.meta_ad_ref &&
+          meta_ad_title == o.meta_ad_title &&
+          meta_ad_photo_url == o.meta_ad_photo_url &&
+          meta_ad_video_url == o.meta_ad_video_url &&
+          meta_ad_post_id == o.meta_ad_post_id &&
+          meta_ad_product_id == o.meta_ad_product_id &&
+          meta_ad_flow_id == o.meta_ad_flow_id &&
+          meta_ad_captured_at == o.meta_ad_captured_at
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [ctwa_clid, ctwa_source_id, ctwa_source_type, ctwa_source_url, ctwa_headline, ctwa_captured_at, meta_ad_id, meta_ad_source, meta_ad_type, meta_ad_ref, meta_ad_title, meta_ad_photo_url, meta_ad_video_url, meta_ad_post_id, meta_ad_product_id, meta_ad_flow_id, meta_ad_captured_at].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+  end
+
+end

data/lib/zernio-sdk/version.rb

@@ -11,5 +11,5 @@ Generator version: 7.19.0
 =end
 
 module Zernio
-  VERSION = '0.0.644'
+  VERSION = '0.0.646'
 end

data/lib/zernio-sdk.rb

@@ -551,6 +551,7 @@ require 'zernio-sdk/models/get_google_business_verifications200_response_voice_o
 require 'zernio-sdk/models/get_google_business_verifications200_response_voice_of_merchant_state_verify'
 require 'zernio-sdk/models/get_inbox_conversation200_response'
 require 'zernio-sdk/models/get_inbox_conversation200_response_data'
+require 'zernio-sdk/models/get_inbox_conversation200_response_data_metadata'
 require 'zernio-sdk/models/get_inbox_conversation_analytics200_response'
 require 'zernio-sdk/models/get_inbox_conversation_analytics200_response_by_source_inner'
 require 'zernio-sdk/models/get_inbox_conversation_analytics200_response_summary'
@@ -873,6 +874,7 @@ require 'zernio-sdk/models/list_inbox_conversation_analytics200_response_paginat
 require 'zernio-sdk/models/list_inbox_conversations200_response'
 require 'zernio-sdk/models/list_inbox_conversations200_response_data_inner'
 require 'zernio-sdk/models/list_inbox_conversations200_response_data_inner_instagram_profile'
+require 'zernio-sdk/models/list_inbox_conversations200_response_data_inner_metadata'
 require 'zernio-sdk/models/list_inbox_conversations200_response_meta'
 require 'zernio-sdk/models/list_inbox_conversations200_response_meta_failed_accounts_inner'
 require 'zernio-sdk/models/list_inbox_conversations200_response_pagination'

data/openapi.yaml

@@ -6562,7 +6562,9 @@ components:
       properties:
         spend: { type: number }
         impressions: { type: integer }
-        reach: { type: integer }
+        reach:
+          type: integer
+          description: "Unique people reached in the requested date range. Meta (facebook/instagram): Meta's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery; on a transient Meta error the value temporarily falls back to a sum of per-day reach, which overcounts people reached on multiple days or by multiple child ads). Because it is de-duplicated, Meta reach is NOT additive: neither daily values nor child nodes sum to the range total. TikTok: sum of per-day reach, so multi-day ranges overcount vs TikTok Ads Manager. Google, LinkedIn, X, Pinterest and OpenAI report 0 (reach not synced). Only derive frequency (impressions / reach) for Meta."
         clicks: { type: integer }
         ctr: { type: number, description: Click-through rate (%) }
         cpc: { type: number, description: Cost per click }
@@ -6618,7 +6620,9 @@ components:
         called with `timeIncrement=1`. Rate metrics (ctr/cpc/cpm/costPerConversion/
         roas/videoAvgTimeWatchedActions) are recomputed per day from that day's
         sums, so summing the additive fields across a node's `daily[]` reproduces
-        its aggregated `metrics` total. Do NOT sum or plain-average
+        its aggregated `metrics` total. `reach` is the exception: on Meta the
+        aggregated total is de-duplicated across the range, so daily reach does
+        not sum to it. Do NOT sum or plain-average
         `videoAvgTimeWatchedActions` across days: the range value is the
         play-weighted average of the daily values.
       allOf:
@@ -7177,7 +7181,7 @@ components:
         daily:
           type: array
           items: { $ref: '#/components/schemas/AdDailyMetrics' }
-          description: "Per-day metric series for this campaign. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` (any `dailyLevel`). This is the per-campaign daily trend — summing its additive fields reproduces the campaign `metrics` total."
+          description: "Per-day metric series for this campaign. Present only when `GET /v1/ads/tree` is called with `timeIncrement=1` (any `dailyLevel`). This is the per-campaign daily trend — summing its additive fields reproduces the campaign `metrics` total, except `reach`: on Meta the range total is de-duplicated, so daily reach does not sum to it."
     AdCampaign:
       type: object
       properties:
@@ -22563,7 +22567,7 @@ paths:
           description: Filter by profile ID
         - name: platform
           in: query
-          schema: { type: string, enum: [facebook, instagram, twitter, bluesky, reddit, telegram] }
+          schema: { type: string, enum: [facebook, instagram, twitter, bluesky, reddit, telegram, whatsapp] }
           description: Filter by platform
         - name: status
           in: query
@@ -22638,6 +22642,92 @@ paths:
                               type: [string, "null"]
                               format: date-time
                               description: When this profile data was last fetched from Instagram
+                        metadata:
+                          type: [object, "null"]
+                          description: |
+                            Ad-click attribution for a conversation that started from a Meta ad.
+                            Absent when the conversation did not originate from an ad click.
+
+                            Captured from the referral Meta attaches to the first inbound message
+                            after the click, which is the only message that carries it. If the same
+                            person later clicks a different ad, the original values are kept, so the
+                            first ad wins. 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 and Facebook Messenger
+                                Click-to-Message. The ad ID is `meta_ad_id`. `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.
+                          properties:
+                            ctwa_clid:
+                              type: string
+                              description: "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_source_id:
+                              type: string
+                              description: "WhatsApp only. The Meta ad ID the user clicked. This is the WhatsApp equivalent of meta_ad_id."
+                            ctwa_source_type:
+                              type: string
+                              description: "WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post)."
+                            ctwa_source_url:
+                              type: string
+                              description: "WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link."
+                            ctwa_headline:
+                              type: string
+                              description: "WhatsApp only. Headline of the ad creative at click time."
+                            ctwa_captured_at:
+                              type: string
+                              format: date-time
+                              description: "WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured."
+                            meta_ad_id:
+                              type: string
+                              description: "Instagram and Facebook only. The Meta ad ID the user clicked. Always present when an Instagram or Facebook referral was captured."
+                            meta_ad_source:
+                              type: string
+                              description: "Instagram and Facebook only. Meta-supplied source identifier, for example ADS."
+                            meta_ad_type:
+                              type: string
+                              description: "Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD."
+                            meta_ad_ref:
+                              type: string
+                              description: "Instagram and Facebook only. The ref parameter passed through from the ad creative."
+                            meta_ad_title:
+                              type: string
+                              description: "Instagram and Facebook only. Title of the ad creative at click time."
+                            meta_ad_photo_url:
+                              type: string
+                              description: "Instagram and Facebook only. Image of the ad creative at click time."
+                            meta_ad_video_url:
+                              type: string
+                              description: "Instagram and Facebook only. Video of the ad creative at click time."
+                            meta_ad_post_id:
+                              type: string
+                              description: "Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post."
+                            meta_ad_product_id:
+                              type: string
+                              description: "Instagram and Facebook only. The catalogue product the user clicked, for product ads."
+                            meta_ad_flow_id:
+                              type: string
+                              description: "Instagram and Facebook only. The Meta flow the ad launched, for flow ads."
+                            meta_ad_captured_at:
+                              type: string
+                              format: date-time
+                              description: "Instagram and Facebook only. When Zernio stored this referral. Always present when an Instagram or Facebook referral was captured."
                   pagination:
                     type: object
                     properties:
@@ -23024,6 +23114,68 @@ paths:
                             type: [string, "null"]
                             format: date-time
                             description: When this profile data was last fetched from Instagram
+                      metadata:
+                        type: [object, "null"]
+                        description: |
+                          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, on the first inbound message after the click, and never
+                          overwritten. If the same person later clicks a different ad, the
+                          original values are kept. Meta only sends the referral on that first
+                          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.
+                        properties:
+                          meta_ad_id:
+                            type: string
+                            description: "The Meta ad ID the user clicked. Always present when a referral was captured."
+                          meta_ad_source:
+                            type: string
+                            description: "Meta-supplied source identifier, for example ADS."
+                          meta_ad_type:
+                            type: string
+                            description: "Meta-supplied referral type, for example OPEN_THREAD."
+                          meta_ad_ref:
+                            type: string
+                            description: "The ref parameter passed through from the ad creative."
+                          meta_ad_title:
+                            type: string
+                            description: "Title of the ad creative at click time."
+                          meta_ad_photo_url:
+                            type: string
+                            description: "Image of the ad creative at click time."
+                          meta_ad_video_url:
+                            type: string
+                            description: "Video of the ad creative at click time."
+                          meta_ad_post_id:
+                            type: string
+                            description: "The organic post the ad promoted, when the ad was a boosted post."
+                          meta_ad_product_id:
+                            type: string
+                            description: "The catalogue product the user clicked, for product ads."
+                          meta_ad_flow_id:
+                            type: string
+                            description: "The Meta flow the ad launched, for flow ads."
+                          meta_ad_captured_at:
+                            type: string
+                            format: date-time
+                            description: "When Zernio stored this referral. Always present when a referral was captured."
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: Inbox addon required
@@ -35773,7 +35925,7 @@ paths:
         - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of the METRICS date range (YYYY-MM-DD). Affects only the spend/impression numbers overlaid on each node, NOT which campaigns are returned. Defaults to 90 days ago." }
         - { name: toDate, in: query, schema: { type: string, format: date }, description: "End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range." }
         - { name: sort, in: query, schema: { type: string, enum: [newest, oldest, spend_desc, spend_asc], default: newest }, description: "Campaign-level sort order. `newest` (default) / `oldest` order by the campaign's newest-ad createdAt. `spend_desc` / `spend_asc` order by aggregated spend in the requested date range; campaigns with no spend land at the end." }
-        - { name: timeIncrement, in: query, schema: { type: integer, enum: [1] }, description: "Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`. See `dailyLevel` to control which levels carry it." }
+        - { name: timeIncrement, in: query, schema: { type: integer, enum: [1] }, description: "Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`, except Meta `reach`: the range total is Meta's de-duplicated value, so daily reach does not sum to it. See `dailyLevel` to control which levels carry it." }
         - { name: dailyLevel, in: query, schema: { type: string, enum: [campaign, adset, ad], default: campaign }, description: "Which tree levels get the `daily[]` series when `timeIncrement=1`. `campaign` (default) attaches it on campaign nodes only — the common per-campaign-trend case, and the smallest payload. `adset` adds it on ad sets too; `ad` adds it on every ad in `ads[]` as well (heaviest — a long range × up to 100 ads per ad set). Scope with `campaignId` to keep `ad`-level responses small. Ignored when `timeIncrement` is unset." }
       responses:
         '200':
@@ -35840,7 +35992,7 @@ paths:
                         date: { type: string, format: date }
                         spend: { type: number, description: "Native currency units (matches /ads/tree convention)." }
                         impressions: { type: integer }
-                        reach: { type: integer }
+                        reach: { type: integer, description: "Reach summed across the account's ads for this single day. A person seen by two ads the same day counts twice, and reach is de-duplicated per day only: do NOT sum it across days (people reached on multiple days would be double-counted)." }
                         clicks: { type: integer }
                         engagement: { type: integer }
                         ctr: { type: number, description: "Click-through rate as a percentage (0–100)." }

data/spec/api/ad_campaigns_api_spec.rb

@@ -192,7 +192,7 @@ describe 'AdCampaignsApi' do
   # @option opts [Date] :from_date Start of the METRICS date range (YYYY-MM-DD). Affects only the spend/impression numbers overlaid on each node, NOT which campaigns are returned. Defaults to 90 days ago.
   # @option opts [Date] :to_date End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.
   # @option opts [String] :sort Campaign-level sort order. `newest` (default) / `oldest` order by the campaign's newest-ad createdAt. `spend_desc` / `spend_asc` order by aggregated spend in the requested date range; campaigns with no spend land at the end.
-  # @option opts [Integer] :time_increment Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`. See `dailyLevel` to control which levels carry it.
+  # @option opts [Integer] :time_increment Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`, except Meta `reach`: the range total is Meta's de-duplicated value, so daily reach does not sum to it. See `dailyLevel` to control which levels carry it.
   # @option opts [String] :daily_level Which tree levels get the `daily[]` series when `timeIncrement=1`. `campaign` (default) attaches it on campaign nodes only — the common per-campaign-trend case, and the smallest payload. `adset` adds it on ad sets too; `ad` adds it on every ad in `ads[]` as well (heaviest — a long range × up to 100 ads per ad set). Scope with `campaignId` to keep `ad`-level responses small. Ignored when `timeIncrement` is unset.
   # @return [GetAdTree200Response]
   describe 'get_ad_tree test' do