Adding support to WhatsApp events on Business SDK

Summary:
CAPI CTWA has been launched to 100% since November 2023, but is still not supported in our Meta Business SDK.

This diff adds support for WhatsApp events on the Business SDK. It includes changes to the Event class to add a new field for the messaging channel, as well as changes to the User Data class to include new constants for the CTWA_CLID and PAGE_ID parameters.

Reviewed By: stcheng

Differential Revision: D54615825

fbshipit-source-id: 67edbe7b4101f3ea571d3d583e585d863ab0ca65

src/FacebookAds/Object/ServerSide/ActionSource.php

@@ -70,6 +70,11 @@ class ActionSource extends AbstractEnum {
    */
   const SYSTEM_GENERATED = 'system_generated';
 
+  /**
+   * Conversion happened through a business messaging channel, such as WhatsApp or Instagram Direct.
+   */
+  const BUSINESS_MESSAGING = 'business_messaging';
+
   /**
    * Conversion happened in a way that is not listed.
    */

src/FacebookAds/Object/ServerSide/Event.php

@@ -51,6 +51,7 @@ class Event implements ArrayAccess {
     'action_source' => 'string',
     'app_data' => 'FacebookAds\Object\ServerSide\AppData',
     'advanced_measurement_table' => 'string',
+    'messaging_channel' => 'string',
   );
   /**
    * Array of attributes where the key is the local name, and the value is the original name
@@ -70,6 +71,7 @@ class Event implements ArrayAccess {
     'action_source' => 'action_source',
     'app_data' => 'app_data',
     'advanced_measurement_table' => 'advanced_measurement_table',
+    'messaging_channel' => 'messaging_channel',
   );
 
   /**
@@ -90,6 +92,7 @@ class Event implements ArrayAccess {
     'action_source' => 'setActionSource',
     'app_data' => 'setAppData',
     'advanced_measurement_table' => 'setAdvancedMeasurementTable',
+    'messaging_channel' => 'setMessagingChannel',
   );
   /**
    * Array of attributes to getter functions (for serialization of requests)
@@ -109,6 +112,7 @@ class Event implements ArrayAccess {
     'action_source' => 'getActionSource',
     'app_data' => 'getAppData',
     'advanced_measurement_table' => 'getAdvancedMeasurementTable',
+    'messaging_channel' => 'getMessagingChannel',
   );
   /**
    * Associative array for storing property values
@@ -134,6 +138,7 @@ public function __construct(array $data = null) {
     $this->container['action_source'] = isset($data['action_source']) ? $data['action_source'] : null;
     $this->container['app_data'] = isset($data['app_data']) ? $data['app_data'] : null;
     $this->container['advanced_measurement_table'] = isset($data['advanced_measurement_table']) ? $data['advanced_measurement_table'] : null;
+    $this->container['messaging_channel'] = isset($data['messaging_channel']) ? $data['messaging_channel'] : null;
   }
 
   public static function paramTypes() {
@@ -402,6 +407,7 @@ public function normalize() {
       $this->container['action_source']
     );
     $normalized_payload['advanced_measurement_table'] = $this->getAdvancedMeasurementTable();
+    $normalized_payload['messaging_channel'] = $this->getMessagingChannel();
     $normalized_payload = array_filter($normalized_payload, function($val) { if(is_array($val)) { return true; } else { return strlen((string) $val); }});
     // Add the opt_out value back in if it was filtered out
     if ($this->getOptOut() === false) {
@@ -518,6 +524,23 @@ public function getAdvancedMeasurementTable() {
     return $this->container['advanced_measurement_table'];
   }
 
+  /**
+   * Sets the messaging channel of the event.
+   * @return $this
+   */
+  public function setMessagingChannel($messaging_channel) {
+    $this->container['messaging_channel'] = $messaging_channel;
+    return $this;
+  }
+
+  /**
+   * Return the messaging channel of the event.
+   * @return string
+   */
+  public function getMessagingChannel() {
+    return $this->container['messaging_channel'];
+  }
+
   /**
    * Gets the string representation of the object
    * @return string

src/FacebookAds/Object/ServerSide/MessagingChannel.php

@@ -0,0 +1,42 @@
+<?php
+/**
+ * Copyright (c) 2015-present, Facebook, Inc. All rights reserved.
+ *
+ * You are hereby granted a non-exclusive, worldwide, royalty-free license to
+ * use, copy, modify, and distribute this software in source code or binary
+ * form for use in connection with the web services and APIs provided by
+ * Facebook.
+ *
+ * As with any software that integrates with the Facebook platform, your use
+ * of this software is subject to the Facebook Developer Principles and
+ * Policies [http://developers.facebook.com/policy/]. This copyright notice
+ * shall be included in all copies or substantial portions of the software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ *
+ */
+
+namespace FacebookAds\Object\ServerSide;
+
+use FacebookAds\Enum\AbstractEnum;
+
+/**
+ * Class ActionSource
+ *
+ * Where the conversion event occurred.
+ *
+ * @package FacebookAds\Object\ServerSide
+ */
+class MessagingChannel extends AbstractEnum {
+
+  /**
+   *  Conversion happened on WhatsApp.
+   */
+  const WHATSAPP = 'whatsapp';
+}

src/FacebookAds/Object/ServerSide/UserData.php

@@ -86,7 +86,9 @@ class UserData implements ArrayAccess {
     'dobm' => 'string',
     'doby' => 'string',
     'madid' => 'string',
-    'anon_id' => 'string'
+    'anon_id' => 'string',
+    'ctwa_clid' => 'string',
+    'page_id' => 'string'
   );
   /**
    * Array of attributes where the key is the local name, and the value is the original name
@@ -129,7 +131,9 @@ class UserData implements ArrayAccess {
     'dobm' => 'dobm',
     'doby' => 'doby',
     'madid' => 'madid',
-    'anon_id' => 'anon_id'
+    'anon_id' => 'anon_id',
+    'ctwa_clid' => 'ctwa_clid',
+    'page_id' => 'page_id'
   );
   /**
    * Array of attributes to setter functions (for deserialization of responses)
@@ -172,7 +176,9 @@ class UserData implements ArrayAccess {
     'dobm' => 'setDobm',
     'doby' => 'setDoby',
     'madid' => 'setMadid',
-    'anon_id' => 'setAnonId'
+    'anon_id' => 'setAnonId',
+    'ctwa_clid' => 'setCtwaClid',
+    'page_id' => 'setPageId'
   );
   /**
    * Array of attributes to getter functions (for serialization of requests)
@@ -215,7 +221,9 @@ class UserData implements ArrayAccess {
     'dobm' => 'getDobm',
     'doby' => 'getDoby',
     'madid' => 'getMadid',
-    'anon_id' => 'getAnonId'
+    'anon_id' => 'getAnonId',
+    'ctwa_clid' => 'getCtwaClid',
+    'page_id' => 'getPageId'
   );
   /**
    * Associative array for storing property values
@@ -336,6 +344,8 @@ public function __construct(array $data = null) {
     $this->container['doby'] = isset($data['doby']) ? $data['doby'] : null;
     $this->container['madid'] = isset($data['madid']) ? $data['madid'] : null;
     $this->container['anon_id'] = isset($data['anon_id']) ? $data['anon_id'] : null;
+    $this->container['ctwa_clid'] = isset($data['ctwa_clid']) ? $data['ctwa_clid'] : null;
+    $this->container['page_id'] = isset($data['page_id']) ? $data['page_id'] : null;
 
 
   }
@@ -853,6 +863,30 @@ public function setAnonId($anon_id) {
     return $this;
   }
 
+  /**
+   * CtwaClid of the conversation that was started on WhatsApp
+   *
+   * @param ctwa_clid the anonymous id
+   * @return $this
+   */
+  public function setCtwaClid($ctwa_clid) {
+    $this->container['ctwa_clid'] = $ctwa_clid;
+
+    return $this;
+  }
+
+  /**
+   * Set the ID of the page that the ad is associated with
+   *
+   * @param page_id
+   * @return $this
+   */
+  public function setPageId($page_id) {
+    $this->container['page_id'] = $page_id;
+
+    return $this;
+  }
+
   /**
    * Returns true if offset exists. False otherwise.
    * @param integer $offset Offset
@@ -923,6 +957,8 @@ public function normalize() {
     $normalized_payload['doby'] = Util::hash(Normalizer::normalize('doby', $this->getDoby()));
     $normalized_payload['madid'] = Util::hash(Normalizer::normalize('madid', $this->getMadid()));
     $normalized_payload['anon_id'] = Util::hash(Normalizer::normalize('anon_id', $this->getAnonId()));
+    $normalized_payload['ctwa_clid'] = $this->getCtwaClid();
+    $normalized_payload['page_id'] = $this->getPageId();
     $normalized_payload = array_filter($normalized_payload);
     return $normalized_payload;
   }
@@ -1252,6 +1288,22 @@ public function getAnonId() {
     return $this->container['anon_id'];
   }
 
+  /**
+   * CtwaClid of the conversation that was started on WhatsApp
+   * @return string
+   */
+  public function getCtwaClid() {
+    return $this->container['ctwa_clid'];
+  }
+
+  /**
+   * ID of the page that the ad is associated with
+   * @return string
+   */
+  public function getPageId() {
+    return $this->container['page_id'];
+  }
+
   /**
    * Gets the string presentation of the object
    * @return string