[PR-23265][Custom app] Create public documentation (#349)

source/email_marketing_and_automation/attentive.rst

@@ -95,7 +95,7 @@ instruct how to find all necessary credentials.
 5. Test the app by pressing on the “Send sample payload” and then check if you are seeing a test request inside your ESP:
 
   .. image:: /_static/img/email_marketing_and_automation/attentive_send_sample.png
-    :alt: Send same payload
+    :alt: Attentive send sample
 
 **Contact us**
 

source/email_marketing_and_automation/custom_app.rst

@@ -2,14 +2,32 @@
 .. include:: /partials/common.rst
 
 .. meta::
-  :description: Custom App allows you to send Talkable data to a desired destination such as your site, ESP, CDP.
+   :description: Custom App allows you to send Talkable data to a desired destination such as your site, ESP, CDP.
 
 Custom App
 ==========
 
 Custom App allows you to send Talkable data to a desired destination such as your site, ESP, CDP.
 Talkable will send a request with data to the Custom App URL for each customer's event specified in the Custom App settings.
 
+Set Up
+------
+
+1. Navigate to the App store:
+
+   .. image:: /_static/img/email_marketing_and_automation/app_store_step_1.png
+      :alt: App store step 1
+
+   .. image:: /_static/img/email_marketing_and_automation/app_store_step_2.png
+      :alt: App store step 2
+
+2. Choose a `Custom app` and click “Install”
+3. Fill in `Endpoint URL` and `App name` fields, and enable the required actions.
+4. Complete installation and enable the app:
+
+   .. image:: /_static/img/email_marketing_and_automation/custom_app.png
+      :alt: Custom App
+
 Webhook Signature Verification
 ------------------------------
 
@@ -32,14 +50,14 @@ To verify the signature, you should complete the following steps:
 Your Talkable **Webhook security key** can be found in the Webhook set up page by navigating to **Menu** then **Webhooks**.
 
 .. image:: /_static/img/menu_webhooks_screenshot.png
- :alt: Webhooks Menu Item
+   :alt: Webhooks Menu Item
 
 .. raw:: html
 
-  <hr>
+   <hr>
 
 .. image:: /_static/img/webhook_secret_key.png
-    :alt: Webhook Security Key
+   :alt: Webhook Security Key
 
 **3. Compare the signatures**
 
@@ -51,35 +69,276 @@ Your Talkable **Webhook security key** can be found in the Webhook set up page b
 
 .. code-block:: ruby
 
-    require 'base64'
-    require 'openssl'
-    require 'active_support/security_utils'
+   require 'base64'
+   require 'openssl'
+   require 'active_support/security_utils'
 
-    WEBHOOK_SECRET_KEY = 'my_webhook_secret'
+   WEBHOOK_SECRET_KEY = 'my_webhook_secret'
 
-    def verify_webhook(data, header_signature)
-      calculated_signature = Base64.strict_encode64(OpenSSL::HMAC.hexdigest('sha256', WEBHOOK_SECRET_KEY, data))
-      ActiveSupport::SecurityUtils.secure_compare(calculated_signature, header_signature)
-    end
+   def verify_webhook(data, header_signature)
+     calculated_signature = Base64.strict_encode64(OpenSSL::HMAC.hexdigest('sha256', WEBHOOK_SECRET_KEY, data))
+     ActiveSupport::SecurityUtils.secure_compare(calculated_signature, header_signature)
+   end
 
 *JavaScript:*
 
 .. code-block:: javascript
 
-    const crypto = require('crypto');
+   const crypto = require('crypto');
+
+   const WEBHOOK_SECRET_KEY = 'my_webhook_secret';
+
+   function verifyWebhook(data, headerSignature) {
+     // Calculate HMAC
+     const calculatedSignature = btoa(crypto
+       .createHmac('sha256', WEBHOOK_SECRET_KEY)
+       .update(data)
+       .digest('hex')
+     );
+
+     return crypto.timingSafeEqual(
+       Buffer.from(calculatedSignature, 'base64'),
+       Buffer.from(headerSignature, 'base64')
+     );
+   }
+
+Available actions
+-----------------
+
+Each action allows custom attributes to be included. You can see allowed interpolation variables by clicking `Show available variables` button:
+
+.. image:: /_static/img/email_marketing_and_automation/variables.png
+   :alt: Variables
+
+Referral Create
+...............
+
+Triggers when a new referral is created, sending detailed information about the referral.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "campaign_id": "142",
+     "referral_status": "in_progress",
+     "advocate_email": "[email protected]",
+     "friend_email": "[email protected]"
+   }
+
+Sync signups
+............
+
+This action automatically synchronizes all people whenever they sign up no matter if person opted in by email or phone number.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "email": "[email protected]",
+     "email_optin": "true",
+     "phone_number": "+12025551111",
+     "phone_optin": "true"
+   }
+
+Sync email opt-ins
+..................
+
+This action automatically synchronizes all people whenever they sign up and opt in. Email signups without opt-in are not triggered by this action.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "email": "[email protected]",
+     "email_optin": "true"
+   }
+
+Sync phone opt-ins
+..................
+
+This action automatically synchronizes all people whenever they sign up and opt in for text messages. Signups without phone opt in are not triggered by this action.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "email": "[email protected]",
+     "phone_number": "+12025551111"
+   }
+
+Sync loyalty actions
+....................
+
+This action automatically synchronizes all loyalty members whenever they make a loyalty action.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "email": "[email protected]"
+   }
+
+Sync loyalty tier transitions
+.............................
+
+This action automatically synchronizes all loyalty members whenever their tier is changed.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "email": "[email protected]"
+   }
+
+Unsubscribe
+...........
+
+Whenever customers unsubscribe from Talkable emails they will also become unsubscribed in your ESP.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "email": "[email protected]"
+   }
+
+Offer share
+...........
+
+Whenever a person shares the offer, the share information will be sent to your ESP.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "email": "[email protected]"
+   }
+
+Send reward
+...........
+
+This action sends the reward information to your ESP.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "description": "$5",
+     "amount": "5.0",
+     "coupon_code": "FR_NEW_5_OFF",
+     "reason": "click",
+     "site_id": "1"
+   }
+
+Create coupon
+.............
+
+When the quantity of available coupons drops below a Talkable threshold this action sends you information.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "coupon_code": "SAMPLE-COUPON-CODE",
+     "coupon_discount_amount": "0.0"
+   }
+
+Event
+.....
+
+Triggers when a new event or purchase is created.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "type": "Event",
+     "created_at": "2024-11-25 00:00:00 -0800",
+     "event_category": "public_event",
+     "event_number": "183247241",
+     "subtotal": "100.0",
+     "currency_iso_code": "USD",
+     "email": "[email protected]"
+   }
+
+Referral status change
+......................
+
+This action is triggered when referral’s status changes.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "site_id": "1",
+     "campaign_id": "142",
+     "referral_status": "in_progress",
+     "advocate_email": "[email protected]",
+     "friend_email": "[email protected]"
+   }
+
+Click reward verification
+.........................
+
+This action sends information about a Friend when they attempt claiming a reward. The response from the Endpoint URL is checked to decide if a reward should be given. To reject unverified rewards, use `click_reward_verified` liquid variable in the incentive criteria.
+
+**Note:** By default, the verification request times out at 1 second, and in that case the reward is considered verified.
+
+*Default payload:*
+
+.. code-block:: JSON
+
+   {
+     "email": "[email protected]",
+     "site_id": "1"
+   }
+
+
+Testing
+-------
+
+Testing Custom app actions can be accomplished with the help of Webhook Tester, an external service that tests your post-receive messages.
+
+1. Visit `Webhook Tester <https://webhook.site/>`_ and click **Copy** to copy the URL you are given.
+2. Open your Custom app.
+3. Paste your Webhook Tester URL into **Endpoint URL** field and save.
+4. Click **Send sample payload** near the action you want to test.
+
+   .. image:: /_static/img/email_marketing_and_automation/send_sample_payload.png
+      :alt: Send sample payload
+
+5. After you finish the implementation on your site **change Webhook Tester URL
+   to the live URL** in your Custom app.
+6. Click **Send sample payload** to test action with Live URL.
+
+Whitelisting Talkable IPs
+-------------------------
 
-    const WEBHOOK_SECRET_KEY = 'my_webhook_secret';
+In case your servers are behind firewall, you may need to whitelist Talkable IP
+addresses so webhooks can be delivered. Pass list of these addresses to your network administrator:
 
-    function verifyWebhook(data, headerSignature) {
-        // Calculate HMAC
-        const calculatedSignature = btoa(crypto
-            .createHmac('sha256', WEBHOOK_SECRET_KEY)
-            .update(data)
-            .digest('hex')
-        );
+.. hlist::
+   :columns: 4
 
-        return crypto.timingSafeEqual(
-            Buffer.from(calculatedSignature, 'base64'),
-            Buffer.from(headerSignature, 'base64')
-        );
-    }
+   .. include:: /partials/talkable_ip_list.rst

source/email_marketing_and_automation/hubspot.rst

@@ -52,8 +52,8 @@ Please use the following guide to start using an app you need:
 
 5. Test the app by pressing on the “Send sample payload” and then check if you are seeing a test request inside your ESP:
 
-  .. image:: /_static/img/email_marketing_and_automation/send_same_payload.png
-    :alt: Send same payload
+  .. image:: /_static/img/email_marketing_and_automation/send_sample_payload.png
+    :alt: Send sample payload
 
 **Contact us**
 

source/email_marketing_and_automation/klaviyo.rst

@@ -52,8 +52,8 @@ Please use the following guide to start using an app you need:
 
 5. Test the app by pressing on the “Send sample payload” and then check if you are seeing a test request inside your ESP:
 
-  .. image:: /_static/img/email_marketing_and_automation/send_same_payload.png
-    :alt: Send same payload
+  .. image:: /_static/img/email_marketing_and_automation/send_sample_payload.png
+    :alt: Send sample payload
 
 **Contact us**
 

source/email_marketing_and_automation/mailchimp.rst

@@ -52,8 +52,8 @@ Please use the following guide to start using an app you need:
 
 5. Test the app by pressing on the “Send sample payload” and then check if you are seeing a test request inside your ESP:
 
-  .. image:: /_static/img/email_marketing_and_automation/send_same_payload.png
-    :alt: Send same payload
+  .. image:: /_static/img/email_marketing_and_automation/send_sample_payload.png
+    :alt: Send sample payload
 
 **Contact us**