Sample Title
``` --- ## add_time Add a specified amount of time to a date and return the result. Time unit defaults to seconds. Available time units (can be used in plural form as well): * `second` * `minute` * `hour` * `day` * `week` * `fortnight` * `month` * `year` ```liquid {{ valid_until | add_time: 42 }} {{ valid_until | add_time: 3, 'months' }} ``` --- ## adjust_color Returns a new adjusted color based on the following attributes: * red — changes only the Red color channel saturation. Allowed values: -255-255. * green — changes only the Green color channel saturation. Allowed values: -255-255. * blue — changes only the Blue color channel saturation. Allowed values: -255-255. * hue — changes the hue of a color. Allowed values: 0-360. * saturation — changes the saturation of a color. Allowed values: -100-100. * lightness — changes the lightness of a color. Allowed values: -100-100. * alpha — changes the opacity of a color. Allowed values: -1-1. ```liquid {{ "red" | adjust_color: blue: 255 }} {{ "#000000" | adjust_color: alpha: -0.5 }} ``` --- ## append_to_array Appends elements to an existing array. Liquid ```liquid {% assign my_array = "" | new_array %} {% assign my_array = my_array | append_to_array: "element1", "element2" %} Array: {{ my_array | json }} ``` Rendered Liquid ```text Array: ["element1","element2"] ``` --- ## asset_url Inserts link for an uploaded asset. ```liquid {{ "image.jpg" | asset_url }} ``` Example: [http://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/745/original/offer-background.jpg](http://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/745/original/offer-background.jpg) --- ## assign_key Assigns a key-value pair to an existing hash. If the key already exists, its value is updated. Liquid ```liquid {% assign my_hash = "" | new_hash: key: "value", key2: 42 %} {% assign my_hash = my_hash | assign_key: "key2", "value2" %} {% assign my_hash = my_hash | assign_key: "key3", "value3" %} Hash: {{ my_hash | json }} ``` Rendered Liquid ```text Hash: {"key":"value","key2":"value2","key3":"value3"} ``` --- ## async_rendering Stores Liquid partial that can be later rendered via `Talkable.loadLiquid` function. ### Example 1 Liquid ```liquid {{ "async_advocate_info" | async_rendering: 'template for rendering with data [[ advocate_info.email ]]' }} ``` JavaScript API call ```javascript Talkable.loadLiquid("async_advocate_info", function(rendered_template) { console.log(rendered_template); }); ``` Rendered Liquid ```text "template for rendering with data advocate@example.com" ``` ### Example 2 Liquid ```liquid {{ 'async_dashboard_data' | async_rendering: some_key: "[[ dashboard.possible_rewards | money: strip_insignificant_zeros: true ]]", other_key: "[[ friend_info.purchases_count ]]" }} ``` JavaScript API call ```javascript Talkable.loadLiquid("async_dashboard_data", function(rendered_data) { console.log(rendered_data.some_key); }); ``` Rendered Liquid ```text "$420" ``` ### Example 3 Liquid ```liquid {% capture some_liquid_block %} {% raw %} Whatever Liquid you would like to have {% endraw %} {% endcapture %} {{ 'async_liquid_reference' | async_rendering: some_liquid_block }} ``` JavaScript API call ```javascript Talkable.loadLiquid("async_liquid_reference", function(rendered_template) { console.log(rendered_template); }); ``` Rendered Liquid ```text "Whatever Liquid you would like to have" ``` ### Example 4 Use `json` Liquid filter to transform deeply nested object structure into a valid JSON. Liquid ```liquid {{ 'async_advocate_info' | async_rendering: '[[ advocate_info | json ]]' }} ``` JavaScript API call ```javascript Talkable.loadLiquid("async_advocate_info", function(rendered_template) { console.log(JSON.parse(rendered_template)); }); ``` Rendered Liquid ```javascript { "first_name": null, "last_name": null, "email": "advocate@example.com", "username": null, "external_customer_id": null, "opted_in_at": null, "sub_choice": false, "purchases_sum": 0.0, "purchases_count": 0, "events_count": 0, "events_count_by_category": { "friend_signup": 0, "purchase": 0 }, "referrals_count": 0, "referred_by": null, "custom_properties": {}, "unsubscribed": false } ``` --- ## attachment_cid Returns a content ID (CID) of an attached file that can be used to embed files in emails. ```liquid {% assign qr_code = 'X' | qr_code: format: 'png' %}
```
---
## barcode
Represents any `string` as an array of boolean values: `[true, false]` in order to convert it into a barcode.
This filter strictly follows GS1-128 specification: [https://en.wikipedia.org/wiki/GS1-128](https://en.wikipedia.org/wiki/GS1-128).
```liquid
{% assign barcode = "X" | barcode %}
```
**Here is an example how to convert a coupon code into a barcode:**
HTML:
```liquid
| {% endfor %} |
{{ coupon.code | qr_code: xdim: 6 }}
```
To return a QR code as a PNG that can be embedded in email body as an attachment, use the custom format:
```liquid
{{ coupon.code | qr_code: format: 'png' }}
```
---
## rand_by
Produces a random value which is always the same for specific parameters passed.
First parameter is a maximum random number.
Simple example:
```liquid
{{ "100" | rand_by: "param1", "param2" }}
```
Always returns `29`.
Interpolation as a parameter:
```liquid
{{ "10" | rand_by: advocate_info.email }}
```
Always returns the same number for a specific email, between 0 and 9.
---
## regexp_captures
Parses input with a given regexp and returning [regular expression captures](https://www.regular-expressions.info/brackets.html) as an array.
```liquid
{{ '12345678' | regexp_captures: '(....)(....)' | join: '-' }}
{{ 'bogdan@example.com' | regexp_captures: '^([a-z]+)\@([a-z]+)\.([a-z]+)' | json }}
```
---
## rybbon
Takes a campaign key of a BHN Rewards (formerly Rybbon) Talkable campaign.
Makes a claim request within the scope of the given campaign and returns a gift claim link.
Requires BHN Rewards (formerly Rybbon) app to be installed and enabled in order to work.
```liquid
{{ "a9a3472f4ea858758e0cd686de8408e2" | rybbon }}
```
Returns `https://www.rybbon.net/redeem.php?claimcode=ee645de47765bdbede751c8c6f08a619`
Accepts custom amount of reward for BHN Rewards (formerly Rybbon) campaigns with variable denomination. The minimum amount conforms to each specific Rybbon gift card restrictions. The maximum amount is 50.
```liquid
{{ "a9a3472f4ea858758e0cd686de8408e2" | rybbon: amount: 13.5 }}
```
Find more details about the integration here: [BHN Rewards (formerly Rybbon)](https://docs.talkable.com/advanced_features/bhnrewards.md#advanced-features-bhnrewards)
---
## save_wallet
Validates and caches the wallet template. This filter should be used on “Talkable wallet for iphone”
and “Talkable wallet for android” pages, passing a hash object with the wallet template. Optionally,
you can pass a card type to the filter. Currently, only `Wallets::ReferralCard` (default, used for Apple)
and `Wallets::GoogleReferralCard` (for Android) are supported.
Example for Apple Wallet:
```liquid
{% assign wallet = "" | new_hash %}
{% assign wallet = wallet | assign_key: "barcodes", apple_wallet_barcodes %}
{% assign wallet = wallet | assign_key: "header_fields", apple_wallet_header_fields %}
{{ wallet | save_wallet }}
```
Example for Android Wallet:
```liquid
{% assign wallet = "" | new_hash %}
{% assign wallet = wallet | assign_key: "barcode", google_wallet_barcode %}
{% assign wallet = wallet | assign_key: "primary_fields", google_wallet_primary_fields %}
{{ wallet | save_wallet: card_type: 'Wallets::GoogleReferralCard' }}
```
Required and allowed fields for each card type should be checked in the respective documentation:
* [Apple Wallet](https://developer.apple.com/documentation/walletpasses/pass)
* [Google Wallet](https://developers.google.com/wallet/generic/overview/how-classes-objects-work#objects)
## scale_color
Returns a new adjusted color with scaled attributes.
Available attributes: red, green, blue, saturation, lightness, alpha
```text
{{ "black" | scale_color: lightness: 50 }}
{{ "rgb(256, 128, 0)" | scale_color: saturation: -10 }}
```
---
## simple_format
Formats plain text to have HTML formatting. E.g. replace `\n` with ``. ```text {{ "Hello [[advocate_info.email]]\nHere is your reward." | simple_format | interpolate }} ``` Returns `Hello John
Here is your reward`. --- ## sort Sort an array. Optional arguments for hashes: 1. property name 2. nils order (first or last). ```liquid {{ campaign_tags | sort }} {{ incentives | sort: "amount" }} {{ incentives | sort: "amount", "first" }} ``` --- ## squish Returns the string, first removing all whitespace on both ends of the string, and then changing remaining consecutive whitespace groups into one space each. ```text {{ " foo bar baz " | squish }} ``` Returns `foo bar baz`. --- ## strip Removes leading and trailing blank symbols from the string. ```text {{ " strip me " | strip }} ``` Returns `strip me`. --- ## tango Takes the ID (UTID) of a Tango reward. Places an order for the specified reward and returns a gift claim link. Requires the Tango app to be installed and enabled in order to work. ```liquid {{ "U957978" | tango: amount: 10.0 }} ``` Returns `https://rewardlink.io/r/1/reward123` Find more details about the integration here: [Tango](https://docs.talkable.com/advanced_features/tango.md#advanced-features-tango) --- ## track_link_click This filter generates a public link that can be used to track wallet link clicks. ```liquid {{ "https://example.com" | track_link_click: "query_42" }} ``` Returns `https://talkable.com/public/[[site_slug]]/[[campaign_id]]/wallet_link_clicks/track?identifier=query_42`. After a click, the user will be redirected to the original link (`https://example.com`). --- ## tremendous Takes a campaign key of a Tremendous campaign. Makes a claim request within the scope of the given campaign and returns a gift claim link. Requires Tremendous app to be installed and enabled in order to work. Implies that there is only one funding source in the Tremendous account. ```liquid {{ "DEM8ULSSATK0" | tremendous }} ``` Returns `https://www.tremendous.com/rewards/payout/reward123` Find more details about the integration here: [Tremendous](https://docs.talkable.com/advanced_features/tremendous.md#advanced-features-tremendous) --- ## tweet_length Calculates a tweet length for the string. ```text {{ "wow this is a tweet http://example.com" | tweet_length }} ``` Returns `43`. --- ## update_query Updates query parameters in a URL. ```liquid {{ "http://example.com/?a=b&utm_source=foo" | update_query: utm_campaign: "Campaign Name", utm_source: "talkable" }} ``` Returns `http://example.com/?a=b&utm_campaign=Campaign%20Name&utm_source=talkable`. --- ## url2png Captures a snapshot of a website URL you pass to it. In case you need to embed a snapshot of your website into Talkable campaign it is way better to use this liquid filter instead of embedding an iframe since an image is always lighter in size and takes less CPU performance to render on a screen. Also, some websites restrict themselves from embedding through an iframe so you can take `url2png` as a bulletproof solution for a website snapshot. Available options: * `ttl` - “time to live” period for a screenshot before it gets refreshed, in seconds. Value example: `86400`. * `viewport` - Viewport dimensions. Value example: `"640x480"`. * `custom_css_url` - Custom CSS file that will be injected into a website in case you need to change a screenshot. Value example: `"http://url2png.com/tests/css/test.css"`. * `fullpage` - Attempts to capture entire document canvas. Value example: `true`. Here is how you can embed a screenshot of your website into a campaign view (`site_url` returns your website URL that you set inside Site Settings): ```liquid
{{ site.title }}
First element
{{ coupon_code }}
Shop using this code
{% else %}
{{ coupon_code }}
Shop using this code
{% else %}
18.207.91.200
18.210.165.17
18.232.203.127
18.233.48.151
184.73.206.68
23.21.155.129 | 3.222.226.72
34.197.54.191
34.226.253.236
34.231.104.179
34.232.247.192
35.169.186.170
35.171.77.58 | 35.173.87.187
44.217.136.252
44.219.211.174
50.16.143.102
50.17.244.178
52.204.148.18
52.22.0.55 | 52.6.41.1
52.7.94.243
54.164.128.44
54.208.14.192
54.86.208.153
54.86.241.218
54.91.51.228 | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | Source: https://docs.talkable.com/email_marketing_and_automation/dotdigital.md =============================================================================== # Dotdigital With the Dotdigital app, clients can synchronize emails and phone numbers that Talkable acquires with their Dotdigital platform. The integration supports: * Email opt-ins from advocates and friends * Phone number opt-ins for SMS marketing * Email unsubscribe management Here are the conditions when Talkable acquires emails and phone numbers: 1. Advocate signs up and opts in for Talkable marketing emails: [[Image]](https://docs.talkable.com/_images/signup_advocate.png.md) 2. A friend passes email gating and opts in for Talkable marketing emails: [[Image]](https://docs.talkable.com/_images/signup_friend.png.md) 3. Phone numbers are captured when users opt in for SMS communications during the referral process. 4. Email unsubscribes are automatically synchronized to ensure compliance with email preferences. ## How to add a new app? Please use the following guide to start using the Dotdigital app: 1. Navigate into the App store: [[Image]](https://docs.talkable.com/_images/app_store_step_1.png.md) [[Image]](https://docs.talkable.com/_images/app_store_step_2.png.md) 2. Choose the Dotdigital app by clicking “Install” 3. Fill in all necessary fields. You can use tips on the right that instruct how to find all necessary credentials from your Dotdigital account: * API User Email * API User Password > **Note:** > > Regional API Endpoint will be filled by Talkable automatically, so it can be left blank. > **Important:** > > When creating an API user, make sure to select “Tiered” for the Rate limiting option. 4. Complete installation and enable the app: [Image] Dotdigital application allows data fields to be included with each contact import. By default, Talkable sets the following data fields: * `FIRSTNAME` * `LASTNAME` You can add custom data fields by modifying the payload of an app action. [[Image]](https://docs.talkable.com/_images/dotdigital_payload.png.md) Talkable will add a prefix to each custom data field name ```JSON { "FAVORITE_COLOR": "{{ person.custom_properties.favorite_color }}", // Data field as defined in the payload "TKBL_FAVORITE_COLOR": "{{ person.custom_properties.favorite_color }}", // Data field sent to Dotdigital } ``` ## About Dotdigital Dotdigital is a leading customer experience and data platform that helps marketing teams create personalized campaigns across email, SMS, social media, and other channels. With powerful automation tools and comprehensive analytics, Dotdigital enables brands to build lasting customer relationships and drive revenue growth. For more information about Dotdigital’s features and capabilities, visit [dotdigital.com](https://dotdigital.com/). ## Contact us Interested in setting this up? Contact your CSM or get in touch [here](https://www.talkable.com/lets-talk-referral). Source: https://docs.talkable.com/email_marketing_and_automation/emarsys.md =============================================================================== # Emarsys Talkable syncs referral opt-ins and contact data into Emarsys — an omnichannel customer engagement platform — so every Advocate and Friend who opts in during a campaign flows into your marketing in real time. ## What this integration does Talkable turns referral sign-ups into enriched, segmentable contacts in your ESP — automatically. The integration: * **Syncs referral opt-ins** — every Advocate and Friend who opts in during a Talkable campaign is sent to your ESP as a contact create-or-update, so referral sign-ups grow your marketable audience in real time. * **Targets the right list or audience** — each contact is added to the specific list, audience, or subscription group you choose, so referred customers drop straight into the right welcome series, nurture flow, or segment. * **Enriches contacts with referral data** — map Talkable data such as referral and share counts, advocate status, and campaign details to your ESP’s fields through interpolation variables, powering referral-based segmentation, triggers, and personalization. ## When opt-ins are synced An opt-in can happen at two points in a referral — the Advocate’s and the Friend’s — and Talkable syncs each one to your ESP the instant it happens, so no opted-in contact is missed or left for a manual export. Here is where that fits in the referral journey: 1. **Advocate opts in.** A customer enters a Talkable campaign (post-purchase, standalone, floating widget, and so on) and opts in for marketing communications. 2. **Advocate synced** → Talkable sends the advocate’s contact details and opt-in status to your ESP. 3. **Advocate shares the offer.** They share by email, social, SMS, or a unique link. 4. **Friend opts in.** A friend follows the referral link, enters the campaign, and opts in to claim the offer. 5. **Friend synced** → Talkable sends the friend’s contact details and opt-in status to your ESP. ## Segmentation use cases With referral data flowing into your ESP, you can: * Build a segment of active advocates (people with one or more successful referrals) for VIP or loyalty campaigns. * Trigger a welcome series for friends acquired through a referral. * Re-engage advocates who have not shared recently. * Personalize messages with relational details — the person’s name and who referred them — so referral emails feel personal, not like another generic promo. ## Available data points You can attach a wide range of Talkable referral data to each contact you sync. The exact variable names are shown in the product when you configure the integration; at a glance, the data available includes: | Data | What’s included | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Contact details | Email, phone number, and name | | Opt-in status | Email and SMS opt-in state, and when each opt-in happened | | Person profile | Advocate and loyalty status, when and where they signed up (including location), and any custom properties you pass from your store | | Referral activity | Referrals made (total, approved, and pending), shares made, and who referred them — by name and email | | Rewards | The coupon code and reward value the person earned | | Campaign | Campaign name, type, tags, and whether it’s active | ## Sample payload Here is what a referral opt-in looks like when Talkable syncs it to Emarsys — referral data maps to your Emarsys contact fields: ```json { "key_id": "email", "email": "jordan.lee@example.com", "first_name": "Jordan", "last_name": "Lee", "email_optin": true, "referrals_total": 7, "friends_referred": 5, "times_shared": 12, "is_advocate": true, "referred_by_first_name": "Casey", "referred_by_last_name": "Morgan", "referred_by_email": "casey.morgan@example.com", "reward_coupon_code": "FRIEND25", "reward_earned": "$25 account credit", "campaign_name": "Spring Referral 2026" } ``` > **Note:** > > Emarsys references each contact field by a numeric ID that is specific to your account. > Readable names are shown above for clarity. ## Contact us Interested in setting this up? Contact your CSM or get in touch [here](https://www.talkable.com/lets-talk-referral). Source: https://docs.talkable.com/email_marketing_and_automation/exponea.md =============================================================================== # Exponea Talkable syncs referral opt-ins and contact data into Exponea — a customer data and engagement platform — so every Advocate and Friend who opts in during a campaign flows into your marketing in real time. ## What this integration does Talkable turns referral sign-ups into enriched, segmentable contacts in your ESP — automatically. The integration: * **Syncs referral opt-ins** — every Advocate and Friend who opts in during a Talkable campaign is sent to your ESP as a contact create-or-update, so referral sign-ups grow your marketable audience in real time. * **Targets the right list or audience** — each contact is added to the specific list, audience, or subscription group you choose, so referred customers drop straight into the right welcome series, nurture flow, or segment. * **Enriches contacts with referral data** — map Talkable data such as referral and share counts, advocate status, and campaign details to your ESP’s fields through interpolation variables, powering referral-based segmentation, triggers, and personalization. ## When opt-ins are synced An opt-in can happen at two points in a referral — the Advocate’s and the Friend’s — and Talkable syncs each one to your ESP the instant it happens, so no opted-in contact is missed or left for a manual export. Here is where that fits in the referral journey: 1. **Advocate opts in.** A customer enters a Talkable campaign (post-purchase, standalone, floating widget, and so on) and opts in for marketing communications. 2. **Advocate synced** → Talkable sends the advocate’s contact details and opt-in status to your ESP. 3. **Advocate shares the offer.** They share by email, social, SMS, or a unique link. 4. **Friend opts in.** A friend follows the referral link, enters the campaign, and opts in to claim the offer. 5. **Friend synced** → Talkable sends the friend’s contact details and opt-in status to your ESP. ## Segmentation use cases With referral data flowing into your ESP, you can: * Build a segment of active advocates (people with one or more successful referrals) for VIP or loyalty campaigns. * Trigger a welcome series for friends acquired through a referral. * Re-engage advocates who have not shared recently. * Personalize messages with relational details — the person’s name and who referred them — so referral emails feel personal, not like another generic promo. ## Available data points You can attach a wide range of Talkable referral data to each contact you sync. The exact variable names are shown in the product when you configure the integration; at a glance, the data available includes: | Data | What’s included | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Contact details | Email, phone number, and name | | Opt-in status | Email and SMS opt-in state, and when each opt-in happened | | Person profile | Advocate and loyalty status, when and where they signed up (including location), and any custom properties you pass from your store | | Referral activity | Referrals made (total, approved, and pending), shares made, and who referred them — by name and email | | Rewards | The coupon code and reward value the person earned | | Campaign | Campaign name, type, tags, and whether it’s active | ## Sample payload When a referred customer opts in, Talkable sends their email and marketing consent to Exponea: ```json { "email": "jordan.lee@example.com", "consent": { "category": "email", "action": "accept" } } ``` ## Contact us Interested in setting this up? Contact your CSM or get in touch [here](https://www.talkable.com/lets-talk-referral). Source: https://docs.talkable.com/email_marketing_and_automation/getresponse.md =============================================================================== # GetResponse Talkable syncs referral opt-ins and contact data into GetResponse — an email marketing and automation platform — so every Advocate and Friend who opts in during a campaign flows into your marketing in real time. ## What this integration does Talkable turns referral sign-ups into enriched, segmentable contacts in your ESP — automatically. The integration: * **Syncs referral opt-ins** — every Advocate and Friend who opts in during a Talkable campaign is sent to your ESP as a contact create-or-update, so referral sign-ups grow your marketable audience in real time. * **Targets the right list or audience** — each contact is added to the specific list, audience, or subscription group you choose, so referred customers drop straight into the right welcome series, nurture flow, or segment. * **Enriches contacts with referral data** — map Talkable data such as referral and share counts, advocate status, and campaign details to your ESP’s fields through interpolation variables, powering referral-based segmentation, triggers, and personalization. ## When opt-ins are synced An opt-in can happen at two points in a referral — the Advocate’s and the Friend’s — and Talkable syncs each one to your ESP the instant it happens, so no opted-in contact is missed or left for a manual export. Here is where that fits in the referral journey: 1. **Advocate opts in.** A customer enters a Talkable campaign (post-purchase, standalone, floating widget, and so on) and opts in for marketing communications. 2. **Advocate synced** → Talkable sends the advocate’s contact details and opt-in status to your ESP. 3. **Advocate shares the offer.** They share by email, social, SMS, or a unique link. 4. **Friend opts in.** A friend follows the referral link, enters the campaign, and opts in to claim the offer. 5. **Friend synced** → Talkable sends the friend’s contact details and opt-in status to your ESP. ## Segmentation use cases With referral data flowing into your ESP, you can: * Build a segment of active advocates (people with one or more successful referrals) for VIP or loyalty campaigns. * Trigger a welcome series for friends acquired through a referral. * Re-engage advocates who have not shared recently. * Personalize messages with relational details — the person’s name and who referred them — so referral emails feel personal, not like another generic promo. ## Available data points You can attach a wide range of Talkable referral data to each contact you sync. The exact variable names are shown in the product when you configure the integration; at a glance, the data available includes: | Data | What’s included | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Contact details | Email, phone number, and name | | Opt-in status | Email and SMS opt-in state, and when each opt-in happened | | Person profile | Advocate and loyalty status, when and where they signed up (including location), and any custom properties you pass from your store | | Referral activity | Referrals made (total, approved, and pending), shares made, and who referred them — by name and email | | Rewards | The coupon code and reward value the person earned | | Campaign | Campaign name, type, tags, and whether it’s active | ## Sample payload Here is what a referral opt-in looks like when Talkable syncs it to GetResponse — referral data maps to your GetResponse custom fields: ```json { "email": "jordan.lee@example.com", "name": "Jordan Lee", "campaign": { "campaignId": "your_list" }, "customFieldValues": [ { "customFieldId": "referrals_total", "value": ["7"] }, { "customFieldId": "friends_referred", "value": ["5"] }, { "customFieldId": "times_shared", "value": ["12"] }, { "customFieldId": "is_advocate", "value": ["true"] }, { "customFieldId": "referred_by_first_name", "value": ["Casey"] }, { "customFieldId": "referred_by_last_name", "value": ["Morgan"] }, { "customFieldId": "referred_by_email", "value": ["casey.morgan@example.com"] }, { "customFieldId": "reward_coupon_code", "value": ["FRIEND25"] }, { "customFieldId": "reward_earned", "value": ["$25 account credit"] }, { "customFieldId": "campaign_name", "value": ["Spring Referral 2026"] } ] } ``` > **Note:** > > GetResponse references each custom field by an ID that is specific to your account. > Readable names are shown above for clarity. ## Contact us Interested in setting this up? Contact your CSM or get in touch [here](https://www.talkable.com/lets-talk-referral). Source: https://docs.talkable.com/email_marketing_and_automation/hubspot.md =============================================================================== # Hubspot With ESP apps clients can synchronize emails that Talkable acquires with their ESP. Here are the conditions when Talkable acquires emails: 1. Advocate signs up and opts in for Talkable marketing emails: [[Image]](https://docs.talkable.com/_images/signup_advocate.png.md) 2. A friend passes email gating and opts in for Talkable marketing emails: [[Image]](https://docs.talkable.com/_images/signup_friend.png.md) Each ESP application allows custom attributes to be included with each request. The following interpolation variables are allowed: 1. `{{ person }}` - a data object for either advocate or friend whenever they sign up or pass email gating and opt-in for marketing emails. 2. `{{ ip }}` – a data object from which IP address either a signup or email gating occurred. 3. `{{ campaign }}` – a data object with details about the campaign within which the email was captured. [[Image]](https://docs.talkable.com/_images/variables.png.md) Each variable is described in the “Available variables” sidebar and can be expanded to see all nested properties. ## How to add a new app? Please use the following guide to start using an app you need: 1. Navigate into the App store: [[Image]](https://docs.talkable.com/_images/app_store_step_1.png.md) [[Image]](https://docs.talkable.com/_images/app_store_step_2.png.md) 2. Choose an app you need by clicking “Install” 3. Fill in all necessary fields. You can use tips on the right that instruct how to find all necessary credentials. 4. Complete installation and enable the app: [Image] 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]](https://docs.talkable.com/_images/send_sample_payload.png.md) ## Contact us Interested in setting this up? Contact your CSM or get in touch [here](https://www.talkable.com/lets-talk-referral). Source: https://docs.talkable.com/email_marketing_and_automation/iterable.md =============================================================================== # Iterable Talkable syncs referral opt-ins and contact data into Iterable — a cross-channel marketing platform — so every Advocate and Friend who opts in during a campaign flows into your marketing in real time. ## What this integration does Talkable turns referral sign-ups into enriched, segmentable contacts in your ESP — automatically. The integration: * **Syncs referral opt-ins** — every Advocate and Friend who opts in during a Talkable campaign is sent to your ESP as a contact create-or-update, so referral sign-ups grow your marketable audience in real time. * **Targets the right list or audience** — each contact is added to the specific list, audience, or subscription group you choose, so referred customers drop straight into the right welcome series, nurture flow, or segment. * **Enriches contacts with referral data** — map Talkable data such as referral and share counts, advocate status, and campaign details to your ESP’s fields through interpolation variables, powering referral-based segmentation, triggers, and personalization. ## When opt-ins are synced An opt-in can happen at two points in a referral — the Advocate’s and the Friend’s — and Talkable syncs each one to your ESP the instant it happens, so no opted-in contact is missed or left for a manual export. Here is where that fits in the referral journey: 1. **Advocate opts in.** A customer enters a Talkable campaign (post-purchase, standalone, floating widget, and so on) and opts in for marketing communications. 2. **Advocate synced** → Talkable sends the advocate’s contact details and opt-in status to your ESP. 3. **Advocate shares the offer.** They share by email, social, SMS, or a unique link. 4. **Friend opts in.** A friend follows the referral link, enters the campaign, and opts in to claim the offer. 5. **Friend synced** → Talkable sends the friend’s contact details and opt-in status to your ESP. ## Segmentation use cases With referral data flowing into your ESP, you can: * Build a segment of active advocates (people with one or more successful referrals) for VIP or loyalty campaigns. * Trigger a welcome series for friends acquired through a referral. * Re-engage advocates who have not shared recently. * Personalize messages with relational details — the person’s name and who referred them — so referral emails feel personal, not like another generic promo. ## Available data points You can attach a wide range of Talkable referral data to each contact you sync. The exact variable names are shown in the product when you configure the integration; at a glance, the data available includes: | Data | What’s included | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Contact details | Email, phone number, and name | | Opt-in status | Email and SMS opt-in state, and when each opt-in happened | | Person profile | Advocate and loyalty status, when and where they signed up (including location), and any custom properties you pass from your store | | Referral activity | Referrals made (total, approved, and pending), shares made, and who referred them — by name and email | | Rewards | The coupon code and reward value the person earned | | Campaign | Campaign name, type, tags, and whether it’s active | ## Sample payload Here is what a referral opt-in looks like when Talkable syncs it to Iterable — referral data lands in the contact’s `dataFields`, ready to use in lists and journeys: ```json { "listId": 482913, "subscribers": [ { "email": "jordan.lee@example.com", "dataFields": { "first_name": "Jordan", "last_name": "Lee", "email_optin": true, "referrals_total": 7, "friends_referred": 5, "times_shared": 12, "is_advocate": true, "referred_by_first_name": "Casey", "referred_by_last_name": "Morgan", "referred_by_email": "casey.morgan@example.com", "reward_coupon_code": "FRIEND25", "reward_earned": "$25 account credit", "campaign_name": "Spring Referral 2026" } } ] } ``` ## Contact us Interested in setting this up? Contact your CSM or get in touch [here](https://www.talkable.com/lets-talk-referral). Source: https://docs.talkable.com/email_marketing_and_automation/klaviyo.md =============================================================================== # Klaviyo With ESP apps clients can synchronize emails that Talkable acquires with their ESP. Here are the conditions when Talkable acquires emails: 1. Advocate signs up and opts in for Talkable marketing emails: [[Image]](https://docs.talkable.com/_images/signup_advocate.png.md) 2. A friend passes email gating and opts in for Talkable marketing emails: [[Image]](https://docs.talkable.com/_images/signup_friend.png.md) Each ESP application allows custom attributes to be included with each request. The following interpolation variables are allowed: 1. `{{ person }}` - a data object for either advocate or friend whenever they sign up or pass email gating and opt-in for marketing emails. 2. `{{ ip }}` – a data object from which IP address either a signup or email gating occurred. 3. `{{ campaign }}` – a data object with details about the campaign within which the email was captured. [[Image]](https://docs.talkable.com/_images/variables.png.md) Each variable is described in the “Available variables” sidebar and can be expanded to see all nested properties. ## How to add a new app? Please use the following guide to start using an app you need: 1. Navigate into the App store: [[Image]](https://docs.talkable.com/_images/app_store_step_1.png.md) [[Image]](https://docs.talkable.com/_images/app_store_step_2.png.md) 2. Choose an app you need by clicking “Install” 3. Confirm the app installation in Klaviyo 4. Complete installation in Talkable and enable the app: [Image] 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]](https://docs.talkable.com/_images/send_sample_payload.png.md) ## Talkable profile properties Every time a Talkable event reaches Klaviyo, Talkable adds extra information about the person to their Klaviyo profile — things like how many friends they’ve referred, whether they’ve shared an offer, and which campaign brought them in. This happens automatically, on top of the standard fields (email, first name, phone, etc.) you see under **Payload attributes** in each action. You can use these properties in Klaviyo to build segments, trigger flows, and personalize emails — for example, send a thank-you email to advocates with three or more approved referrals, or greet a referred customer with a “your friend just signed up” message. Which profiles get updated, by action: * **Sync email opt-ins** / **Sync phone opt-ins** — the person who just opted in. * **Track offer shares** — the advocate who shared their offer. * **Track referral approvals** — both the friend (the new customer) and the advocate who referred them. The friend’s profile gets the advocate’s email saved on `talkable_referred_by_email`, which is how the *Talkable Referred Customers* segment finds them. * **Track reward issued** — the person receiving the reward. * **Sync loyalty actions** / **Sync loyalty tier transitions** — the loyalty member. | Property | Value | What it means | | ---------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------- | | `talkable_advocate` | true / false | Whether this person has received at least one Talkable referral offer (i.e. has ever been an advocate). | | `talkable_referral_count_total` | Number | Total number of friends this person has referred, regardless of status. | | `talkable_referral_count_approved` | Number | Number of this person’s referrals that have been approved (rewards earned). | | `talkable_referral_count_pending` | Number | Number of this person’s referrals still awaiting approval. | | `talkable_shares_count` | Number | How many times this person has shared their offer across all channels (email, SMS, Facebook, copy link, etc.). | | `talkable_referred_by_email` | Email | The advocate’s email — set only on friends who came in through a referral. | | `talkable_referred_by_first_name` | Text | The advocate’s first name — set only on friends who came in through a referral. | | `talkable_referred_by_last_name` | Text | The advocate’s last name — set only on friends who came in through a referral. | | `talkable_latest_offer_date` | Date | Date of the most recent Talkable referral offer this person received. | | `talkable_loyalty_member` | true / false | Whether this person is enrolled in your Talkable loyalty program. | | `talkable_campaign_name` | Text | Name of the Talkable campaign that drove the current event. | | `talkable_campaign_tags` | List of tags | Tags assigned to the Talkable campaign that drove the current event. | If a property doesn’t apply to someone (for example, `talkable_referred_by_email` for a person who signed up directly), it’s simply left off — Klaviyo will treat it as “not set” in segment conditions. ## Segments When the Klaviyo app is installed, Talkable creates a set of starter segments built on top of the profile properties above. You can find them in Klaviyo under **Audience → Lists & Segments**. Segment creation requires the `segments:read` and `segments:write` OAuth scopes. Klaviyo includes them in the consent screen when you install the app, and its consent is all-or-nothing — you can’t approve some scopes and decline others — so a fresh install grants these automatically. If your installation predates Talkable’s segments feature and you haven’t reauthorized the app since, the stored grant won’t include the segment scopes and Talkable will quietly skip segment creation. Reinstall the app from the Talkable App Store (look for the **Reinstall** badge) to pick up the new scopes; the segments will be created right after that to preserve the app activation status. The segment-creation step runs on each **app activation** — fresh install, reinstall, or toggling the app off and back on. On every run, Talkable looks up Klaviyo segments by their original Talkable names: * If a matching name exists, Talkable leaves the segment untouched — **editing the conditions** of a Talkable segment is safe; your edits won’t be overwritten. * If a matching name is missing, Talkable creates a fresh segment with that name and the default conditions. **Renaming** a Talkable segment causes Talkable to recreate the original on the next activation (your renamed copy stays alongside it); **deleting** one means it reappears on the next activation. To customize a Talkable segment safely, edit its conditions in place rather than renaming or deleting it. If you need a meaningfully different segment, build it as a separate segment in Klaviyo. | Segment | Conditions (joined with AND) | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Talkable Opted In Never Shared** | `talkable_advocate` equals `true` AND `talkable_shares_count` equals `0`. Advocates who opted in but never shared their offer — good candidates for a nudge. | | **Talkable High-Value Advocates** | `talkable_referral_count_approved` is at least `3`. Your top referrers — use for VIP treatment, ambassador invites, or special rewards. | | **Talkable Referred Customers** | `talkable_referred_by_email` is set. People who came in through a referral — useful for welcome flows that acknowledge the advocate. | | **Talkable Lapsed Advocates** | `talkable_advocate` equals `true` AND `talkable_shares_count` is greater than `0` AND `talkable_latest_offer_date` is at least `30` days ago. Previously-engaged advocates who’ve gone quiet — target with win-back flows. | ## Metrics Talkable fires Klaviyo **metric events** for the most important moments in a referral lifecycle. Each event becomes a trigger you can use to start a Klaviyo Flow — welcome series, thank-you emails, reward notifications, and so on. The following metric events are sent when the corresponding action is enabled: | Metric name | Triggered by | Profile that receives the event | | ------------------------------ | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Talkable Email Opted In** | Sync email opt-ins | The opted-in person | | **Talkable Phone Opted In** | Sync phone opt-ins | The opted-in person | | **Talkable Offer Shared** | Track offer shares in Klaviyo | The advocate who shared | | **Talkable Referral Approved** | Track referral approvals in Klaviyo | The advocate (the friend’s profile is updated separately so the *Talkable Referred Customers* segment picks them up) | | **Talkable Reward Issued** | Track reward issued in Klaviyo | The reward recipient | The **Sync loyalty actions** and **Sync loyalty tier transitions** actions also generate metric events. Their metric names come from the `metric_name` payload attribute (defaults: `loyalty_action_performed` and `loyalty_tier_transitioned`), so you can rename them or split them across multiple metrics by editing the payload. ### Metric event properties Every metric event carries two layers of data: 1. **Profile properties** — all the `talkable_*` properties listed in *Talkable profile properties* above are attached to the recipient’s profile alongside the event. Use them as Flow filters or reference them in the email body as `{{ person.talkable_referral_count_approved }}`. 2. **Event properties** — whatever you’ve configured in the action’s **Payload attributes** panel (minus `email` and `metric_name`, which Klaviyo handles specially) ends up here. By default the track-* actions send only the recipient’s email, so the event properties bag is empty until you add custom attributes. ### Viewing and filtering metrics in Analytics Open **Analytics → Metrics** in Klaviyo and pick any Talkable metric (for example, *Talkable Referral Approved*) to see an over-time chart of event volume. From the chart’s controls you can: * **Filter (Where)** — restrict the chart to events whose property matches a specific value (for example, only events where `campaign_name` equals `"Holiday 2025"`). * **Group by (By)** — break the chart into one line per property value (for example, group *Talkable Offer Shared* by `channel` to compare email, SMS, and Facebook shares side by side). Any custom attribute you add to the action’s payload becomes available as a filter/group-by option on its metric. For richer analysis, build a **Custom Report** under **Analytics → Custom Reports** — single-metric Deep Dive reports support property filters and grouping, while multi-metric reports do not (each metric has its own property schema). ### Using event properties in email bodies In a Flow triggered by a Talkable metric, event properties are available in the email template as `{{ event.
block for the referral campaign.
```html
```
* Optionally, update the schema name to anything meaningful, for example, “Referral campaign“
[Image]
* Click “Save”
2. Create a share page template:
* Go to **Templates**
* Click “Add a new template“
* Create a new JSON template of type page called talkable (page.talkable.json)
* Change the type of the main section to talkable-campaign
[Image]
> **Important:**
>
> The name of the section should be the same as the one you used
> in the previous step when naming your section file.
> **Important:**
>
> If your main section is disabled, remove the row that does it.
3. Create a page:
* Exit theme editor if it was opened
* Go to **Online Store** → **Pages**
* Click “Add page“
* Add title: Share
* Select theme template: talkable
* Click “Save”
9. In your Shopify Admin, create resources for referral dashboard page:
1. Create a dashboard page section:
* In the theme code editor (**Online Store** → **Themes** → **Edit code**), go to **Sections**
* Click “Add a new section“
* Create a new Liquid section called talkable-dashboard.liquid
* In the newly created file, add the following code:
```html
{% if shop.customer_accounts_enabled %}
{% if customer %}
{% else %}
{{ 'Log in' | customer_login_link }}
{% endif %}
{% endif %}
```
* Optionally, update the schema name to anything meaningful, for example, “Referral dashboard“
* Click “Save”
2. Create a dashboard page template:
* Go to **Templates**
* Click “Add a new template“
* Create a new JSON template of type page called dashboard.talkable (page.dashboard.talkable.json)
* Change the type of the main section to talkable-dashboard
```JSON
{
"sections": {
"main": {
"type": "talkable-dashboard"
}
}
}
```
> **Important:**
>
> The name of the section should be the same as the one you used
> in the previous step when naming your section file.
> **Important:**
>
> If your main section is disabled, remove the row that does it.
3. Create a page:
* Exit theme editor if it was opened
* Go to **Online Store** → **Pages**
* Click “Add page“
* Add title: Referral Dashboard
* Select theme template: dashboard.talkable
* Click “Save” (Customer accounts must be enabled in **Settings** → **Checkout**)
10. In your Shopify Admin, add a post-purchase script:
* Go to **Settings** → **Checkout**
* Scroll down to **Order status page**
* Paste the following code into **Additional scripts** field:
```html
```
> **Note:**
>
> Replace **** with your Talkable Site ID which is displayed on the integration page.
* Click “Save”.
11. Verify your integration using [Verifying Integration instructions](https://docs.talkable.com/integration/verify.md#integration-verify).
> **Important:**
>
> If you are managing the Shopify theme code using a [Shopify Github integration](https://shopify.dev/docs/storefronts/themes/tools/github),
> make sure to pull the changes to the theme made by the automatic integration to avoid
> resetting them with a commit.
### For Shopify vintage themes
If your Shopify store uses a [vintage theme](https://help.shopify.com/en/manual/online-store/themes/managing-themes/versions),
please follow the instructions below.
1. Provide a valid Shopify store URL and choose “Shopify” as your platform during registration process
2. On the Welcome screen click “I’m a Developer”
3. Pass Shopify authorization
4. You will be redirected to your Shopify store, log in and click the install button
5. After successful installation you will be redirected back to Talkable
6. Click “Integrate manually“
7. In your Shopify Admin, add the integration to your layout:
1. Create a snippet:
* Go to **Online Store** → **Themes**
* Click **Actions** (”…” button) → **Edit code**
* Go to **Snippets**
* Click “Add a new snippet“
* Create a new snippet called talkable-partial
* In the newly created file, add the following code:
```html
```
> **Note:**
>
> Replace **** with your Talkable Site ID which is displayed on the integration page.
* Click “Save”
2. Render the snippet in the layout:
* In the theme code editor (**Online Store** → **Themes** → **Edit code**), go to **Layout**
* Open theme.liquid file
* Before closing paste the following code:
```liquid
{% render "talkable-partial" %}
```
* Click “Save”
8. In your Shopify Admin, create resources for referral share page:
1. Create a share page template:
* In the theme code editor (**Online Store** → **Themes** → **Edit code**), go to **Templates**
* Click “Add a new template“
* Create a new Liquid template of type page called talkable (page.talkable.liquid)
* Paste the following code inside layout of this page instead of {{ page.content }}:
```html
```
* Click “Save”
2. Create a page:
* Exit theme editor if it was opened
* Go to **Online Store** → **Pages**
* Click “Add page“
* Add title: Share
* Select theme template: talkable
* Click “Save”
9. In your Shopify Admin, create resources for referral dashboard page:
1. Create a dashboard page template:
* In the theme code editor (**Online Store** → **Themes** → **Edit code**), go to **Templates**
* Click “Add a new template“
* Create a new Liquid template of type page called dashboard.talkable (page.dashboard.talkable.liquid)
* Paste the following code inside layout of this page instead of {{ page.content }}:
```html
{% if shop.customer_accounts_enabled %}
{% if customer %}
{% else %}
{{ 'Log in' | customer_login_link }}
{% endif %}
{% endif %}
```
* Click “Save”
2. Create a page:
* Exit theme editor if it was opened
* Go to **Online Store** → **Pages**
* Click “Add page“
* Add title: Referral Dashboard
* Select theme template: dashboard.talkable
* Click “Save” (Customer accounts must be enabled in **Settings** → **Checkout**)
10. In your Shopify Admin, add a post-purchase script:
* Go to **Settings** → **Checkout**
* Scroll down to **Order status page**
* Paste the following code into **Additional scripts** field:
```html
```
> **Note:**
>
> Replace **** with your Talkable Site ID which is displayed on the integration page.
* Click “Save”.
11. Verify your integration using [Verifying Integration instructions](https://docs.talkable.com/integration/verify.md#integration-verify).
```html
https://123test.myshopify.com
```
> **Important:**
>
> If you are managing the Shopify theme code using a [Shopify Github integration](https://shopify.dev/docs/storefronts/themes/tools/github),
> make sure to pull the changes to the theme made by the automatic integration to avoid
> resetting them with a commit.
## Manual migrating from a vintage theme to an Online store 2.0 theme
If you have previously integrated Talkable in your vintage Shopify theme and want to migrate to a newer theme,
you need to do the following:
1. Share page migration:
1. If you have a templates/page.talkable.liquid file, store its content elsewhere and delete the file
2. Create a share page section:
* In the theme code editor (**Online Store** → **Themes** → **Edit code**), go to **Sections**
* Click “Add a new section“
* Create a new Liquid section called talkable-campaign.liquid
* In the newly created file, add the
block for the referral campaign.
```html
```
If there were any customizations in the templates/page.talkable.liquid, add them as well
* Optionally, update the schema name to anything meaningful, for example, “Referral campaign“
* Click “Save”
3. Create a share page template:
* Go to **Templates**
* Click “Add a new template“
* Create a new JSON template of type page called talkable (page.talkable.json)
* Change the type of the main section to talkable-campaign
[Image]
> **Important:**
>
> The name of the section should be the same as the one you used
> in the previous step when naming your section file.
> **Important:**
>
> If your main section is disabled, remove the row that does it.
2. Dashboard page migration:
1. If you have a templates/page.talkable-dashboard.liquid file, store its content elsewhere and delete the file
2. Create a dashboard page section:
* In the theme code editor (**Online Store** → **Themes** → **Edit code**), go to **Sections**
* Click “Add a new section“
* Create a new Liquid section called talkable-dashboard.liquid
* In the newly created file, add the
block for the referral campaign.
```html
{% if shop.customer_accounts_enabled %}
{% if customer %}
{% else %}
{{ 'Log in' | customer_login_link }}
{% endif %}
{% endif %}
```
If there were any customizations in the templates/page.talkable-dashboard.liquid, add them as well
* Optionally, update the schema name to anything meaningful, for example, “Referral dashboard“
* Click “Save”
3. Create a dashboard page template:
* Go to **Templates**
* Click “Add a new template“
* Create a new JSON template of type page called dashboard.talkable (page.dashboard.talkable.json)
* Change the type of the main section to talkable-dashboard
```JSON
{
"sections": {
"main": {
"type": "talkable-dashboard"
}
}
}
```
> **Important:**
>
> The name of the section should be the same as the one you used
> in the previous step when naming your section file.
> **Important:**
>
> If your main section is disabled, remove the row that does it.
> **Important:**
>
> If you are managing the Shopify theme code using a [Shopify Github integration](https://shopify.dev/docs/storefronts/themes/tools/github),
> make sure to pull the changes to the theme made by the automatic integration to avoid
> resetting them with a commit.
> **Note:**
>
> Also Talkable provides integration for Shopify Plus.
## Contact us
Interested in setting this up? Contact your CSM or get in touch [here](https://www.talkable.com/lets-talk-referral).
Source: https://docs.talkable.com/integration/loyalty.md
===============================================================================
# Loyalty Integration
Integrating Talkable Loyalty to e-commerce sites is done in
a few quick steps by adding the below scripts to your site.
## Integration
1. Initialize Talkable integration library.
Add the [Talkable Initialization Script](https://docs.talkable.com/integration/loyalty/integration_components.md#integration-loyalty-integration-components-initialization-script) to your header or any template spanning every page.
> **Note:**
>
> Skip this step if you already have Talkable integrated on your site
2. Add Loyalty Dashboard.
To host the Loyalty campaign, create a new HTML page with a standard
header/footer. The best practice is to create this page on `www.your-site.com/loyalty`
Copy Talkable container DIV element & paste it exactly where the Talkable iframe should be rendered, similarly to the referral standalone placement:
```html
```
3. Add Redeem Widget.
Copy Talkable container DIV element & paste it at the checkout
exactly where the loyalty points redemption widget should render:
```html
```
It is recommended to add it above the discount field. Examples:
[Image]
4. Define Loyalty points redemption batches.
Each redemption batch determines progressive point redemption options based on the available points balance of the loyalty member.
For example, 500 points would equal a discount coupon for $50 off, 1000 points would equal $100, and so on.
For every redemption batch, please generate single-use coupons for
a certain discount amount ($50 off, $100 off, etc.) and upload all coupon lists into Talkable loyalty coupon lists.
It is recommended to upload 100,000 single-use coupons into every coupon list.
[Image]
> **Note:**
>
> All design and loyalty campaign setup is done inside the Talkable platform,
> then via iframe loyalty campaign content is injected into the site.
## Requirements
1. User accounts. The website must support user accounts since the loyalty program is only available to logged in users.
2. Single-use coupons. Every loyalty member will have a choice of redemption batches to redeem points for a one-time discount.
When pressing a redeem button Talkable deducts points and issues a single-use coupon in return.
3. Ideally, only purchases without tax & shipping costs should be passed to Talkable.
This simplifies future refunds support as taxes and shipping costs are not refundable.
* [Integration Components](https://docs.talkable.com/integration/loyalty/integration_components.md)
* [Initialization Script](https://docs.talkable.com/integration/loyalty/integration_components.md#initialization-script)
* [Initialization Script Notes](https://docs.talkable.com/integration/loyalty/integration_components.md#initialization-script-notes)
* [Talkable Container DIV](https://docs.talkable.com/integration/loyalty/integration_components.md#talkable-container-div)
* [Loyalty Dashboard Notes](https://docs.talkable.com/integration/loyalty/integration_components.md#loyalty-dashboard-notes)
* [Loyalty Widget Notes](https://docs.talkable.com/integration/loyalty/integration_components.md#loyalty-widget-notes)
* [Loyalty Actions](https://docs.talkable.com/integration/loyalty/integration_components.md#loyalty-actions)
* [Loyalty Actions Notes](https://docs.talkable.com/integration/loyalty/integration_components.md#loyalty-actions-notes)
* [Custom App for Loyalty](https://docs.talkable.com/integration/loyalty/custom_app.md)
* [Sync loyalty actions](https://docs.talkable.com/integration/loyalty/custom_app.md#sync-loyalty-actions)
* [Liquid variables hints](https://docs.talkable.com/integration/loyalty/custom_app.md#liquid-variables-hints)
* [Sync loyalty tier transitions](https://docs.talkable.com/integration/loyalty/custom_app.md#sync-loyalty-tier-transitions)
* [Liquid variables hints](https://docs.talkable.com/integration/loyalty/custom_app.md#id1)
* [Auto-Enrollment](https://docs.talkable.com/integration/loyalty/auto_enrollment.md)
* [Post-Purchase Enrollment](https://docs.talkable.com/integration/loyalty/auto_enrollment.md#post-purchase-enrollment)
* [Enrollment via JS Integration](https://docs.talkable.com/integration/loyalty/auto_enrollment.md#enrollment-via-js-integration)
* [Code Example #1:](https://docs.talkable.com/integration/loyalty/auto_enrollment.md#code-example-1)
* [Code Example #2:](https://docs.talkable.com/integration/loyalty/auto_enrollment.md#code-example-2)
* [Shopify Integration](https://docs.talkable.com/integration/loyalty/shopify_integration.md)
* [Automatic integration](https://docs.talkable.com/integration/loyalty/shopify_integration.md#automatic-integration)
* [Manual integration](https://docs.talkable.com/integration/loyalty/shopify_integration.md#manual-integration)
* [Manual migrating from a vintage theme to an Online store 2.0 theme](https://docs.talkable.com/integration/loyalty/shopify_integration.md#manual-migrating-from-a-vintage-theme-to-an-online-store-2-0-theme)
Source: https://docs.talkable.com/integration/loyalty/auto_enrollment.md
===============================================================================
# Auto-Enrollment
Talkable allows to enroll users to loyalty without showing the loyalty dashboard page.
There are a couple of ways to do that:
* [Post-Purchase Enrollment](#post-purchase-enrollment)
* [Enrollment via JS Integration](#enrollment-via-js-integration)
## Post-Purchase Enrollment
Enroll users to loyalty after they make a purchase.
A setting to enable this behavior can be found under **Site settings** → **Loyalty settings** → **General** → **Auto-enrollment**.
## Enrollment via JS Integration
Enroll users to loyalty without showing the campaign using join_loyalty.
For example, this could be used for enrolling users during registration or login.
Don’t forget to include a consent checkbox that would inform your user that they are about to join the loyalty program.
> **Note:**
>
> join_loyalty is available since integration version 4.5.9.
### Code Example #1:
Use authenticate_customer to store current user data.
When you call join_loyalty, you can pass empty object since Talkable will have access to the data from authenticate_customer.
> **Tip:**
>
> authenticate_customer data can also be reused by other integration functions.
```js
window._talkableq.push(["authenticate_customer", {
email: "loyalty@talkable.com", // required for `join_loyalty`
phone_number: '+12025551111',
first_name: "John",
last_name: "Smith",
custom_properties: {},
customer_id: "11111"
}]);
window._talkableq.push("join_loyalty", {})
```
### Code Example #2:
Pass loyalty member data directly to join_loyalty.
> **Note:**
>
> Arguments passed with join_loyalty override respective arguments from authenticate_customer.
```js
window._talkableq.push(["join_loyalty", {
email: "loyalty@talkable.com", // required
phone_number: '+12025551111',
first_name: "John",
last_name: "Smith",
custom_properties: {},
customer_id: "11111"
}]);
```
Source: https://docs.talkable.com/integration/loyalty/custom_app.md
===============================================================================
# Custom App for Loyalty
Talkable offers a Custom App that allows you to send Talkable data to an outside destination such as your site, ESP, or CDP.
The Custom App supports several actions. In the context of loyalty, the following actions might be useful:
* Sync loyalty actions
* Sync loyalty tier transitions
By default, the Custom App payload contains only email for loyalty-related actions.
However, it is recommended to modify the payload that will be sent when the app is triggered.
To set up a Custom App, go to **All site settings** → **App store** → **Custom app**.
## Sync loyalty actions
This feature sends Talkable data to the configured endpoint URL in the following cases:
* when a loyalty member earns points according to loyalty action configurations (eg. by subscribing to your newsletter);
* when a loyalty member earns or has points deducted due to a manual points adjustment (eg. made by a Customer Service representative);
* when a loyalty member exchanges (redeems) points for a coupon discount.
### Liquid variables hints
To determine which loyalty action triggered the Custom App, use {{ action.identifier }} liquid variable in the payload.
{{ action.identifier }} can have the following values:
* when loyalty member exchanges points for a coupon, the Action Identifier is *“redeem”*;
* when loyalty member gains or loses points due to a manual points adjustment, the Action Identifier is *“manual_adjustment”*;
* when loyalty member earns points according to loyalty action configurations, the Action Identifier varies based on the action configuration type:
* *“optin”* for “Loyalty join”;
* *“event”* for “Purchase points” and “Event points”;
* *“referral”* for “Refer a friend”;
* for a custom type, the Identifier is taken straight from the action configuration “Identifier” field.
{{ action.rule }} contains details about the action configuration that is responsible for a particular points collection.
> **Note:**
>
> {{ action.rule }} is optional for *“manual_adjustment”* actions and always blank for *“redeem”* actions.
To see the full list of available variables, click “Show available variables” on the Custom App action configuration page.
## Sync loyalty tier transitions
This feature sends Talkable data to the configured endpoint URL once a loyalty member reaches a new tier.
### Liquid variables hints
{{ tier_transition.reason }} is either *“upgrade”* or *“downgrade”*, depending on the direction of the transition.
To see the full list of available variables, click “Show available variables” on the Custom App action configuration page.
Source: https://docs.talkable.com/integration/loyalty/integration_components.md
===============================================================================
# Integration Components
Talkable Loyalty is composed of the following components:
1. [Initialization Script](#integration-loyalty-integration-components-initialization-script)
**Script Location.** The Initialization script should be placed in the head template or some template
that spans every page. All other integration components are dependent on the Init script.
**Data Capture.** The Initialization Script should pass variables for logged in users:
* Email
* Phone Number
* First Name
* Last Name
* Custom Properties
* Customer ID
2. [Talkable Container DIV](#talkable-container-div)
**DIV Location.** Talkable Container DIV should be placed in the body of every page where you want to show a loyalty campaign. This DIV tag determines the place where the campaign is shown.
3. [Loyalty Actions](#loyalty-actions)
## Initialization Script
The Initialization script should be placed in the head template or some
template that spans every page. Talkable JS library size is typically
around 20kB and causes no noticeable impact to your site’s loading time.
All other integration components are dependent on the Initialization
script.
```html
```
### Initialization Script Notes
1. **Site ID.** You can obtain your Site ID by logging into the Talkable
platform where Site ID is displayed on your Dashboard and URL as seen
here:
[Image]
2. **Variables.** Use your dynamic variables to pass user details.
## Talkable Container DIV
Add the following Talkable Container DIV in the body of every page where you want a loyalty campaign to be shown:
```html
```
The [Talkable Initialization Script](#integration-loyalty-integration-components-initialization-script) must be present in your head template in order for the Loyalty Dashboard to work. The placement of the DIV tag is important since it’s going to determine where the campaign will be rendered.
> **Note:**
>
> The same DIV tag is used for both Loyalty Dashboard and Loyalty Redeem Widget.
> You can find more info about where to place the DIV tag in [Loyalty Dashboard Placement](https://docs.talkable.com/campaigns/campaign_placements/loyalty_dashboard.md#campaigns-campaign-placements-loyalty-dashboard) and [Loyalty Widget Placement](https://docs.talkable.com/campaigns/campaign_placements/loyalty_widget.md#campaigns-campaign-placements-loyalty-widget).
### Loyalty Dashboard Notes
The dashboard can be added inline inside your user accounts menu, however the dashboard content width for proper display is 980px.
### Loyalty Widget Notes
Add Talkable Container DIV at the checkout exactly where the loyalty points redemption widget should be rendered.
## Loyalty Actions
To register custom loyalty actions (e.g. completing surveys, adding reviews, uploading something on site),
use the following code:
```html
```
### Loyalty Actions Notes
1. register_loyalty_action optionally accepts email and custom_properties. If none provided, values will be
taken from respective parameters of authenticate_customer. Email must be provided in either of the sources to
register loyalty actions.
Source: https://docs.talkable.com/integration/loyalty/shopify_integration.md
===============================================================================
# Shopify Integration
## Automatic integration
After passing [Shopify authorization](https://docs.talkable.com/integration/ecommerce_platforms/shopify.md#integration-ecommerce-platforms-shopify-automatic-integration),
Loyalty page will be located at /pages/loyalty.
To turn Loyalty integration on/off, navigate to Talkable Shopify Integration page https://admin.talkable.com/sites//integration/shopify
## Manual integration
1. Pass Shopify authorization
2. You will be redirected to your Shopify store, log in and click the Install button
3. After successful installation you will be redirected back to Talkable
4. Click “Integrate manually“
5. Set up Referral Integration [manually](https://docs.talkable.com/integration/ecommerce_platforms/shopify.md#integration-ecommerce-platforms-shopify-manual-integration)
6. In your Shopify Admin create resources for loyalty dashboard page:
1. Create a loyalty dashboard page section:
* In the theme code editor (**Online Store** → **Themes** → **Edit code**), go to **Sections**
* Click “Add a new section“
* Create a new Liquid section called talkable-loyalty-dashboard.liquid
* In the newly created file, add the following code:
```html
{% if shop.customer_accounts_enabled %}
{% endif %}
```
* Optionally, update the schema name to anything meaningful, for example, “Loyalty dashboard“
* Click “Save”
2. Create a loyalty dashboard page template:
* Go to **Templates**
* Click “Add a new template“
* Create a new JSON template of type page called loyalty_dashboard.talkable (page.loyalty_dashboard.talkable.json)
* Change the type of the main section to talkable-loyalty-dashboard
```JSON
{
"sections": {
"main": {
"type": "talkable-loyalty-dashboard"
}
}
}
```
> **Important:**
>
> The name of the section should be the same as the one you used
> in the previous step when naming your section file.
> **Important:**
>
> If your main section is disabled, remove the row that does it.
3. Create a page:
* Exit theme editor if it was opened
* Go to **Online Store** → **Pages**
* Click “Add page“
* Add title: Loyalty Dashboard
* Select theme template: loyalty_dashboard.talkable
* Click “Save”
## Requirements
User accounts. The website must support user accounts since the loyalty program is only available to logged in users.
## Manual migrating from a vintage theme to an Online store 2.0 theme
If you have previously integrated Talkable in your vintage Shopify theme and want to migrate to a newer theme,
you need to do the following:
1. [Migrate the referral pages](https://docs.talkable.com/integration/ecommerce_platforms/shopify.md#integration-ecommerce-platforms-shopify-manual-integration-theme-migration)
2. If you have a templates/page.talkable-loyalty-dashboard.liquid file, store its content elsewhere and delete the file
3. Create a loyalty dashboard page section:
* In the theme code editor (**Online Store** → **Themes** → **Edit code**), go to **Sections**
* Click “Add a new section“
* Create a new Liquid section called talkable-loyalty-dashboard.liquid
* In the newly created file, add the following code:
```html
{% if shop.customer_accounts_enabled %}
{% endif %}
```
If there were any customizations in the templates/page.talkable-loyalty-dashboard.liquid, add them as well
* Optionally, update the schema name to anything meaningful, for example, “Loyalty dashboard“
* Click “Save”
4. Create a loyalty dashboard page template:
* Go to **Templates**
* Click “Add a new template“
* Create a new JSON template of type page called loyalty_dashboard.talkable (page.loyalty_dashboard.talkable.json)
* Change the type of the main section to talkable-loyalty-dashboard
```JSON
{
"sections": {
"main": {
"type": "talkable-loyalty-dashboard"
}
}
}
```
> **Important:**
>
> The name of the section should be the same as the one you used
> in the previous step when naming your section file.
> **Important:**
>
> If your main section is disabled, remove the row that does it.
Source: https://docs.talkable.com/integration/standard.md
===============================================================================
# Standard Integration
## Integration High Level Overview
1. Add the [Talkable Initialization Script](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-initialization-script) to your header or any template spanning every page.
Surface variables for email and name if user is logged in.
2. Add the [Talkable Post Purchase Script](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-post-purchase-script) to your checkout confirmation page to pass purchase details
to Talkable for all purchases.
Surface purchase detail variables as described in more detail in [Integration Components](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components).
3. Create a new HTML page with standard header/footer to host the Talkable Standalone campaign
which will be your Advocate Landing page where you can drive traffic from email and other onsite
and offsite locations to refer friends. Copy & paste the Talkable container DIV element into the
body as seen in [Integration Components](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components).
4. Create an additional new HTML page attached to your user accounts section (if you have one) behind
login which is where referring Advocates can go to view referral details of all of the friends
they’ve shared with. Copy & paste the Talkable container DIV element into the body as seen in [Integration Components](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components).
* [Integration High-Level Overview](https://docs.talkable.com/integration/standard/overview.md)
## Contents:
* [Integration Components](https://docs.talkable.com/integration/standard/integration_components.md)
* [Initialization Script](https://docs.talkable.com/integration/standard/integration_components.md#initialization-script)
* [Post Purchase Script](https://docs.talkable.com/integration/standard/integration_components.md#post-purchase-script)
* [Advocate Landing Page](https://docs.talkable.com/integration/standard/integration_components.md#advocate-landing-page)
* [Referral Dashboard](https://docs.talkable.com/integration/standard/integration_components.md#referral-dashboard)
* [Verifying Integration](https://docs.talkable.com/integration/verify.md)
* [Verifying Integration in JS SPAs](https://docs.talkable.com/integration/verify.md#verifying-integration-in-js-spas)
* [Troubleshooting](https://docs.talkable.com/integration/verify.md#troubleshooting)
* [Validating the Integration](https://docs.talkable.com/integration/standard/validating_integration.md)
* [Visual Confirmation Note](https://docs.talkable.com/integration/standard/validating_integration.md#visual-confirmation-note)
* [Validation Checklist](https://docs.talkable.com/integration/standard/validating_integration.md#validation-checklist)
* [How to create or check for existing campaigns](https://docs.talkable.com/integration/standard/validating_integration.md#how-to-create-or-check-for-existing-campaigns)
* [Test Mode Display](https://docs.talkable.com/integration/standard/validating_integration.md#test-mode-display)
* [Cookies](https://docs.talkable.com/integration/standard/cookies.md)
* [Understanding the Cookies We Use](https://docs.talkable.com/integration/standard/cookies.md#understanding-the-cookies-we-use)
* [GDPR and CCPA compliance](https://docs.talkable.com/integration/standard/cookies.md#gdpr-and-ccpa-compliance)
* [F.A.Q.](https://docs.talkable.com/integration/standard/questions.md)
Source: https://docs.talkable.com/integration/standard/alternate_post_purchase.md
===============================================================================
# Alternate Post Purchase Script for cart line item passing
```html
```
Source: https://docs.talkable.com/integration/standard/cookies.md
===============================================================================
# Cookies
At Talkable, we prioritize enhancing your digital experience.
Our use of cookies is instrumental in this endeavor, as they play a critical role in tracking referrals and conversions, personalizing content, and maintaining the overall performance and reliability of our services.
## Understanding the Cookies We Use
We broadly categorize our cookies and similar technologies as follows:
**Strictly Necessary**
These cookies and other technologies are essential to enabling your use of our Site and Services and its features.
Without these cookies, key functionalities (like sign-up processes) would be unfeasible.
These cookies may be associated with personal data.
**Functionality**
These cookies and other technologies improve your experience by enabling personalization (like remembering language and region).
They can help you fill out forms on our campaigns more easily.
These cookies may be associated with personal data.
**Analytics and Performance**
These cookies and other technologies help us learn how well our Campaigns and Services are performing.
We use these cookies to understand, improve, and research our Site and Services.
| Cookie name | Purpose | Domain(s) | Retention period(Days) |
| ----------------------------------------------------------------- | ------------------------- | -------------------------- | ---------------------- |
| `tkbl_session_id` | Strictly Necessary | talkable.com shop domain | 0 |
| `tkbl_session` | Functionality | talkable.com shop domain | 400 |
| `tkbl_cvuuid` | Functionality | talkable.com shop domain | 400 |
| [multiple](https://newrelic.com/termsandconditions/cookie-policy) | Analytics and Performance | \*.newrelic.com | 0-400 |
| `bugsnag*` | Analytics and Performance | \*.bugsnag.com | 0-400 |
| `_ga` | Analytics and Performance | talkable.com | 400 |
## GDPR and CCPA compliance
Talkable ensures compliance with GDPR and CCPA regulations.
In compliant mode, we only set a session cookie during the first user interaction.
These session cookies, being temporary, disappear once the browser is closed.
Under GDPR and CCPA, setting such cookies does not require user consent.
Post-consent (e.g., during signup), Talkable activates standard cookies to monitor user activities, aligning with regulatory guidelines.
> **Note:**
>
> Limitations of compliance mode seriously hinders Talkable ability to track referrals and conversions.
> It is advised to use compliant mode only if you are legally obligated to do so.
To enable GDPR and CCPA compliant mode, please contact your Customer Success Manager.
Source: https://docs.talkable.com/integration/standard/integration_components.md
===============================================================================
# Integration Components
Talkable is composed of the following components:
1. [Initialization Script](#integration-standard-integration-components-initialization-script)
**Script Location.** The Initialization script should be placed in the head template or some template
that spans every page. All other integration components are dependent on the Init script.
**Data Capture.** The Initialization Script should pass variables for logged in users:
* Email
* Phone Number
* First Name
* Last Name
2. [Post Purchase Script](#integration-standard-integration-components-post-purchase-script)
**Script Location.** The Post Purchase script should be placed on the checkout confirmation page.
**Script Dependency.** The Post Purchase script should be fired after the Initialization script.
**Data Capture.** This script needs to capture purchase based details
* Email of purchaser
* Order Number
* Subtotal (pre-tax, post-discount amount)
* Coupon code(s) used at checkout (can accept an array of strings if you allow for multiple coupons to
be applied at checkout)
* Currency ISO code. It is required for multi-currency sites.
* (optional) Shipping Address for additional fraud protection.
* (optional) Shopping cart line items. This is only necessary if segmenting based on cart contents.
* (optional) Segments (segment1, segment2, segment3). Custom attribute for segmenting purchases by value (e.g., location, age group, source channel, platform, gender, interests).
3. In case your business has one-time purchases and subscription model, or you are in SaaS
business we recommend integrating through Events. [Learn more](https://docs.talkable.com/advanced_features/events.md#advanced-features-events).
4. [Advocate Landing Page](#integration-standard-integration-components-advocate-landing-page).
Create an HTML page (URL path /share) with your standard site header and footer.
Add the Talkable Container DIV in the body. This tells Talkable where to inject content.
5. [Referral Dashboard (my account)](#integration-standard-integration-components-referral-dashboard).
Similar to the advocate landing page, create an HTML page that’s linked to from a menu in user accounts.
Add the Talkable Container DIV in the body. This tells Talkable where to inject content.
---
## Initialization Script
The Initialization script should be placed in the head template or some
template that spans every page. Talkable JS library size is typically
around 20kB and causes no noticeable impact to your site’s loading time.
All other integration components are dependent on the Initialization
script.
```html
```
In this example, segment1, segment2, and segment3 attributes are passed through authenticate_customer to enable segmentation without requiring an Origin creation.
> **Note:**
>
> Segments can also be passed in register_affiliate, register_purchase, and register_event, providing flexibility for different integration scenarios.
This approach simplifies custom data handling for customers, allowing for unified data across various methods and optimizing segmentation management without additional calls.
### Initialization Script Notes
1. **Site ID.** You can obtain your Site ID by logging into the Talkable
platform where Site ID is displayed on your Dashboard and URL as seen
here:
[Image]
2. **Variables.** Use your dynamic variables to pass user details {email,
first_name, last_name} if the user is logged in and the data
exists. If the data does not exist, you can pass a null value or a
blank string. If your website doesn’t have a user accounts section
and this info is never available, it’s acceptable to completely omit
the parameters, or pass empty strings.
---
## Post Purchase Script
The post purchase script should be placed on your checkout confirmation
page or any page that immediately follows checkout. All parameters can
be passed as strings. A Number can be passed for subtotal, however, if
using any calculation, you’re responsible for ensuring that some number is
passed where division by zero or null value does not occur.
```html
```
### Post Purchase Script Notes
1. Mandatory parameters must be passed or the purchase will not be
passed to Talkable. Mandatory parameters are: email, order_number, subtotal
2. coupon_code is not mandatory, but it’s preferred to be passed via the script, since some of the fraud checks and referral tracking methods rely on those
3. Shipping parameters are optional but gives the added benefit of
additional fraud protection
4. If you’re using a payment gateway that directs the user away from
your domain, you should ensure that some auto return feature is
enabled so that the user returns to the checkout confirmation page to
allow the post purchase script to run.
5. If you’re using a tag manager [click here](https://docs.talkable.com/integration/standard/integration_tag_manager.md#integration-standard-integration-tag-manager).
6. If you need to pass shopping cart line items, to see the alternate
post purchase integration script [click here](https://docs.talkable.com/advanced_features/product_items.md#advanced-features-product-items).
7. For individual purchase segmentation, you have the option to utilize one of three custom
segments: segment1, segment2, segment3.
These segments can represent various criteria such as location, age group, traffic source, etc.
> **Note:**
>
> All PII params support data encryption. Find more about [Params Encryption](https://docs.talkable.com/advanced_features/params_encryption.md#advanced-features-params-encryption).
## Advocate Landing Page
Create a new HTML page with URL path (www.your-site.com/share) and add the Talkable Container DIV
in the body of the page between your standard site header and footer:
> **Note:**
>
> The Talkable Container DIV id can be changed upon request to the Talkable team.
> The current DIV id value for each Event Category can be found on the Placements page.
```html
```
### Advocate Landing Page Notes
1. The Talkable Initialization script must be present in your head
template in order for the advocate landing page to work
2. Talkable will inject referral content where Talkable Container
resides in your DOM
3. URL Path: If you can’t use URL path www.your-site.com/share then
you’ll need to update the Site Placements section inside of Talkable
for the Invite Advocate Landing Page to match the exact URL path that
you intend to use via https://admin.talkable.com/sites//placements
[Image]
---
## Referral Dashboard
Similar to the Advocate Landing Page, create a new HTML page with URL
path (www.your-site.com/referrals) and add the Talkable Container DIV in
the body of the page:
> **Note:**
>
> The Talkable Container DIV id can be changed upon request to the Talkable team.
> The current DIV id value for each Event Category can be found on the Placements page.
```html
```
### Referral Dashboard Notes
1. The [Talkable Initialization Script](#integration-standard-integration-components-initialization-script) must be present in your head
template in order for the referral dashboard to work
2. Talkable will inject referral content where Talkable Container
resides in your DOM. Adding a new page is only a suggestion. The
dashboard can be added inline inside your user accounts menu, however
the dashboard content width for proper display is 980px.
3. **URL Path.** If you don’t host on www.your-site.com/referrals then
you’ll need to update the Site Placements section inside of Talkable
for the Dashboard Placement to use the exact URL path you intend to
host the Referral Dashboard on via https://www.talkable.com/sites//placements
4. **Linking to the Referral Dashboard.** Allow your users to reach the
Referral Dashboard by adding a link from any place that makes sense
considering your website configuration. Most common uses are links in
the user accounts section, or from the user accounts menu.
5. **Host on a page that’s only accessible behind login.** The Referral
Dashboard contains semi-sensitive information about an Advocate’s
referral history. If you don’t have user logins, then the Referral
Dashboard can be configured to display partially obfuscated data for
public access.
* [Alternate Post Purchase Script for cart line item passing](https://docs.talkable.com/integration/standard/alternate_post_purchase.md)
* [Integrating with a Tag Manager](https://docs.talkable.com/integration/standard/integration_tag_manager.md)
* [Potential Performance Impact](https://docs.talkable.com/integration/standard/integration_tag_manager.md#potential-performance-impact)
* [Best Practices for Speed Optimization](https://docs.talkable.com/integration/standard/integration_tag_manager.md#best-practices-for-speed-optimization)
* [Alternative Approach: Direct Integration](https://docs.talkable.com/integration/standard/integration_tag_manager.md#alternative-approach-direct-integration)
* [Verifying success](https://docs.talkable.com/integration/standard/integration_tag_manager.md#verifying-success)
* [Removing the Talkable Integration Script from GTM](https://docs.talkable.com/integration/standard/integration_tag_manager.md#removing-the-talkable-integration-script-from-gtm)
* [Helpful Links](https://docs.talkable.com/integration/standard/integration_tag_manager.md#helpful-links)
Source: https://docs.talkable.com/integration/standard/integration_tag_manager.md
===============================================================================
# Integrating with a Tag Manager
* Initialization Script in a Tag Manager: Place the [Initialization Script](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-initialization-script) in a tag that is
visible in the head template on all pages.
* Post Purchase Integration in a Tag Manager: Since the post
purchase integration on the checkout confirmation page requires the
Init script to work, you’re welcome to combine the [Initialization Script](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-initialization-script) + [Post Purchase Script](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-post-purchase-script) script into a
single tag for the checkout confirmation page. In fact this is
recommended for Google Tag Manager, when combining the place the
Initialization script on top/before the Post purchase script in the
tag.
* Tag Manager Data Layer to Pass Variables: You’ll need to
ensure a data layer object is set up to collect and pass the
variables to Talkable inside your tag.
* Troubleshooting: You can use window._talkableq for all talkableq variable instances if you’re having trouble with variable
interpolation and need to use a global namespace.
## Potential Performance Impact
This section addresses two key considerations for integrating Talkable using Google Tag Manager (GTM):
**1. Potential Performance Impact:**
* In some cases, using GTM to load the Talkable integration code can introduce a slight delay in the referral program’s functionality. This is because GTM typically waits for all its tags to load before executing them.
* If you’ve identified performance concerns related to the Talkable integration’s load time, consider the alternative approach outlined below.
**2. Safari Private Mode Blocking Third-Party Vendors:**
* A known issue exists where Safari in private mode blocks third-party vendors, including GTM. This can prevent the Talkable integration code from loading entirely, hindering the referral program’s operation.
## Best Practices for Speed Optimization
1. Make sure the campaign uses optimized image/file sizes and upload lower-resolution versions if it is.
2. There should be only one copy of the Initialization script on the page. Delete all duplicates if there are any.
3. Make sure you don’t have JS errors from code executed before Talkable. If there is some critical error, the browser may not be able to process Talkable scripts quickly.
4. Implementing a custom domain for your integration won’t directly increase its speed, but it will significantly reduce issues related to incognito mode and security policies blocking for third-party content.
> **Note:**
>
> If you use GTM, you can add [priority](https://support.google.com/tagmanager/answer/2772421) to the tag. The higher the priority, the quicker it gets loaded.
[Image]
## Alternative Approach: Direct Integration
To mitigate these potential issues, you can integrate Talkable directly into your web pages without using GTM. Here’s a step-by-step guide on [Custom Integration](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components).
**Benefits of Direct Integration:**
* **Improved Performance:** Eliminates the delay associated with GTM loading all tags before execution.
* **Enhanced Compatibility:** Ensures the Talkable integration code loads even in Safari private mode, where GTM might be blocked.
**Choosing the Right Approach:**
The optimal approach depends on your specific priorities:
* If performance is a critical concern, direct integration is generally recommended.
* If you prefer a more centralized tag management system for other integrations, GTM might still be suitable, but be aware of the potential performance impact and Safari private mode blocking.
**Additional Considerations:**
* Thoroughly test both approaches (GTM and direct integration) to ensure the Talkable referral program functions as expected in all browsers and scenarios.
* If you encounter further issues, check Talkable’s support resources or contact support team for assistance.
## Verifying success
1. Open Talkable admin, open or create Floating widget campaign. Scroll down to the Placements section and click on the eye button. It will open up your site with the Talkable campaign shown in test mode.
2. Submit purchase through your site.
3. Open Talkable admin, go to Reports → Purchases and find your purchase in the list.
4. Visit the Standalone page you created for the site, it should be showing up within 1-3 seconds.
## Removing the Talkable Integration Script from GTM
If you’ve decided to remove the Talkable integration script from GTM, follow these steps:
1. Log in to your Google Tag Manager account.
2. Locate the Talkable integration tag (usually named “Talkable Integration” or similar).
3. Click on the tag to open its details.
4. Click the “Delete” button to remove the Talkable integration tag.
**Important Note:** After removing the Talkable integration script from GTM, you’ll need to implement the [direct integration approach](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components) documented earlier to ensure Talkable functionality on your website.
> **Note:**
>
> Talkable doesn’t recommend adding integration as tags in Google Tag Manager because of slow loading of campaigns for certain user agents as well as GTM being blocked by some Ad blockers
## Helpful Links
* [How to make campaigns load faster?](https://talkable.freshdesk.com/support/solutions/articles/43000682297-how-to-make-campaigns-load-faster-)
* [How to integrate with a Tag Manager](https://talkable.freshdesk.com/support/solutions/articles/43000628861-how-to-integrate-with-a-tag-manager)
* [GTM tag prioritization](https://support.google.com/tagmanager/answer/2772421)
Source: https://docs.talkable.com/integration/standard/overview.md
===============================================================================
# Integration High-Level Overview
Integrating Talkable referral marketing platform to e-commerce sites is done in
a few quick steps by adding the below scripts to your site.
> **Note:**
>
> All design and referral campaign setup is done inside the Talkable platform,
> then via ‘iframe’ referral campaign content is injected into the e-commerce
> site. The below scripts also handle the collection of specific necessary user
> data for Talkable to service the referral campaigns.
>
> Site-specific integration scripts are found after logging in at `https://admin.talkable.com/sites//integration/other`
## Integration Steps
1. Add the [Talkable Initialization Script](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-initialization-script) to your header or any template spanning every page. Surface variables for
email and name if the user is logged in.
2. Add the [Talkable Post Purchase Script](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-post-purchase-script) to your checkout confirmation page to pass purchase details to Talkable for
all purchases.
Surface purchase detail variables as described in more detail in [Integration Components](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components).
> **Note:**
>
> If a business has both one-time purchases and subscription transactions, or
> the business has a strictly subscription or SaaS model we recommend integrating
> the ‘Post Purchase’ through Events. [Learn more](https://docs.talkable.com/advanced_features/events.md#advanced-features-events).
>
> Post Purchase step is the only step which changes for subscription business
> model integration - other steps remain the same.
3. To host the Invite Standalone campaign, create a new HTML page with standard
header/footer. Best practice is to create this page on `www.your-site.com/share`
The Invite Standalone campaign will be your landing page to drive traffic to
from marketing email and other onsite and offsite locations to refer friends.
Copy & paste the Talkable container DIV element into the body as seen in [Integration Components](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components).
```html
```
4. To host the Advocate Dashboard Standalone campaign, create an additional new
HTML page under your user accounts section behind login.
This Advocate Dashboard Standalone page allows Advocates to view referral
details for the friends they’ve shared with. Copy & paste the Talkable container
DIV element into the body as seen in [Integration Components](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components).
```html
```
Source: https://docs.talkable.com/integration/standard/questions.md
===============================================================================
# F.A.Q.
1. [Does the post purchase script need to capture all purchases or just Talkable purchases?](#integration-standard-questions-post-purchase-capture)
2. [How does referral tracking work?](#integration-standard-questions-how-does-referral-tracking-work)
3. [What does the Talkable integration do?](#integration-standard-questions-what-does-the-talkable-integration-do)
4. [How does Talkable know where to display content?](#integration-standard-questions-talkable-know-where-to-display-content)
5. [What do I, as a developer, need to do to complete integration?](#integration-standard-questions-complete-integration)
6. [How does the rewarding process work?](#integration-standard-questions-rewarding-process-work)
7. [How do I verify success?](#integration-standard-questions-verify-success)
**1. Does the post purchase script need to capture all purchases or
just Talkable purchases?**
The post purchase script needs to capture all purchases. This not only
simplifies the integration by removing any logic you need to perform on
your end to determine if a purchase is referral related but is required
so that Talkable can perform referral tracking which happens after the
purchase is captured. Talkable also reports on referral related sales
metrics to display what % of total sales referrals is responsible for
along with other sales related metrics.
**2. How does referral tracking work?**
Talkable automatically handles all referral tracking, so there’s nothing
special you need to do as a developer. Talkable tracks referrals by at
least 1 of 3 possible tracking methods: {cookie, coupon code, and
email}. The most common tracking method is cookie, so if your ecommerce
platform is unable to surface coupon code as a parameter to pass at
checkout, then that’s fine as Talkable will still be able to track the
referral.
**3. What does the Talkable integration do?**
* Displays Refer-A-Friend content inside a Talkable generated iframe
either as an overlay or inline
* Handles all button click events, and mobile responsive resizing
* Tracks referral attribution automatically
* Blocks self-referral and gaming of the system
* Handles all other referral related logic and communications
* Decides where to show content on your website based on rules
defined inside of the Talkable platform
* Sends referral p2p and reward emails on your behalf
**4. How does Talkable know where to display content?**
* “Placements” refer to areas of your website where referral content
should display. These rules are defined inside of the Placements
section inside the Talkable platform.
* You can modify default placements, add additional placements, or
create various inclusion or suppression rules in the Talkable
Placements section. This allows for future placement modification
with minimal to zero developer work required.
* See Talkable Placements documentation for more details: [Campaign Placements](https://docs.talkable.com/campaigns/campaign_placements.md#campaigns-campaign-placements)
* Talkable looks at the URL to determine display as defined by rules in
the Placements section. Most integrations will be able to use default
placements where no modification is necessary inside the Talkable
platform.
* Default Placements:
* Share Widget Campaign: All pages (inclusion and exclusion rules
can be defined)
* Post Purchase Popup Campaign: Checkout confirmation page where the
post purchase integration script resides.
* Advocate Landing Page Invite Campaign: URL ending in “/share”
* Referral Dashboard Campaign: URL ending in “/referrals”
**5. What work do I, as a developer, need to do to complete
integration?**
* Surface variables, plug into integration script, and copy into the
appropriate locations.
* Create HTML pages for Advocate Landing Page and Referral Dashboard
and paste the Talkable Container DIV in the body
* Create a link to the Referral Dashboard from your user accounts
section or drop down menu
* Validate your integration to verify success
* (optional) DNS configuration for referral link and email sending
subdomain white labeling (ask your Talkable contact to enable this)
**6. How does the rewarding process work?**
Referring Advocate Reward payout is configurable, it can be triggered
automatically based on any grace period delay, through API call when
considering returns, or through manual approval. Once a reward is
approved, Talkable sends an email that communicates/delivers the reward.
Most customers choose auto approval after a 24-48 delay, which requires
little to no attention.
Here’s how reward flow and logic works:
After Talkable tracks the referred purchase we run it through two sets
of filters: fraud filters, and then campaign qualifiers.
* Fraud filters will check for things such as self referral, cross
referral, similar email match, matching ip + device, matching
shipping address, etc.
* Campaign qualifiers are checked once fraud filters are passed. This
contains the campaign referral logic that determines when a reward is
due, such as: is the friend a new customer?, did the friend spend >
$X?, etc.
Reward approval
Once a referred purchase is qualified in passing through both of these
filters, the reward is now in a pending state and ready to be
approved/paid. Most companies turn on auto reward approval which will
auto approve the reward after some grace period. Approval can be
configured via API if return rate is abnormally high, but considering
that standard Advocate reward redemption rate is between 20-30% this is
typically not necessary.
API approval to account for returns
The way this works is that you would ping Talkable on all orders that
reach some final valid or failed state. This uses lazy logic so you
don’t need to know if a purchase is referral related or not, Talkable
will determine this. So any order# you ping us with that’s not related
to a pending referral, we’ll gracefully ignore, and any order# we
recognize as related to a pending referral, we’ll take the appropriate
action.
**7. How do I verify success?**
Refer to the section titled [Validating the Integration](https://docs.talkable.com/integration/standard/validating_integration.md#integration-standard-validating-integration).
Source: https://docs.talkable.com/integration/standard/validating_integration.md
===============================================================================
# Validating the Integration
## Visual Confirmation Note
In order to see visual confirmation you must create or have existing
Talkable campaigns. Campaigns must be enabled for visual display (see
examples below on how to enable campaigns). Note that enabling campaigns
on production will allow your customers to see referral content. If you
want to limit visual display, or want to validate on your production
site without customers seeing visual display, then see the [Test Mode Display](#integration-standard-validating-integration-test-mode-display) section below.
## Validation Checklist
1. Perform a test checkout.
**Confirm Visual Result** You should see visual confirmation content
on the checkout confirmation page if the post purchase campaign is enabled.
**Confirm Data Result** Navigate to Reports > Purchases tab inside
the Talkable platform to ensure all parameters that you’re using
in the post purchase script are being passed. Data populates in real time.
2. Visit your Home Page.
**Confirm Visual Result** You should see the floating Talkable Widget button.
3. Visit your Advocate Landing Page.
**Confirm Visual Result** You should see visual confirmation content
in the location where you placed the Talkable Container DIV.
4. Visit your Referral Dashboard Page.
**Confirm Visual Result** You should see visual confirmation content
in the location where you placed the Talkable Container DIV.
## How to create or check for existing campaigns
You’ll need to have a campaign of each type in order to validate
display.
There are 5 types:
1. Post Purchase: displays as a pop up after checkout
2. Floating Widget: displays as a floating widget button on your home
page (and every page)
3. Invite Standalone: displays inline on your /share advocate landing
page
4. Advocate Dashboard Standalone: displays inline in your /referrals
page
5. Claim by Name displays as a floating widget button on your checkout page.
> **Note:**
>
> Claim by Name campaign has its own DIV container and can be shown along with the Floating Widget on the same page.
> The DIV id is talkable-claim-by-name.
* How to create campaigns: Here’s a video showing you how to quickly
create all campaigns in less than 1 minute [https://youtu.be/HDK-zFlCAkw](https://youtu.be/HDK-zFlCAkw)
* How to enable campaigns: Here’s a video showing you how to enable
campaigns (ignore any warnings for now and note the site display placement) [https://youtu.be/HgR6WQYeASg](https://youtu.be/HgR6WQYeASg)
## Test Mode Display
After creating campaigns, while still in test mode before activating,
you can append a URL query string parameter to page where you want to display
a campaign in test mode which prevents anyone else from seeing visual display.
Note that each campaign has campaign ID under the campaign name and you can reference
these in the URL using the following guidelines:
1. Floating widget on your homepage:
www.your-site.com?tkbl_campaign_id=11111
2. Advocate Landing Page /share:
www.your-site.com/share?tkbl_campaign_id=11112
3. Referral Dashboard:
www.your-site.com/referrals?tkbl_campaign_id=11113
4. Claim by Name widget:
www.your-site.com/cart?tkbl_campaign_id=11114 or www.your-site.com/checkouts?tkbl_campaign_id=11114
Note that campaigns must be newly created campaigns in test mode to be
eligible for test mode display. Use the following image as a visual
guideline:
[Image]
Source: https://docs.talkable.com/integration/verify.md
===============================================================================
# Verifying Integration
After installing Talkable, you should verify that the integration is working:
1. Open your homepage (assuming the Talkable init script is placed on every page,
otherwise visit the page where the initialization script was placed)
with a secret URL parameter like so:
https://www.site.com/?tkbl_verify_integration=true.
As a result you should see:
[Image]
2. Issue a test purchase. Order subtotal should be > 0,
email should be integration@talkable.com. Preferably include a coupon code so we
can verify it gets passed as well. As a result you should see:
[Image] Talkable verification dialog only appears to you, it will not be shown to anyone else.
All purchases with integration@talkable.com email will not be recorded inside Talkable.
## Verifying Integration in JS SPAs
In case you are unable to pass **?tkbl_verify_integration=true** URL parameter you can alternatively turn Talkable into “Verification mode” by setting:
talkable.config.verify_integration = true;
All requests will now be coming with “Verification” flag turned on.
**Note:** do not use it in production, this mode is for debugging purpose only.
## Troubleshooting
In case you are not seeing the verification popup please make sure the [init script](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-initialization-script) (non-platform integration only)
is installed on the page. You may do so by making right click
(Chrome) → Inspect Element → Inside Elements tab press Cmd+F (Ctrl+F on Windows) and
search for d2jj → make sure the init script matches the one provided inside your
Integration tab inside Talkable Admin.
If you see the init script on the page, but the verification popup still does
not appear on the screen, make sure a request is was passed to Talkable.
To do that open
Network tab (Chrome) → refresh the page → inside Search bar look
up for “create.html”. Make sure you see something like:
[Image]
If the request is coming through but you are still not seeing the verification
popup please contact Talkable support: [support@talkable.com](mailto:support%40talkable.com).
Source: https://docs.talkable.com/ios_sdk.md
===============================================================================
# Talkable iOS SDK
Talkable has an iOS framework enabling you to use Talkable in iOS Apps. Once integrated you can use the following Talkable capabilities:
* Display Advocate Signup/Share Page (the page itself is built inside Talkable)
* Share Offer via:
* Email
* Facebook
* Twitter
* SMS
* by copying a direct Offer link
* Track sales via the App and reward Advocate if a sale was driven thourgh someone’s claim link
## Contents:
* [Getting Started](https://docs.talkable.com/ios_sdk/getting_started.md)
* [Requirements](https://docs.talkable.com/ios_sdk/getting_started.md#requirements)
* [Step 1: Installation](https://docs.talkable.com/ios_sdk/getting_started.md#step-1-installation)
* [Step 2: Configuration](https://docs.talkable.com/ios_sdk/getting_started.md#step-2-configuration)
* [Integration](https://docs.talkable.com/ios_sdk/integration.md)
* [Standalone Campaign](https://docs.talkable.com/ios_sdk/integration/standalone.md)
* [Post Purchase Campaign](https://docs.talkable.com/ios_sdk/integration/post_purchase.md)
* [Custom Events](https://docs.talkable.com/ios_sdk/integration/event.md)
* [Social Sharing](https://docs.talkable.com/ios_sdk/social_sharing.md)
* [Social Sharing from a web-based campaign](https://docs.talkable.com/ios_sdk/social_sharing.md#social-sharing-from-a-web-based-campaign)
* [Legacy Sharing using Social.framework](https://docs.talkable.com/ios_sdk/social_sharing.md#legacy-sharing-using-social-framework)
* [Social Sharing from a native campaign](https://docs.talkable.com/ios_sdk/social_sharing.md#social-sharing-from-a-native-campaign)
* [Native Integration via API](https://docs.talkable.com/ios_sdk/api_integration.md)
* [1. Create an Origin](https://docs.talkable.com/ios_sdk/api_integration.md#create-an-origin)
* [2. Create a Share](https://docs.talkable.com/ios_sdk/api_integration.md#create-a-share)
* [3. Check for Reward](https://docs.talkable.com/ios_sdk/api_integration.md#check-for-reward)
* [Extra Functionality](https://docs.talkable.com/ios_sdk/api_integration.md#extra-functionality)
* [React Native](https://docs.talkable.com/ios_sdk/react_native.md)
* [How it works](https://docs.talkable.com/ios_sdk/react_native.md#how-it-works)
* [What to expect](https://docs.talkable.com/ios_sdk/react_native.md#what-to-expect)
* [Reusing the SDK’s API wrapper (optional)](https://docs.talkable.com/ios_sdk/react_native.md#reusing-the-sdk-s-api-wrapper-optional)
* [Advanced Usage](https://docs.talkable.com/ios_sdk/advanced.md)
* [Specify a custom campaign tag](https://docs.talkable.com/ios_sdk/advanced.md#specify-a-custom-campaign-tag)
* [Implement TalkableDelegate](https://docs.talkable.com/ios_sdk/advanced.md#implement-talkabledelegate)
* [Notifications](https://docs.talkable.com/ios_sdk/advanced.md#notifications)
* [Contacts Import](https://docs.talkable.com/ios_sdk/advanced.md#contacts-import)
* [Debugging](https://docs.talkable.com/ios_sdk/advanced.md#debugging)
* [Integration with Third Party Deep Linking Services](https://docs.talkable.com/ios_sdk/custom_deep_linking.md)
* [1. Configure your Talkable campaign](https://docs.talkable.com/ios_sdk/custom_deep_linking.md#configure-your-talkable-campaign)
* [2. Pass deep linking params to the Talkable SDK](https://docs.talkable.com/ios_sdk/custom_deep_linking.md#pass-deep-linking-params-to-the-talkable-sdk)
* [Example](https://docs.talkable.com/ios_sdk/example.md)
Source: https://docs.talkable.com/ios_sdk/advanced.md
===============================================================================
# Advanced Usage
## Specify a custom campaign tag
By default if no campaign tag was specified, SDK uses ios-invite and ios-post-purchase tags for [Standalone](https://docs.talkable.com/ios_sdk/integration/standalone.md#ios-sdk-integration-standalone) and [Post Purchase](https://docs.talkable.com/ios_sdk/integration/post_purchase.md#ios-sdk-integration-post-purchase) campaigns. But you can explicitly specify your own tag in this way:
```objc
#import
// ...
[[Talkable manager] registerOrigin:TKBLAffiliateMember params:@{TKBLCampaignTags: @"your-custom-tag"}];
```
## Implement TalkableDelegate
1. Assign your ViewController or other object as Talkable delegate by using the following code:
```objc
[[Talkable manager] setDelegate: yourObjectConformsToTalkableDelegateProtocol];
```
2. Take control of presenting offers to your users. Use the next two delegate methods to prevent
or give an instruction as to where you want that offer to be displayed:
```objc
- (BOOL)shouldPresentTalkableOfferViewController:(UIViewController*)controller;
- (UIViewController*)viewControllerForPresentingTalkableOfferViewController;
```
3. Customize ViewContoller title by implementing the method below. By default, title of offer page is used.
```objc
- (NSString*)titleForTalkableOfferViewController:(UIViewController*)controller;
```
> **Note:**
>
> You can modify page title on a Talkable Site during campaign development.
4. Present offers to your users by yourself by handling request url or webView after origin was created.
```objc
- (void)didRegisterOrigin:(TKBLOriginType)type withURL:(NSURL*)url;
- (void)didRegisterOrigin:(TKBLOriginType)type withWebView:(WKWebView*)webView;
```
> **Note:**
>
> Talkable SDK assigns itself to WKWebView navigation delegate. Changing WKWebView navigation delegate
> may break some functionality so we strictly recommend not doing this.
5. Manage cases where origin wasn’t created or offer hasn’t been presented.
```objc
- (void)registerOrigin:(TKBLOriginType)type didFailWithError:(NSError*)error;
```
> **Note:**
>
> userInfo may contain detailed information about the error.
6. Receive notification when the user taps Facebook or Twitter sharing button in the WebView and trigger
corresponding sharing view.
```objc
- (void)showFacebookShareDialogWithParams:(NSDictionary*)params delegate:(id)delegate;
- (void)showFacebookShareDialogWithParams:(NSDictionary*)params completion:(void (^)())completionHandler;
- (void)showTwitterShareDialogWithParams:(NSDictionary*)params completion:(void (^)())completionHandler;
```
> **Note:**
>
> See [Social Sharing](https://docs.talkable.com/ios_sdk/social_sharing.md#ios-sdk-social-sharing) for details.
## Notifications
Subscribe to notifications that Talkable SDK publish and be aware of everything that happens around your campaigns.
1. Receive the coupon given to your users:
```objc
#import
// ...
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(couponReceived:) name:TKBLDidReceiveCouponCode object:nil];
// ...
- (void)couponReceived:(NSNotification*)ntf {
// Your logic here
}
```
2. Catch every message from presented offer:
```objc
#import
// ...
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(publishMessageNotification:) name:TKBLDidPublishMessageNotification object:nil];
// ...
- (void)publishMessageNotification:(NSNotification*)ntf {
if ([[[ntf userInfo] objectForKey:TKBLMessageNameKey] isEqualToString:TKBLMessageOfferLoaded]) {
// Your logic here
}
}
```
Available messages:
* TKBLMessageOfferLoaded
* TKBLMessageOfferClose
* TKBLMessageCouponIssued
## Contacts Import
It is possible to import contacts from a device with the SDK, so they will be accessible at the Share page with JavaScript.
The button at the Share page for contacts importing should have `class="js-import-contacts"` property.
Also, contacts usage description is required on iOS 10+ devices. It should be described under the `NSContactsUsageDescription` key
in the `Info.plist` file of your app. This message will be shown when asking for contacts permissions.
```xml
NSContactsUsageDescription
Share the offer with your Friends from contacts
.. note::
Talkable SDK asks for the contacts permissions dynamically only when "contacts import" functionality is implemented
in the campaign and Advocate presses the corresponding button at the Share page for the first time.
```
## Debugging
See all debugging information in your console which can help you to understand what is going wrong:
```objc
#import
// ...
[Talkable manager].debug = YES;
```
Source: https://docs.talkable.com/ios_sdk/api_integration.md
===============================================================================
# Native Integration via API
Talkable provides an API that can be utilized to implement a fully native referral program interface if you don’t want to use
included WKWebView-based functionality. Below are the methods necessary to integrate the Talkable referral loop into your iOS app.
## 1. Create an Origin
The Origin is a user event (e.g. a purchase or simply opening the app) that initiates the referral chain.
Create an Origin to retrieve an Offer and display it to an [Advocate](https://docs.talkable.com/campaigns.md#campaigns).
To create an Origin, make a request to [Origins API](https://www.talkable.com/api-docs/#/Origins/createOrigin) using the `createOrigin:withHandler:` method.
If the request is successful, the `handler` block will receive attributes of created Origin and [Offer](https://www.talkable.com/api-docs/#/Advocate%20Offers/findAdvocateOffer) entities.
```objc
NSDictionary* originParams = @{
TKBLOriginTypeKey: TKBLOriginTypePurchase,
TKBLOriginDataKey: @{
TKBLPurchaseEmailKey: @"test@example.com",
TKBLPurchaseSubtotalKey: @"17.43",
TKBLPurchaseOrderNumberKey: @"100125",
@"campaign_tags": @"your-campaign-tag"
}
};
[[Talkable manager] createOrigin:originParams withHandler:^(NSDictionary* response, NSError* error) {
NSDictionary* offerParams = [response objectForKey:TKBLOfferKey];
NSDictionary* claimLinks = [offerParams objectForKey:@"claim_links"];
}];
```
## 2. Create a Share
Sharing an Offer is the next step in the referral chain. You will need the `short_url_code` of the Offer obtained from a previous request.
```objc
NSString* shortUrlCode = [offerParams objectForKey:TKBLOfferShortUrlCodeKey];
```
### Native sharing
The `nativeShare:` method will display a native iOS sharing dialog. When content is shared,
the share will be automatically registered with Talkable and reflected on your dashboard.
```objc
UIActivityViewController* sheet = [[Talkable manager] nativeShare:@{
TKBLOfferShortUrlCodeKey: shortUrlCode,
TKBLOfferClaimUrlKey: [claimLinks objectForKey:TKBLShareChannelOther]
}];
[self presentViewController:sheet animated:YES completion:^{}];
```
### Social sharing
Use frameworks provided by social networks to share your offer. Upon a successful share,
call the `createSocialShare:channel:withHandler:` method to register the share with Talkable
via [Shares API](https://www.talkable.com/api-docs/#/Shares/shareViaSocialChannel).
```objc
[[Talkable manager] createSocialShare:shortUrlCode channel:TKBLShareChannelOther withHandler:^(NSDictionary* response, NSError* error) {
NSDictionary* rewardParams = [response objectForKey:@"reward"];
}];
```
#### Facebook example
```objc
MyFBSDKDelegateClass* delegate = [self myFBSDKDelegate];
delegate.shortUrlCode = shortUrlCode;
FBSDKShareLinkContent *content = [[FBSDKShareLinkContent alloc] init];
content.contentURL = [NSURL URLWithString:[params objectForKey:[claimLinks objectForKey:TKBLShareChannelFacebook]]];
[FBSDKShareDialog showFromViewController:self
withContent:content
delegate:delegate];
// ...
@implementation MyFBSDKDelegateClass
@synthesize shortUrlCode;
- (void)sharer:(id)sharer didCompleteWithResults:(NSDictionary *)results {
if (_shortUrlCode != nil)
[[Talkable manager] createSocialShare:_shortUrlCode
channel:TKBLShareChannelFacebook
withHandler:^(NSDictionary* response, NSError* error) {...}];
}
@end
```
#### Twitter example
```objc
TWTRComposer *composer = [[TWTRComposer alloc] init];
[composer setText:[params objectForKey:TKBLShareMessage]];
[composer showFromViewController:self completion:^(TWTRComposerResult result) {
if (result == TWTRComposerResultDone) {
[[Talkable manager] createSocialShare:shortUrlCode
channel:TKBLShareChannelTwitter
withHandler:^(NSDictionary* response, NSError* error) {...}];
}
}];
```
> **Note:**
>
> This method will be called automatically when you use `socialShare:` or `nativeShare:` methods.
### Legacy social sharing
The legacy `socialShare:` method was used prior to v1.4.9 and is provided for backwards compatibility.
It will attempt to display a sharing dialog directly using the deprecated Social.framework.
Only the Facebook sharing channel is currently supported.
```objc
SLComposeViewController* sheet = [[Talkable manager] socialShare:@{
TKBLShareChannel:TKBLShareChannelFacebook,
TKBLOfferClaimUrlKey:[claimLinks objectForKey:TKBLShareChannelFacebook],
TKBLShareMessage:@"Personalized message",
TKBLOfferShortUrlCodeKey:shortUrlCode
}];
[self presentViewController:sheet animated:YES completion:^{}];
```
> **Warning:**
>
> Starting with v1.4.9, this method is deprecated and offers only limited Facebook sharing support.
> Native sharing or custom implementation based on Facebook/Twitter SDK should be used instead.
> See [Social Sharing](https://docs.talkable.com/ios_sdk/social_sharing.md#ios-sdk-social-sharing) for details.
### Email Share
To share an Offer via email, simply use the `createEmailShare:recipients:withParams:andHandler:` method to send an API request.
Talkable will send the emails for you. You will need to provide an interface for the user to specify recipients’ email addresses, a subject, and a personal message.
```objc
NSString* recipients = @"customer@example.com,elon@musk.com"; // comma separated email addresses
NSDictionary* emailShareParams = @{
@"subject": @"Custom Email Subject",
@"body": @"Personal message that will be added to the email body",
@"reminder": NO // Whether Talkable should send a reminder email later
};
[[Talkable manager] createEmailShare:shortUrlCode recipients:recipients withParams:emailShareParams andHandler:^(NSDictionary* response, NSError* error) {
// process delivery stats
}];
```
## 3. Check for Reward
If a Talkable campaign is configured to give a reward to the Advocate just for sharing, the call to [Shares API](https://www.talkable.com/api-docs/#/Shares/shareViaEmail) will return a [Reward](https://www.talkable.com/api-docs/#/Rewards) you can display immediately. In most cases, however, the Advocate will receive a reward after
a Friend responds to a shared link, e.g. makes a purchase.
To check whether the current user has any outstanding rewards, use the `retrieveRewardsWithHandler:` method.
```objc
[[Talkable manager] retrieveRewardsWithHandler:^(NSDictionary* response, NSError* error) {
NSArray *rewards = (NSArray *)[response objectForKey:@"rewards"];
}];
```
## Extra Functionality
### Retrieve an Offer by Short Code
If you need to access an Offer for the Origin you’ve created earlier, store the offer’s `short_url_code` and then use `retrieveOffer:withHandler:` method
to fetch the Offer.
```objc
[[Talkable manager] retrieveOffer:shortUrlCode withHandler:^(NSDictionary* response, NSError* error) {
NSDictionary* offerParams = [response objectForKey:TKBLOfferKey];
}];
```
Source: https://docs.talkable.com/ios_sdk/custom_deep_linking.md
===============================================================================
# Integration with Third Party Deep Linking Services
Talkable can work with third party deep linking providers such as GetSocial, Branch.io, and Firebase. Talkable is able to use deep linking functionality to track app installations and reward your Advocates and Friends for installing your mobile app on their phones.
Deep linking services provide a special referral link that can be given to Advocates to be shared with their Friends. Once opened on a Friend’s mobile device, this link will not only redirect them to the App Store to install the app, but also track that the app was installed using a referral link. Deep linking can also be used to send a Friend to a specific place in the app once it’s installed and opened for the first time, show them personalized messages, and more.
## 1. Configure your Talkable campaign
To use deep linking with Talkable campaigns, simply use your deep link URL as your Talkable Site URL.
[Image]
> **Note:**
>
> If you have configured a custom Friend Destination URL for your campaign, make sure the following GET parameters
> are present in the final URL: `?tkbl_cvuuid={{ visitor_uuid }}&talkable_visitor_offer_id={{ friend_offer.id }}`.
>
> All major deep linking providers support passing additional GET parameters with the deep link.
> This functionality is used to pass the Friend’s identifying information to the Talkable SDK in your iOS app.
> To use this functionality with Firebase, refer to this document: [Manually constructing a Dynamic Link URL](https://firebase.google.com/docs/dynamic-links/create-manually).
## 2. Pass deep linking params to the Talkable SDK
Retrieve deep linking params as described in your deep linking provider’s documentation
and pass these params to the Talkable SDK using `handleOpenURL:` or `handleURLParams:` method.
Use `handleURLParams:` method if you have a `NSDictionary` with params passed to the deep link handler block (Branch.io, GetSocial).
```objc
// For Branch.io
[[Branch getInstance] initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) {
[[Talkable manager] handleURLParams:params];
}];
```
> **Note:**
>
> Most deep linking services provide additional parameters in the deep link handler to indicate whether the app was installed
> on this device for the first time, reinstalled or simply launched. You can use these params to register installs
> only when desired conditions are met.
```objc
// For GetSocial
[GetSocial referralDataWithSuccess:^(GetSocialReferralData * _Nullable referralData) {
if ([referralData isFirstMatch]) {
[[Talkable manager] handleURLParams:[referralData linkParams]];
}
} failure:^(NSError * _Nonnull error) {}];
```
Use `handleOpenURL:` method if you handle deep link as `NSURL` using the standard `application:openURL:options:` method (Firebase).
```objc
// For Firebase
- (BOOL)application:(UIApplication *)app
openURL:(NSURL *)url
options:(NSDictionary *)options {
[[Talkable manager] handleOpenURL:url];
}
```
Calling either of these methods will register the app installation event in Talkable and complete the referral cycle.
You can then use the [retrieveRewardsWithHandler:](https://docs.talkable.com/ios_sdk/api_integration.md#ios-sdk-api-integration) method to check for rewards or subscribe
to a corresponding [notification](https://docs.talkable.com/ios_sdk/advanced.md#ios-sdk-advanced-notifications).
Source: https://docs.talkable.com/ios_sdk/example.md
===============================================================================
# Example
In case you want to take a look at the actual code and see it in action we created a demo project that covers nearly all Talkable possibilities. To download Talkable Demo iOS project click [here](https://talkable-downloads.s3.amazonaws.com/ios-sdk/talkable_sdk_demo.zip). Once downloaded please proceed to [configuration](https://docs.talkable.com/ios_sdk/getting_started.md#ios-sdk-getting-started) step to set up your API Key and Talkable Site Slug.
If you have any questions, don’t hesitate to email us at [support@talkable.com](mailto:support%40talkable.com). Happy hacking!
Source: https://docs.talkable.com/ios_sdk/getting_started.md
===============================================================================
# Getting Started
The Getting Started guide shows you how to setup and launch Referral Campaign as quickly as possible with Talkable iOS SDK.
## Requirements
* Talkable SDK supports iOS *9.0* and later
* Add the -ObjC option to **Other Linker Flags** in the **Build Settings** tab
## Step 1: Installation
Talkable SDK could be integrated using [Swift Package Manager](#swift-package-manager), [CocoaPods](#cocoapods) or manually as a [Binary Framework](#binary-framework).
### Swift Package Manager
Installing from Xcode:
1. Add a package by selecting **File** → **Add Packages…** in Xcode’s menu bar.
2. Search for the Talkable SDK using the repo’s URL:
```bash
https://github.com/talkable/ios-sdk.git
```
3. Set the **Dependency Rule** to be Up to Next Major Version and specify 1.5.1 as the lower bound (default option).
4. Select **Add Package** and choose TakableSDK package.
Alternatively, you can add Talkable SDK directly to a Package.swift manifest:
```swift
dependencies: [
.package(url: "https://github.com/talkable/ios-sdk.git", .upToNextMajor(from: "1.5.1"))
]
```
### CocoaPods
To integrate Talkable SDK into your Xcode project using CocoaPods, specify it in your [Podfile](https://guides.cocoapods.org/using/the-podfile.html):
```ruby
pod 'TalkableSDK', '~> 1.5.1'
```
### Binary Framework
To integrate the SDK manually as a Binary Framework, please follow next intructions:
1. Download the latest version of [Talkable SDK](https://talkable-downloads.s3.amazonaws.com/ios-sdk/talkable_ios_sdk.zip).
2. Navigate to your project settings by clicking on it in the project navigator.
3. Make sure that your target is selected and **General** tab is open.
4. Go to **Frameworks, Libraries, and Embedded Content** section and add the SDK by clicking **“+”** button → **Add Other…** → **Add Files…** and locate the downloaded SDK.
5. For **Embed** setting of the added framework select Do Not Embed option.
6. Make sure that Talkable SDK is linked with your project in **Link Binary With Libraries** section under **Build Phases** tab with Required Status.
It should already be included by default after following the steps above, however in case it’s not – click on the **“+”** button and add it.
## Step 2: Configuration
1. Initialize Talkable SDK in your application:didFinishLaunchingWithOptions: method, like so:
```objc
#import
// ...
[[Talkable manager] setApiKey:@"YOUR_TALKABLE_PUBLIC_API_KEY" andSiteId:@"YOUR_SITE_ID"];
```
> **Note:**
>
> You can locate your credentials inside Talkable site:
>
> * Select site and go to **Dashboard** → **Settings** → **Site Settings** → **Integrations**.
> Find **API integration** section and there you will see your API Keys and Site ID.
> Use only the *Public API Key* in your application submitted to the App Store.
2. Register URL scheme for Talkable:
* Defines tkbl-YOUR-SITE-ID as URL Scheme in your Info.plist file:
```xml
CFBundleURLTypes
CFBundleURLSchemes
tkbl-YOUR-SITE-ID
```
* Add tkbl-YOUR-SITE-ID scheme to the list of schemes that are queried within application. Also add fb-messenger, fbauth2, whatsapp schemes if you are going to utilize these sharing channels:
```xml
LSApplicationQueriesSchemes
tkbl-YOUR-SITE-ID
fb-messenger
fbauth2
whatsapp
```
> **Note:**
>
> Please replace YOUR-SITE-ID with your actual Site ID.
> Make sure to keep tkbl- prefix in the value. For example,
> if your site ID is my-store, the correct value is tkbl-my-store.
3. Add following lines to application:openURL:options:
```objc
#import
// ...
[[Talkable manager] handleOpenURL:url];
```
Your environment is all set up! Now you can [integrate](https://docs.talkable.com/ios_sdk/integration.md#ios-sdk-integration) the Talkable campaign piece.
Source: https://docs.talkable.com/ios_sdk/integration.md
===============================================================================
# Integration
> **Important:**
>
> Before integrating SDK campaigns into your app, make sure you have campaigns properly configured
> in Talkable. See [SDK Campaign Setup](https://docs.talkable.com/campaigns/tutorials/sdk_campaign_setup.md#campaigns-tutorials-sdk-campaign-setup) for complete
> campaign setup guide including tags, native sharing, and mobile optimization.
The SDK is installed and configured. Now you can integrate Standalone and/or Post Purchase campaigns into your mobile app.
* [Standalone Campaign](https://docs.talkable.com/ios_sdk/integration/standalone.md#ios-sdk-integration-standalone)
* [Post Purchase Campaign](https://docs.talkable.com/ios_sdk/integration/post_purchase.md#ios-sdk-integration-post-purchase)
* [Custom Events](https://docs.talkable.com/ios_sdk/integration/event.md#ios-sdk-integration-event)
* [Standalone Campaign](https://docs.talkable.com/ios_sdk/integration/standalone.md)
* [Post Purchase Campaign](https://docs.talkable.com/ios_sdk/integration/post_purchase.md)
* [Custom Events](https://docs.talkable.com/ios_sdk/integration/event.md)
Source: https://docs.talkable.com/ios_sdk/integration/event.md
===============================================================================
# Custom Events
In addition to Signup and Purchase incentives, Talkable campaigns can utilize [custom events](https://docs.talkable.com/advanced_features/events.md#advanced-features-events) to issue rewards based on other actions performed by Advocates and Friends, such as purchasing a subscription, completing a game level, or simply visiting a certain place in your app. Register an event every time the user performs the desired action in your app.
An Event has two required properties: event category and event number. Please refer to [available properties](https://docs.talkable.com/advanced_features/events.md#advanced-features-events-available-properties) for a complete list of optional properties.
```objc
#import
// ...
NSDictionary* params = @{
TKBLCampaignTags: @"your-campaign-tag",
TKBLEventKey: @{
TKBLEventCategoryKey: @"subscription_purchased",
TKBLEventNumberKey: [[NSUUID UUID] UUIDString] //must be unique for given category
}
};
[[Talkable manager] registerOrigin:TKBLEvent params:params];
```
If you have a Talkable offer configured for this event, the Talkable campaign screen will be displayed as a result of calling the `registerOrigin` method.
> **Warning:**
>
> Unlike the default [Standalone](https://docs.talkable.com/ios_sdk/integration/standalone.md#ios-sdk-integration-standalone) and [Post Purchase](https://docs.talkable.com/ios_sdk/integration/post_purchase.md#ios-sdk-integration-post-purchase) integrations, the event-based integration will not automatically use the default campaign tag (`ios-invite` or `ios-post-purchase` respectively). To match your events to the desired Talkable campaign, you **must** specify the correct campaign tag when creating an event.
Customer data can be added to the registered event. Custom properties passed with the event will be added to the customer profile.
```objc
#import
// ...
NSDictionary* params = @{
TKBLCampaignTags: @"your-campaign-tag",
TKBLEventKey: @{
TKBLEventEmailKey: @"customer@example.com",
TKBLEventCategoryKey: @"subscription_purchased",
TKBLEventNumberKey: self.orderNumberField.text,
TKBLEventPersonCustomPropertiesKey: @{
@"property_key": @"property_value"
}
}
}
};
[[Talkable manager] registerOrigin:TKBLEvent params:params];
```
Please refer to the [Integrating Events](https://docs.talkable.com/advanced_features/events.md#advanced-features-events) page to learn more about event-based campaigns.
Source: https://docs.talkable.com/ios_sdk/integration/post_purchase.md
===============================================================================
# Post Purchase Campaign
Now that we know what a Standalone campaign is, let’s take a look at one more type of Talkable campaign — Post Purchase. It is used to convert your existing customers into Advocates after they make a purchase. It has the same flow as a basic Standalone campaign except this is gated by a purchase and shown to a customer immediately after.
Post Purchase campaign usually looks like a pop up right after a user made a purchase. This campaign is initialized on the order confirmation page and captures order with its details. You need to pass order data to Talkable that includes your customer’s email address, order number, subtotal, coupon code used at checkout to allow Talkable detect and close a referral loop.
Here is an example of a Purchase capturing, this action should be triggered on the order confirmation page:
```objc
#import
// ...
NSDictionary* params = @{
TKBLPurchaseKey: @{
TKBLPurchaseOrderNumberKey: @"100130", // REQUIRED - Order number
TKBLPurchaseEmailKey: @"customer@example.com", // REQUIRED - Customer Email
TKBLPurchaseSubtotalKey: [NSNumber numberWithDouble:22.33], // REQUIRED - Purchase Subtotal
TKBLPurchaseCouponCodeKey: @"TEST25", // REQUIRED - Coupon code used at checkout, pass multiple as an array: @[@"SAVE20", @"FREE-SHIPPING"]. Pass @"" if there is no coupon code.
TKBLPurchaseOrderItemsKey:@[
@{
TKBLPurchaseOrderItemProductIDKey: @"sku3", // Item Product ID
TKBLPurchaseOrderItemPriceKey: [NSNumber numberWithDouble:4.99], // Item Unit Price
TKBLPurchaseOrderItemQuantityKey: [NSNumber numberWithUnsignedInt:5], // Item Quantity
TKBLPurchaseOrderItemTitleKey: @"Amazing Product 3", // Name of the product
TKBLPurchaseOrderItemUrlKey: @"http://www.store.com/product2", // URL of the product page
TKBLPurchaseOrderItemImageUrlKey: @"http://www.store.com/product2/image.jpg" // URL of the product image
}
]
}
};
[[Talkable manager] registerOrigin:TKBLPurchase params:params];
```
> **Note:**
>
> If Post Purchase campaign does not show up when testing, make sure you have it
> Live on the Campaigns listing with a default tag (ios-post-purchase) or with
> a tag you specified in the registerOrigin call.
Source: https://docs.talkable.com/ios_sdk/integration/standalone.md
===============================================================================
# Standalone Campaign
> **Note:**
>
> For information about setting up campaigns to work with iOS SDK, including campaign tags,
> native sharing, and mobile optimization, see [SDK Campaign Setup](https://docs.talkable.com/campaigns/tutorials/sdk_campaign_setup.md#campaigns-tutorials-sdk-campaign-setup).
Let’s take a look at how the Standalone campaign integration looks. The main purpose of this type of campaign is to drive your users to invite their friends (to become Advocates) without being gated by a purchase beforehand.
Usually Standalone campaign look like a separate widget that people can access by clicking on the “Invite friends” button inside app navigation.
Once you’ve got a Standalone campaign set up inside Talkable you can integrate the campaign with the following line of code:
```objc
#import
// ...
[[Talkable manager] registerOrigin:TKBLAffiliateMember params:nil];
```
> **Note:**
>
> Make sure you have at least one Live “SA” campaign inside Talkable Site with a default tag (ios-invite) or with a tag you specified in the registerOrigin call
Note that params are empty, in this case user will see Signup form on [Advocate Signup/Share Page](https://docs.talkable.com/campaigns/views/offers_show.md#campaigns-views-offers-show), which is used to collect the user’s email address. Your application may already know/have access to the user’s email, if so, you should pass this parameter which will automatically skip the Signup Form in the flow and show Share form immediately [Advocate Signup/Share Page](https://docs.talkable.com/campaigns/views/offers_show.md#campaigns-views-offers-show). You have the ability to pass any custom data you think might be useful by using “person custom properties” to define any number of custom key/value pairs. For example, below we are creating and passing a custom key value pair of *eye color* = *green*. Any data passed through here will be accessible on a campaign level for segmentation or other logic.
```objc
#import
// ...
NSDictionary* params = @{
TKBLAffiliateMemberKey: @{
TKBLAffiliateMemberEmailKey: @"advocate@example.com",
TKBLAffiliateMemberFirstNameKey: @"John",
TKBLAffiliateMemberLastNameKey: @"Smith",
TKBLAffiliateMemberPersonCustomPropertiesKey: @{
@"eye_color": @"green"
}
}
};
[[Talkable manager] registerOrigin:TKBLAffiliateMember params:params];
```
Source: https://docs.talkable.com/ios_sdk/react_native.md
===============================================================================
# React Native
Talkable supports React Native apps through the Talkable API. You build the referral program
interface in your React Native app and connect it to Talkable using the API. The Friend Claim
Page is hosted by Talkable.
The iOS SDK documented in this section is a framework for native iOS apps. If your app is
built with React Native, use the Talkable API instead of embedding the SDK. The steps below
describe how.
## How it works
The referral flow is the same as any Talkable API integration.
See [Referral Program via API](https://docs.talkable.com/api_v2/flow.md#api-v2-flow) for the full walkthrough.
In your React Native app you:
* Generate a Talkable Offer for the Advocate.
* Let the Advocate share the Offer via social network or email.
* Let the Friend claim the Offer on the Claim (Landing) page after following the share URL.
* Let Talkable know about a Purchase or Event so it can close the referral chain and trigger the reward.
Reference docs:
* [Referral Program via API](https://docs.talkable.com/api_v2/flow.md#api-v2-flow) — the end-to-end integration flow.
* [API Introduction](https://docs.talkable.com/api_v2/intro.md#api-v2-intro) — base URL, authentication, response and error formats.
* [Origins](https://docs.talkable.com/api_v2/origins.md#api-v2-origins) — the Purchase or Event reporting that triggers rewards.
## What to expect
* You build the referral UI in React Native, using your own components and branding.
* Talkable provides the referral functionality via the API: offers, shares, attribution, and rewards.
* There is no React Native package to install.
You integrate using the API, and the same integration works for both iOS and Android.
## Reusing the SDK’s API wrapper (optional)
The iOS SDK also provides helper methods that call the Talkable API for you — creating an
Origin, sharing an Offer, and retrieving offers and rewards. These are documented in [Native Integration via API](https://docs.talkable.com/ios_sdk/api_integration.md#ios-sdk-api-integration), with Objective-C examples for
each step.
You do not need the SDK to integrate React Native; calling the API directly requires no
native dependency. You can bridge these helper methods into React Native if you prefer. [Native Integration via API](https://docs.talkable.com/ios_sdk/api_integration.md#ios-sdk-api-integration) is also a useful reference for the
same Origin, Share, and Reward steps if you call the API directly.
Source: https://docs.talkable.com/ios_sdk/social_sharing.md
===============================================================================
# Social Sharing
Talkable iOS SDK provides the functionality to facilitate sharing offers via social networks.
Older versions of the SDK prior to 1.4.9 used Apple-provided Social.framework to implement
sharing to Facebook and Twitter. Starting with version 1.4.9, usage of Social.framework is
officially deprecated following Apple’s decision to deprecate the framework.
We still provide limited support of Social.framework to ensure the stability of legacy implementations.
However, developers are encouraged to use Facebook and Twitter SDKs to enable sharing to these platforms.
This article describes how to use the Talkable SDK with social sharing in various scenarios.
## Social Sharing from a web-based campaign
The default Talkable iOS integration utilizes WebView to display web-based campaign views in your app.
If you have Facebook or Twitter available on your sharing page, the Talkable iOS SDK will automatically
detect when the user clicks on the share button and trigger one of the corresponding delegate methods
(see [Talkable Delegate](https://docs.talkable.com/ios_sdk/advanced.md#ios-sdk-advanced-delegate)).
### showFacebookShareDialogWithParams:delegate:
```objc
- (void)showFacebookShareDialogWithParams:(NSDictionary*)params delegate:(id)delegate;
```
This method is called when the user clicks on the ‘Facebook Share’ button.
The `params` dictionary contains information on the content being shared and will have the following keys:
* `TKBLOfferClaimUrlKey` - the link URL to share
* `TKBLShareMessage` - the message to share
The `delegate` param is a delegate object that conforms to Facebook iOS SDK `SharingDelegate` protocol.
Pass this object as a `delegate:` param when sharing the link using FBSDK to automatically notify the Talkable SDK
that sharing was completed successfully. Talkable SDK will then register the share with Talkable so that you can see it
in your Talkable Dashboard.
### Example
```objc
- (void)showFacebookShareDialogWithParams:(NSDictionary *)params delegate:(id)delegate {
FBSDKShareLinkContent *content = [[FBSDKShareLinkContent alloc] init];
content.contentURL = [NSURL URLWithString:[params objectForKey:TKBLOfferClaimUrlKey]];
[FBSDKShareDialog showFromViewController:self
withContent:content
delegate:delegate];
}
```
### showFacebookShareDialogWithParams:completionHandler:
```objc
- (void)showFacebookShareDialogWithParams:(NSDictionary*)params completion:(void (^)())completionHandler;
```
This method is also called when the user clicks on the ‘Facebook Share’ button, but instead of `delegate` param it
provides the `completionHandler` block that should be called when sharing is completed successfully. Use
this method if you already have a delegate object that you use for Facebook sharing.
Pass the `completionHandler` block to the delegate object and call it in your `sharer:didCompleteWithResults:` method.
### Example
```objc
- (void)showFacebookShareDialogWithParams:(NSDictionary *)params completion:(void (^)())completionHandler {
MyFBSDKDelegateClass* delegate = [self myFBSDKDelegate];
delegate.talkableCompletionHandler = completionHandler;
FBSDKShareLinkContent *content = [[FBSDKShareLinkContent alloc] init];
content.contentURL = [NSURL URLWithString:[params objectForKey:TKBLOfferClaimUrlKey]];
[FBSDKShareDialog showFromViewController:self
withContent:content
delegate:delegate];
}
// ...
@implementation MyFBSDKDelegateClass
@synthesize talkableCompletionHandler;
- (void)sharer:(id)sharer didCompleteWithResults:(NSDictionary *)results {
if ((_talkableCompletionHandler) != nil)
_talkableCompletionHandler();
}
@end
```
### showTwitterShareDialogWithParams:completionHandler:
```objc
- (void)showTwitterShareDialogWithParams:(NSDictionary*)params completion:(void (^)())completionHandler;
```
This method is called when the user clicks on the Twitter Share button. The `params` and `completionHandler` attributes are analogous to the previous method.
### Example
```objc
- (void)showTwitterShareDialogWithParams:(NSDictionary *)params completion:(void (^)())completionHandler {
TWTRComposer *composer = [[TWTRComposer alloc] init];
[composer setText:[params objectForKey:TKBLShareMessage]];
[composer showFromViewController:self completion:^(TWTRComposerResult result) {
if (result == TWTRComposerResultDone) {
completionHandler();
}
}];
}
```
## Legacy Sharing using Social.framework
Prior to v1.4.9, the TalkableSDK used Social.framework to automatically display Facebook and Twitter sharing dialog
when the user clicks on on a corresponding button. This type of sharing relied on functionality built into iOS, and did not
require the use of additional SDKs. Staring with iOS 11, Apple deprecated this way of sharing and now requires
developers to utilize frameworks provided by Facebook and Twitter.
While Social.framework is officially deprecated, Talkable SDK still supports a limited subset of its functionality
to ensure a seamless transition to new implementations.
* If Talkable Delegate doesn’t implement either of the two Facebook methods,
TalkableSDK will attempt to trigger Facebook share via Social.framework.
* Facebook sharing popup will only be displayed if Facebook app is installed on a customer’s phone, otherwise it will
silently fail.
* Twitter sharing is not supported by Social.framework anymore.
> **Note:**
>
> Talkable iOS SDK v1.4.9 features improved support of legacy Facebook sharing via Social.framework. If you are having trouble
> with your current implementation, please upgrade to the latest version. Note that we can only try to provide the best
> transitioning experience, and this fallback should not be regarded as a permanent solution. We encourage developers to switch
> to delegate methods for social sharing.
## Social Sharing from a native campaign
The methods documented above are designed to work with web-based campaigns only. If you have integrated using our API,
please refer to the [Sharing](https://docs.talkable.com/ios_sdk/api_integration.md#ios-sdk-api-integration-sharing) section of the Native Integration page.
Source: https://docs.talkable.com/web_hooks.md
===============================================================================
# Webhooks
Webhooks are “user-defined HTTP callbacks” triggered by events on Talkable’s
site. Subscribing to Talkable Webhooks allows you to receive notifications about
various events from Talkable, for example, when a Reward should be given, or
when a Friend or Advocate opts in to an email newsletter subscription.
After subscribing to a Webhook, your app can execute code immediately after
specific events occur in Talkable.
[https://en.wikipedia.org/wiki/Webhook](https://en.wikipedia.org/wiki/Webhook)
Each Webhook in Talkable is defined with an HTTP URL to deliver Webhook data
(aka payload). This URL should be defined and implemented on the client’s site.
> **Note:**
>
> Talkable now provides a more flexible and powerful way to handle events with the Custom App.
> We strongly recommend [migrating your existing Webhooks to Custom App](https://docs.talkable.com/web_hooks/migration_to_custom_app.md#web-hooks-migration-to-custom-app) to take advantage of centralized configuration, customizable payloads, and greater overall flexibility.
## Available Webhooks
Below is a user experience flow showing when Talkable Webhooks are called.
For more details concerning specific Talkable Webhooks, click the appropriate
Webhook type in the left-hand menu.
[Image]
> **Note:**
>
> The Reward Webhooks will only send if there is an associated incentive
> configured. For example, for the ‘Reward Webhook’ (reason = signup) to send,
> there must be a signup incentive configured in the campaign rules.
## Set Up
[Image]
1. Set up and test Talkable Webhooks by navigating to **Menu** then **Webhooks**
2. Proceed to **Create New Webhook**
3. Choose a Webhook from the dropdown and provide your endpoint URL
4. From here, Send Sample, Edit, Delete or Create New
5. Take note of your Talkable security key. This key will be the same for all
Talkable Webhooks on a given site. Talkable includes a key parameter in
Webhooks which are unique to each site as a way to identify Talkable as
an authorized server. Your Talkable Webhook security key can be found in
the Webhook set up page.
Talkable Webhooks will trigger automatically based on associated events defined
by Webhook type.
## Testing
Testing webhooks 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 site on Webhooks set up page.
3. Click **New**.
4. Select webhook type.
5. Paste your Webhook Tester URL and save.
6. Click **Deliver Sample** near the webhook you want to test.
7. After you finish the implementation on your site **change Webhook Tester URL
to the live URL** on your site.
8. Click **Deliver Sample** to test webhook with Live URL.
## Data
All Webhooks are delivered as an HTTP Post request with the main parameter
called payload. All data inside this parameter is encoded as JSON. Below is
a PHP parameter decode example:
```php
json_decode($_POST["payload"])
```
## Parsing Timestamps
**Timestamp data type** is not a part of JSON standard. Timestamps
are passed as strings in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) compatible format. To function properly, ensure
your date parser is compatible to this standard. Java users go here:
[https://stackoverflow.com/questions/2201925/converting-iso-8601-compliant-string-to-java-util-date](https://stackoverflow.com/questions/2201925/converting-iso-8601-compliant-string-to-java-util-date)
## Response Codes
Talkable considers a Webhook as “delivered successfully” when a site
server returns a **2xx response status**. Otherwise Talkable will continually
retry to deliver a Webhook after a set interval of time.
## HTTP Responses and Their Meanings
* 2xx: Success
* 200: OK
* 201: Created
* 202: Accepted
* 203: Non Authoritative Information
* 204: No Content
* 205: Reset Content
* 206: Partial Content
If you have a problem on your server, you can answer with code 500. If there is
some problem in our request (problem on Talkable’s side), you can answer
“400 Bad Request”.
Talkable will retry delivery of Webhook if any other error code is received.
## Security Key
Talkable includes a `key` parameter in Webhooks which are unique to each site
as a way to identify Talkable as an authorized server. Your Talkable Webhook
security key can be found in the Webhook set up page.
## Type
The `type` parameter of a Webhook request can be used to identify which Webhook
is received without looking at the payload. This will be useful if you point multiple
Webhooks to the same URL; for instance, for data collection purposes.
Possible types are:
* `referral_web_hook`
* `create_coupon_web_hook`
* `post_share_web_hook`
* `offer_signup_web_hook`
* `claim_signup_web_hook`
* `reward_web_hook`
* `unsubscribe_web_hook`
* `check_unsubscribe_web_hook`
* `event_web_hook`
## Site
Every Webhook has a `site` parameter that identifies which Talkable site sent
this request. This is useful if you have a multi-site setup or use a staging site.
## Whitelisting Talkable IPs
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:
| 100.26.94.244
18.207.91.200
18.210.165.17
18.232.203.127
18.233.48.151
184.73.206.68
23.21.155.129 | 3.222.226.72
34.197.54.191
34.226.253.236
34.231.104.179
34.232.247.192
35.169.186.170
35.171.77.58 | 35.173.87.187
44.217.136.252
44.219.211.174
50.16.143.102
50.17.244.178
52.204.148.18
52.22.0.55 | 52.6.41.1
52.7.94.243
54.164.128.44
54.208.14.192
54.86.208.153
54.86.241.218
54.91.51.228 | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ## Compatibility and Versioning Talkable Webhooks do not currently incorporate versioning. Current spec will not be changed for all existing hooks. Note that Talkable may add additional data elements to existing Webhooks, but should not remove or change existing data elements. --- See available Webhooks on the navigation sidebar. * [Create Coupons](https://docs.talkable.com/web_hooks/create_coupon.md) * [Referral](https://docs.talkable.com/web_hooks/referral.md) * [Reward](https://docs.talkable.com/web_hooks/reward.md) * [Post Share](https://docs.talkable.com/web_hooks/post_share.md) * [Advocate Signup](https://docs.talkable.com/web_hooks/offer_signup.md) * [Friend Email Gating](https://docs.talkable.com/web_hooks/claim_signup.md) * [Unsubscribe](https://docs.talkable.com/web_hooks/unsubscribe.md) * [Check Unsubscribe](https://docs.talkable.com/web_hooks/check_unsubscribe.md) * [Event](https://docs.talkable.com/web_hooks/event.md) * [Migration from Webhooks to Custom App](https://docs.talkable.com/web_hooks/migration_to_custom_app.md) * [How Custom App enhances or replaces Webhooks](https://docs.talkable.com/web_hooks/migration_to_custom_app.md#how-custom-app-enhances-or-replaces-webhooks) * [Webhooks vs Custom App](https://docs.talkable.com/web_hooks/migration_to_custom_app.md#webhooks-vs-custom-app) * [Transition from Webhooks to Custom App](https://docs.talkable.com/web_hooks/migration_to_custom_app.md#transition-from-webhooks-to-custom-app) Source: https://docs.talkable.com/web_hooks/check_unsubscribe.md =============================================================================== # Check Unsubscribe Webhook Talkable Check Unsubscribe Webhook is used to ensure emails are not sent from Talkable to user email addresses who have unsubscribed from the client side. This is an optional functionality. Note: users do have the ability to unsubscribe from Talkable referral related emails at any time from those emails directly. ## When does Talkable call the Check Unsubscribe Webhook? Talkable Check Unsubscribe Webhook is triggered on every attempt to send an otherwise valid customer email, aimed at checking if the email is also valid on merchant side. > **Important:** > > The ‘unsubscribed’ field should have a boolean value, > representing unsubscribed status according to the merchant info. ## Payload parameters provided The sample payload with parameters for Check Unsubscribe Webhook is available here: [Check Unsubscribe Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Check%20Unsubscribe/post_your_api_check_unsubscribe_web_hook_path). ### View categories View category can be one of the following: * notifier_offers_email * notifier_offers_share_via_email * notifier_offers_share_via_email_reminder * advocate_rewards_confirmation * advocate_rewards_paid * friend_rewards_paid Source: https://docs.talkable.com/web_hooks/claim_signup.md =============================================================================== # Friend Email Gating Webhook The Talkable Friend Email Gating Webhook notifies your endpoint that a Friend Email Gating form was submitted (on Friend Claim Page). Use cases for the Friend Email Gating Webhook include: * Tracking when users select the checkbox to opt into your email newsletter * Collection of data for Business Intelligence and analytics systems to track users who become Friends * Sending automated ‘Thank You’ or ‘Don’t forget to shop’ emails after a Friend passes the email gating form ## When does Talkable call the Friend Email Gating Webhook? Talkable Friend Email Gating Webhook is triggered any time an Friend Email Gating form is submitted. This is the form a Friend completes after receiving a share from an Advocate, and before receiving their discount code. Friend Email Gating form example: [Image] ## Payload parameters provided The sample payload with parameters for Friend Email Gating Webhook is available here: [Friend Email Gating Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Friend%20Email%20Gating/post_your_api_claim_signup_web_hook_path). Source: https://docs.talkable.com/web_hooks/create_coupon.md =============================================================================== # Create Coupon Webhook Talkable Create Coupon Webhook enables automatic coupon creation, which eliminates the need to upload coupon lists into the Talkable platform manually. Talkable creates unique coupon codes then passes those codes via the Create Coupon Webhook to the client; it is then up to the client to enable these coupons on their platform. > **Note:** > > Create Coupon Webhook and [Shopify Coupon auto-sync](https://docs.talkable.com/advanced_features/shopify_coupons_auto_sync.md#advanced-features-shopify-coupons-auto-sync) can be enabled simultaneously. > In that case, coupons will be passed via the webhook only after successful Shopify sync. ## When does Talkable call the Create Coupon Webhook? Create Coupon Webhook is called when the quantity of available coupons drops below a Talkable threshold. This threshold is dynamically calculated based on the number of coupon codes used by the client site in the last 21 days. The threshold ensures the Talkable coupon lists will always hold enough available coupons to serve the site for 21 days, even if the integration were to break. The minimum threshold is 20 coupons. When the number of coupons available to Talkable drops below the threshold, Talkable will call the Create Coupon Webhook with a payload of 15 new coupons in the background. If a user needs a coupon code, but there are no coupon codes available, Talkable will generate one in the foreground and give it to the user that requested it. In both cases, coupons are sent to the client endpoint as a webhook and then inserted into the Talkable database only when a webhook returns a successful response. ## Set Up The Create Coupon Webhook will add coupons to a specific coupon list on Talkable’s backend. These coupon lists must be set up in the Talkable campaign editor before utilizing the Create Coupon Webhook. Follow the below instructions to set up a coupon list for a campaign: 1. Navigate to **Campaigns** then select the campaign you would like to set up coupon list(s) for 2. Proceed to **Rules** then scroll down to **Incentives** section where incentives for both Advocate and Friend can be configured [Image] 3. Inside the Referral Incentive Editor choose the **Coupon code type: Single-use** then select an existing Coupon list or create a new coupon list by clicking **Manage Coupon Lists**. 4. Here you’ll be able to **Create New** and configure a Name, Expiration Date (optional), and Amount ($ or %) 5. Now go back to **Rules** → **Incentives** → **Edit** and select the **Reward Amount** associated with the list created in step 4 and select the newly created list 6. Optionally, select **Advanced Settings** for additional configuration parameters > **Note:** > > Coupons created by the **Create Coupon Webhook** will be added to the coupon > list associated with the referral campaign. Multiple referral campaigns can > use the same or unique coupon lists. **Advocate** and **Friend** referral > incentives can also use the same or unique coupon lists. Once a single-use coupon code list is associated with a campaign, then the Create Coupon Webhook can now be set up. [Learn more about General Webhook Set Up Steps](https://docs.talkable.com/web_hooks.md#web-hooks) ## Payload parameters provided by Create Coupon Webhook The sample payload with parameters for Create Coupon Webhook is available here: [Create Coupon Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Create%20Coupon/post_your_api_create_coupon_web_hook_path). Source: https://docs.talkable.com/web_hooks/event.md =============================================================================== # Event Webhook The Talkable Event Webhook notifies your endpoint that an [Event](https://docs.talkable.com/advanced_features/events.md#advanced-features-events) or a [Purchase](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-post-purchase-script) has been registered with Talkable. Use cases for the Event Webhook include: * Capturing purchases and custom referral events generated by the customer (e.g. added data to profile or renewed a subscription) * Tracking coupon codes used for purchases * Using Talkable events to trigger custom workflows (e.g. add a custom property to a customer who just cancelled a subscription) ## When does Talkable call the Event Webhook? Talkable calls the Event Webhook any time an Event or a Purchase is registered either via [the front-end Talkable integration](https://docs.talkable.com/advanced_features/events.md#advanced-features-events) or using the [Talkable backend API](https://docs.talkable.com/api_v2/origins.md#api-v2-origins). ## Payload parameters provided The sample payload with parameters for Event Webhook is available here: [Event Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Event/post_your_api_event_web_hook_path). Source: https://docs.talkable.com/web_hooks/migration_to_custom_app.md =============================================================================== # Migration from Webhooks to Custom App The transition from Webhooks to [Custom App](https://docs.talkable.com/email_marketing_and_automation/custom_app.md#email-marketing-and-automation-custom-app) provides a more flexible approach to integrate Talkable events with your systems. This guide outlines the key improvements, differences, and step-by-step instructions to help you successfully migrate to the new Custom App architecture. ## How Custom App enhances or replaces Webhooks Webhooks are useful for triggering HTTP requests based on specific Talkable events, but they have limitations, such as: * Each event type requires a separate webhook configuration. * Only one webhook can be set per event. * Payload customization is not supported. Custom App overcomes these limitations by providing: * A single endpoint to manage multiple events, reducing setup complexity. * Built-in testing tools for verifying event payloads before production use. * Customizable payload with a wide range of data variables. * Conditional execution with Liquid criteria for each event. By migrating from webhooks to [Custom App](https://docs.talkable.com/email_marketing_and_automation/custom_app.md#email-marketing-and-automation-custom-app), businesses can streamline their data integration processes and reduce maintenance overhead. ## Webhooks vs Custom App | Feature | Webhooks | Custom App | | ------------------------- | ---------------------------------------- | ---------------------------------------------------------- | | **Flexibility** | Fixed event-based triggers | Supports custom event handling | | **Configuration** | Requires manual endpoint setup per event | Centralized configuration in Talkable UI | | **Customizable Payload** | Limited or manual payload manipulation | Flexible payload configuration via UI | | **Conditional Execution** | Not supported out of the box | Allows event triggers based on custom rules and conditions | ### Transition from Webhooks to Custom App To transition from webhooks to the [Custom App](https://docs.talkable.com/email_marketing_and_automation/custom_app.md#email-marketing-and-automation-custom-app), follow these steps: 1. Review Current Webhooks * Identify the webhooks currently used in your system (e.g., Sync signups, Send reward, Referral status change). * Note the payload structure and data sent to each endpoint. 2. Install and Configure Custom App * Follow the Set Up instructions below to install and enable the Custom App. * Configure the same actions as your existing webhooks. 3. Test Custom App Actions * Use the Webhook Tester to confirm that data is sent correctly. * Compare payloads from the Custom App to ensure they match what was previously received via webhooks. 4. Disable Legacy Webhooks * Once the Custom App is fully functional, deactivate the old webhooks in the Talkable settings. * Ensure all integrations are working smoothly before making the final switch. Source: https://docs.talkable.com/web_hooks/offer_signup.md =============================================================================== # Advocate Signup Webhook The Talkable Advocate Signup Webhook notifies your endpoint of an Advocate Signup forms submission. Use cases for the Advocate Signup Webhook include: * Tracking when users select the checkbox to opt into your email newsletter * Collection of data for Business Intelligence and analytics systems to track users who become Advocates * Sending automated ‘Thank You’ emails after a user becomes an Advocate ## When does Talkable call the Advocate Signup Webhook? Talkable Signup Webhook is triggered any time an Advocate Signup Form is submitted. The Advocate Signup Form is the standard Name & Email (with optional email subscription checkbox) fields a user submits before becoming an Advocate and sharing an offer with Friends. Advocate Signup Form example: [Image] ## Payload parameters provided for Advocate Signup Webhook The sample payload with parameters for Advocate Signup Webhook is available here: [Advocate Signup Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Advocate%20Signup/post_your_api_advocate_signup_web_hook_path). Source: https://docs.talkable.com/web_hooks/post_share.md =============================================================================== # Post Share Webhook Talkable Post Share Webhook provides notification of a share event performed within a referral campaign workflow. Use cases for the Post Share Webhook include: * Sending automated ‘Thank You’ email to an Advocate for performing a share * Any event that should be triggered when a user shares * Data for Business Intelligence and analytics systems ## When does Talkable call the Post Share Webhook? Talkable Post Share Webhook is triggered any time an Advocate (referrer) shares offer details with a Friend (referee) via the corresponding form provided by campaign workflow. Which includes any time: * An advocate shares with a Friend via Email or any other channel from inside a referral campaign workflow * An Advocate copies a share link from a referral campaign workflow share screen > **Note:** > > The Post Share Webhook triggers every time a share occurs. For example, if an Advocate shares with a Friend via email (or any channel), then shares with a second Friend via email (or any channel), the Post Share Webhook will be triggered twice. ## Payload parameters provided for Post Share Webhook The sample payload with parameters for Post Share Webhook is available here: [Post Share Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Post%20Share/post_your_api_post_share_web_hook_path). > **Note:** > > `origin.email` contains the email saved at the moment when the campaign is > first shown to the Advocate. It could be `null`. For the most up-to-date > information about the Advocate, use `sharer_info` property which is updated > with the email address the Advocate has entered on the Advocate Signup/Share Page. Source: https://docs.talkable.com/web_hooks/referral.md =============================================================================== # Referral Webhook The Talkable Referral Webhook notifies your endpoint that an Advocate referral status has become “Approved” specifically for a Friend purchase or event. “Approved” referral status signifies the following: * Neither Advocate nor Friend are blocked by email or IP * Advocate passed enabled fraud checks and is considered non-fraudulent Use cases for the Referral Webhook include: * Providing account credit or account upgrades to an Advocate as a reward * Giving non-monetary rewards such as physical gifts to an Advocate * Sending automated ‘Thank You’ emails after a reward is given to an Advocate * Data for business intelligence or analytics systems to track when Advocates receive rewards > **Note:** > > “Approved” referral status does not guarantee that Advocate will receive a reward. Things that can prevent Advocate or Friend from being rewarded: * Share wasn’t active at the moment of referral event creation * Advocate Referral Incentive rewards limit (per month or in total) has been reached * Coupon cycling has been detected (when Friend uses Advocate’s coupon in referred event) * Incentive criteria does not match * Rewards issuing is not allowed for auto-approved referrals > **Important:** > > Referral Webhook keeps retrying until it gets 2xx HTTP status in response. > Only after that rewards associated with the referral can be paid. ## When does Talkable call the Referral Webhook? Talkable Referral Webhook is triggered any time an Advocate referral status has become “Approved” specifically for a Friend purchase or event. > **Note:** > > Referral Webhook triggers only for Advocate rewards specifically from a Friend > Purchase or Friend Event (such as signup event or subscription purchase event). > To receive notification of both Advocate and Friend rewards use the Rewards Webhook. ## Payload parameters provided for Referral Webhook The sample payload with parameters for Referral Webhook is available here: [Referral Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Referral/post_your_api_referral_web_hook_path). ## Coupon codes as a reward > **Important:** > > If referral campaigns are set-up to reward either Friends or Advocates with > Talkable provided coupon codes, then the Reward Webhook is called for > informational purposes only. It is a notification that the reward has been > provided. Note, Talkable gets these coupons either by manual upload from the > Dashboard, or if configured, Talkable will call the [Create Coupon Webhook](https://docs.talkable.com/web_hooks/create_coupon.md#web-hooks-create-coupon) to generate additional coupons > automatically. ## Incentive types Incentives can be of 3 following general types. * **Rebate** (rebate) — monetary reward, certain amount of money that should be paid out to a customer with a given email. The merchants’ payment system should handle the payment. * **Coupon code** (discount_coupon) — a discount coupon is issued to user. Talkable handles distributing this type of incentives. * **Non-monetary** (other) — used when a campaign has a non-monetary rebate like *“Free T-shirt”* or *“One Month Free”*. This should be handled on the merchant’s side. More information on the reward is specified in incentive_description. Source: https://docs.talkable.com/web_hooks/reward.md =============================================================================== # Reward Webhook The Talkable Reward Webhook notifies your endpoint that a reward is ready to be, or has been given. A reward can be for either an Advocate or for a Friend. Talkable Reward Webhook notifications allow your application to know when to reward users by means other than the standard ‘give them a coupon code’ method. Use cases for the Reward Webhook include: * Providing account credit or account upgrades to a user as a reward * Giving non-monetary rewards such as physical gifts * Sending automated ‘Thank You’ emails after a reward is given to a user * Any event that should trigger at the moment a user has earned a reward ## When does Talkable call the Reward Webhook? Talkable calls the Reward Webhook any time a reward is ready to be, or has been given to either an Advocate or a Friend according to the logic set-up in a Talkable referral campaign. Possible events which will trigger the Reward Webhook are: * Advocate Signup Form submitted (Reason = **signup**) * Advocate shares an offer with Friend(s) (Reason = **shared**) * Friend passes email gating form (Reason = **click**) > **Note:** > > If campaign is setup without email gating form, Reward Webhook with > Reason = click will trigger when Friend clicks through to site. * Friend makes eligible purchase (Reason = **referrer**) * Friend makes eligible purchase (Reason = **referred**) > **Note:** > > Reason = referrer indicates a reward should be given to an Advocate. > Reason = referred indicates a reward should be given to a Friend. ## Set-Up Because the Reward Webhook will trigger at various events depending on the Incentive configuration for each referral campaign, to trigger the Reward Webhook we first must ensure Incentives are correctly configured. To configure incentives: 1. Navigate to **Campaigns** then select the campaign you would like to configure incentives for 2. Proceed to **Rules** then scroll down to **Incentives** section where incentives for both Advocates and Friends can be set-up [Image] 3. Configure the incentives as desired inside the Referral Incentive Editor. To configure Incentive types other than Coupon Codes, please contact your Talkable Customer Success Manager; they will be able to set up “Rebate (store credit)” type incentives and “Non-Monetary” type incentives. > **Note:** > > If there is a delay configured into when the Advocate reward is approved then > the Reward Webhook trigger when the Advocate reward is ready to be, or has > been given. For example, if campaigns are set to send an Advocate their reward > three days after a Friend makes an eligible purchase, then the Reward Webhook > will be called three days after the Friend makes the eligible purchase. You > can select these delays under **Fraud Settings**, which is found under **Menu**. Once incentives are configured for a referral campaign, Talkable will then call the Reward Webhook any time either an Advocate or a Friend should receive a reward. Now, the Reward Webhook can be set-up. [Learn more about General Webhook Set Up Steps](https://docs.talkable.com/web_hooks.md#web-hooks) ## Payload parameters provided by Reward Webhook The sample payload with parameters for Reward Webhook is available here: [Reward Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Reward/post_your_api_reward_web_hook_path). ## Reasons Reward reason can be of 5 following general types. * **signup** — Advocate reward for sign-up (Advocate Signup Form submitted) * **shared** — Advocate reward for sharing an offer with Friend(s) * **click** — Friend reward for visiting claim page (and optionally passing gating) * **referrer** — Advocate reward for eligible referral purchase by Friend * **referred** — Friend reward for eligible referral purchase by themselves ## Incentive types Incentives can be of 3 following general types. * **Rebate** (rebate) — monetary reward, certain amount of money that should be paid out to a customer with a given email. The merchants’ payment system should handle the payment. * **Coupon code** (discount_coupon) — a discount coupon is issued to user. Talkable handles distributing this type of incentives. * **Non-monetary** (other) — used when a campaign has a non-monetary rebate like *“Free T-shirt”* or *“One Month Free”*. This should be handled on the merchant’s side. More information on the reward is specified in incentive_description. ## Coupon codes as a reward > **Important:** > > If referral campaigns are set-up to reward either Friends or Advocates with > Talkable provided coupon codes, then the Reward Webhook is called for > informational purposes only. It is a notification that the reward has been > provided. Note, Talkable gets these coupons either by manual upload from the > Dashboard, or if configured, Talkable will call the [Create Coupon Webhook](https://docs.talkable.com/web_hooks/create_coupon.md#web-hooks-create-coupon) to generate additional coupons > automatically. Source: https://docs.talkable.com/web_hooks/unsubscribe.md =============================================================================== # Unsubscribe Webhook Talkable Unsubscribe Webhook provides notification of a user unsubscribing from Talkable sent referral email. Use cases for the Unsubscribe Webhook include: * Unsubscribing users from in-house marketing newsletters when user unsubscribes from Talkable referral emails * Any event that should be triggered when a user unsubscribes from Talkable referral emails ## When does Talkable call the Unsubscribe Webhook? Talkable Unsubscribe Webhook is called any time a user unsubscribes from a Talkable sent email. ## Payload parameters provided The sample payload with parameters for Unsubscribe Webhook is available here: [Unsubscribe Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Unsubscribe/post_your_api_unsubscribe_web_hook_path). --- ## Summary Total documents aggregated: 175 Generated by talkable-llm-txt
18.207.91.200
18.210.165.17
18.232.203.127
18.233.48.151
184.73.206.68
23.21.155.129 | 3.222.226.72
34.197.54.191
34.226.253.236
34.231.104.179
34.232.247.192
35.169.186.170
35.171.77.58 | 35.173.87.187
44.217.136.252
44.219.211.174
50.16.143.102
50.17.244.178
52.204.148.18
52.22.0.55 | 52.6.41.1
52.7.94.243
54.164.128.44
54.208.14.192
54.86.208.153
54.86.241.218
54.91.51.228 | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ## Compatibility and Versioning Talkable Webhooks do not currently incorporate versioning. Current spec will not be changed for all existing hooks. Note that Talkable may add additional data elements to existing Webhooks, but should not remove or change existing data elements. --- See available Webhooks on the navigation sidebar. * [Create Coupons](https://docs.talkable.com/web_hooks/create_coupon.md) * [Referral](https://docs.talkable.com/web_hooks/referral.md) * [Reward](https://docs.talkable.com/web_hooks/reward.md) * [Post Share](https://docs.talkable.com/web_hooks/post_share.md) * [Advocate Signup](https://docs.talkable.com/web_hooks/offer_signup.md) * [Friend Email Gating](https://docs.talkable.com/web_hooks/claim_signup.md) * [Unsubscribe](https://docs.talkable.com/web_hooks/unsubscribe.md) * [Check Unsubscribe](https://docs.talkable.com/web_hooks/check_unsubscribe.md) * [Event](https://docs.talkable.com/web_hooks/event.md) * [Migration from Webhooks to Custom App](https://docs.talkable.com/web_hooks/migration_to_custom_app.md) * [How Custom App enhances or replaces Webhooks](https://docs.talkable.com/web_hooks/migration_to_custom_app.md#how-custom-app-enhances-or-replaces-webhooks) * [Webhooks vs Custom App](https://docs.talkable.com/web_hooks/migration_to_custom_app.md#webhooks-vs-custom-app) * [Transition from Webhooks to Custom App](https://docs.talkable.com/web_hooks/migration_to_custom_app.md#transition-from-webhooks-to-custom-app) Source: https://docs.talkable.com/web_hooks/check_unsubscribe.md =============================================================================== # Check Unsubscribe Webhook Talkable Check Unsubscribe Webhook is used to ensure emails are not sent from Talkable to user email addresses who have unsubscribed from the client side. This is an optional functionality. Note: users do have the ability to unsubscribe from Talkable referral related emails at any time from those emails directly. ## When does Talkable call the Check Unsubscribe Webhook? Talkable Check Unsubscribe Webhook is triggered on every attempt to send an otherwise valid customer email, aimed at checking if the email is also valid on merchant side. > **Important:** > > The ‘unsubscribed’ field should have a boolean value, > representing unsubscribed status according to the merchant info. ## Payload parameters provided The sample payload with parameters for Check Unsubscribe Webhook is available here: [Check Unsubscribe Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Check%20Unsubscribe/post_your_api_check_unsubscribe_web_hook_path). ### View categories View category can be one of the following: * notifier_offers_email * notifier_offers_share_via_email * notifier_offers_share_via_email_reminder * advocate_rewards_confirmation * advocate_rewards_paid * friend_rewards_paid Source: https://docs.talkable.com/web_hooks/claim_signup.md =============================================================================== # Friend Email Gating Webhook The Talkable Friend Email Gating Webhook notifies your endpoint that a Friend Email Gating form was submitted (on Friend Claim Page). Use cases for the Friend Email Gating Webhook include: * Tracking when users select the checkbox to opt into your email newsletter * Collection of data for Business Intelligence and analytics systems to track users who become Friends * Sending automated ‘Thank You’ or ‘Don’t forget to shop’ emails after a Friend passes the email gating form ## When does Talkable call the Friend Email Gating Webhook? Talkable Friend Email Gating Webhook is triggered any time an Friend Email Gating form is submitted. This is the form a Friend completes after receiving a share from an Advocate, and before receiving their discount code. Friend Email Gating form example: [Image] ## Payload parameters provided The sample payload with parameters for Friend Email Gating Webhook is available here: [Friend Email Gating Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Friend%20Email%20Gating/post_your_api_claim_signup_web_hook_path). Source: https://docs.talkable.com/web_hooks/create_coupon.md =============================================================================== # Create Coupon Webhook Talkable Create Coupon Webhook enables automatic coupon creation, which eliminates the need to upload coupon lists into the Talkable platform manually. Talkable creates unique coupon codes then passes those codes via the Create Coupon Webhook to the client; it is then up to the client to enable these coupons on their platform. > **Note:** > > Create Coupon Webhook and [Shopify Coupon auto-sync](https://docs.talkable.com/advanced_features/shopify_coupons_auto_sync.md#advanced-features-shopify-coupons-auto-sync) can be enabled simultaneously. > In that case, coupons will be passed via the webhook only after successful Shopify sync. ## When does Talkable call the Create Coupon Webhook? Create Coupon Webhook is called when the quantity of available coupons drops below a Talkable threshold. This threshold is dynamically calculated based on the number of coupon codes used by the client site in the last 21 days. The threshold ensures the Talkable coupon lists will always hold enough available coupons to serve the site for 21 days, even if the integration were to break. The minimum threshold is 20 coupons. When the number of coupons available to Talkable drops below the threshold, Talkable will call the Create Coupon Webhook with a payload of 15 new coupons in the background. If a user needs a coupon code, but there are no coupon codes available, Talkable will generate one in the foreground and give it to the user that requested it. In both cases, coupons are sent to the client endpoint as a webhook and then inserted into the Talkable database only when a webhook returns a successful response. ## Set Up The Create Coupon Webhook will add coupons to a specific coupon list on Talkable’s backend. These coupon lists must be set up in the Talkable campaign editor before utilizing the Create Coupon Webhook. Follow the below instructions to set up a coupon list for a campaign: 1. Navigate to **Campaigns** then select the campaign you would like to set up coupon list(s) for 2. Proceed to **Rules** then scroll down to **Incentives** section where incentives for both Advocate and Friend can be configured [Image] 3. Inside the Referral Incentive Editor choose the **Coupon code type: Single-use** then select an existing Coupon list or create a new coupon list by clicking **Manage Coupon Lists**. 4. Here you’ll be able to **Create New** and configure a Name, Expiration Date (optional), and Amount ($ or %) 5. Now go back to **Rules** → **Incentives** → **Edit** and select the **Reward Amount** associated with the list created in step 4 and select the newly created list 6. Optionally, select **Advanced Settings** for additional configuration parameters > **Note:** > > Coupons created by the **Create Coupon Webhook** will be added to the coupon > list associated with the referral campaign. Multiple referral campaigns can > use the same or unique coupon lists. **Advocate** and **Friend** referral > incentives can also use the same or unique coupon lists. Once a single-use coupon code list is associated with a campaign, then the Create Coupon Webhook can now be set up. [Learn more about General Webhook Set Up Steps](https://docs.talkable.com/web_hooks.md#web-hooks) ## Payload parameters provided by Create Coupon Webhook The sample payload with parameters for Create Coupon Webhook is available here: [Create Coupon Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Create%20Coupon/post_your_api_create_coupon_web_hook_path). Source: https://docs.talkable.com/web_hooks/event.md =============================================================================== # Event Webhook The Talkable Event Webhook notifies your endpoint that an [Event](https://docs.talkable.com/advanced_features/events.md#advanced-features-events) or a [Purchase](https://docs.talkable.com/integration/standard/integration_components.md#integration-standard-integration-components-post-purchase-script) has been registered with Talkable. Use cases for the Event Webhook include: * Capturing purchases and custom referral events generated by the customer (e.g. added data to profile or renewed a subscription) * Tracking coupon codes used for purchases * Using Talkable events to trigger custom workflows (e.g. add a custom property to a customer who just cancelled a subscription) ## When does Talkable call the Event Webhook? Talkable calls the Event Webhook any time an Event or a Purchase is registered either via [the front-end Talkable integration](https://docs.talkable.com/advanced_features/events.md#advanced-features-events) or using the [Talkable backend API](https://docs.talkable.com/api_v2/origins.md#api-v2-origins). ## Payload parameters provided The sample payload with parameters for Event Webhook is available here: [Event Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Event/post_your_api_event_web_hook_path). Source: https://docs.talkable.com/web_hooks/migration_to_custom_app.md =============================================================================== # Migration from Webhooks to Custom App The transition from Webhooks to [Custom App](https://docs.talkable.com/email_marketing_and_automation/custom_app.md#email-marketing-and-automation-custom-app) provides a more flexible approach to integrate Talkable events with your systems. This guide outlines the key improvements, differences, and step-by-step instructions to help you successfully migrate to the new Custom App architecture. ## How Custom App enhances or replaces Webhooks Webhooks are useful for triggering HTTP requests based on specific Talkable events, but they have limitations, such as: * Each event type requires a separate webhook configuration. * Only one webhook can be set per event. * Payload customization is not supported. Custom App overcomes these limitations by providing: * A single endpoint to manage multiple events, reducing setup complexity. * Built-in testing tools for verifying event payloads before production use. * Customizable payload with a wide range of data variables. * Conditional execution with Liquid criteria for each event. By migrating from webhooks to [Custom App](https://docs.talkable.com/email_marketing_and_automation/custom_app.md#email-marketing-and-automation-custom-app), businesses can streamline their data integration processes and reduce maintenance overhead. ## Webhooks vs Custom App | Feature | Webhooks | Custom App | | ------------------------- | ---------------------------------------- | ---------------------------------------------------------- | | **Flexibility** | Fixed event-based triggers | Supports custom event handling | | **Configuration** | Requires manual endpoint setup per event | Centralized configuration in Talkable UI | | **Customizable Payload** | Limited or manual payload manipulation | Flexible payload configuration via UI | | **Conditional Execution** | Not supported out of the box | Allows event triggers based on custom rules and conditions | ### Transition from Webhooks to Custom App To transition from webhooks to the [Custom App](https://docs.talkable.com/email_marketing_and_automation/custom_app.md#email-marketing-and-automation-custom-app), follow these steps: 1. Review Current Webhooks * Identify the webhooks currently used in your system (e.g., Sync signups, Send reward, Referral status change). * Note the payload structure and data sent to each endpoint. 2. Install and Configure Custom App * Follow the Set Up instructions below to install and enable the Custom App. * Configure the same actions as your existing webhooks. 3. Test Custom App Actions * Use the Webhook Tester to confirm that data is sent correctly. * Compare payloads from the Custom App to ensure they match what was previously received via webhooks. 4. Disable Legacy Webhooks * Once the Custom App is fully functional, deactivate the old webhooks in the Talkable settings. * Ensure all integrations are working smoothly before making the final switch. Source: https://docs.talkable.com/web_hooks/offer_signup.md =============================================================================== # Advocate Signup Webhook The Talkable Advocate Signup Webhook notifies your endpoint of an Advocate Signup forms submission. Use cases for the Advocate Signup Webhook include: * Tracking when users select the checkbox to opt into your email newsletter * Collection of data for Business Intelligence and analytics systems to track users who become Advocates * Sending automated ‘Thank You’ emails after a user becomes an Advocate ## When does Talkable call the Advocate Signup Webhook? Talkable Signup Webhook is triggered any time an Advocate Signup Form is submitted. The Advocate Signup Form is the standard Name & Email (with optional email subscription checkbox) fields a user submits before becoming an Advocate and sharing an offer with Friends. Advocate Signup Form example: [Image] ## Payload parameters provided for Advocate Signup Webhook The sample payload with parameters for Advocate Signup Webhook is available here: [Advocate Signup Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Advocate%20Signup/post_your_api_advocate_signup_web_hook_path). Source: https://docs.talkable.com/web_hooks/post_share.md =============================================================================== # Post Share Webhook Talkable Post Share Webhook provides notification of a share event performed within a referral campaign workflow. Use cases for the Post Share Webhook include: * Sending automated ‘Thank You’ email to an Advocate for performing a share * Any event that should be triggered when a user shares * Data for Business Intelligence and analytics systems ## When does Talkable call the Post Share Webhook? Talkable Post Share Webhook is triggered any time an Advocate (referrer) shares offer details with a Friend (referee) via the corresponding form provided by campaign workflow. Which includes any time: * An advocate shares with a Friend via Email or any other channel from inside a referral campaign workflow * An Advocate copies a share link from a referral campaign workflow share screen > **Note:** > > The Post Share Webhook triggers every time a share occurs. For example, if an Advocate shares with a Friend via email (or any channel), then shares with a second Friend via email (or any channel), the Post Share Webhook will be triggered twice. ## Payload parameters provided for Post Share Webhook The sample payload with parameters for Post Share Webhook is available here: [Post Share Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Post%20Share/post_your_api_post_share_web_hook_path). > **Note:** > > `origin.email` contains the email saved at the moment when the campaign is > first shown to the Advocate. It could be `null`. For the most up-to-date > information about the Advocate, use `sharer_info` property which is updated > with the email address the Advocate has entered on the Advocate Signup/Share Page. Source: https://docs.talkable.com/web_hooks/referral.md =============================================================================== # Referral Webhook The Talkable Referral Webhook notifies your endpoint that an Advocate referral status has become “Approved” specifically for a Friend purchase or event. “Approved” referral status signifies the following: * Neither Advocate nor Friend are blocked by email or IP * Advocate passed enabled fraud checks and is considered non-fraudulent Use cases for the Referral Webhook include: * Providing account credit or account upgrades to an Advocate as a reward * Giving non-monetary rewards such as physical gifts to an Advocate * Sending automated ‘Thank You’ emails after a reward is given to an Advocate * Data for business intelligence or analytics systems to track when Advocates receive rewards > **Note:** > > “Approved” referral status does not guarantee that Advocate will receive a reward. Things that can prevent Advocate or Friend from being rewarded: * Share wasn’t active at the moment of referral event creation * Advocate Referral Incentive rewards limit (per month or in total) has been reached * Coupon cycling has been detected (when Friend uses Advocate’s coupon in referred event) * Incentive criteria does not match * Rewards issuing is not allowed for auto-approved referrals > **Important:** > > Referral Webhook keeps retrying until it gets 2xx HTTP status in response. > Only after that rewards associated with the referral can be paid. ## When does Talkable call the Referral Webhook? Talkable Referral Webhook is triggered any time an Advocate referral status has become “Approved” specifically for a Friend purchase or event. > **Note:** > > Referral Webhook triggers only for Advocate rewards specifically from a Friend > Purchase or Friend Event (such as signup event or subscription purchase event). > To receive notification of both Advocate and Friend rewards use the Rewards Webhook. ## Payload parameters provided for Referral Webhook The sample payload with parameters for Referral Webhook is available here: [Referral Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Referral/post_your_api_referral_web_hook_path). ## Coupon codes as a reward > **Important:** > > If referral campaigns are set-up to reward either Friends or Advocates with > Talkable provided coupon codes, then the Reward Webhook is called for > informational purposes only. It is a notification that the reward has been > provided. Note, Talkable gets these coupons either by manual upload from the > Dashboard, or if configured, Talkable will call the [Create Coupon Webhook](https://docs.talkable.com/web_hooks/create_coupon.md#web-hooks-create-coupon) to generate additional coupons > automatically. ## Incentive types Incentives can be of 3 following general types. * **Rebate** (rebate) — monetary reward, certain amount of money that should be paid out to a customer with a given email. The merchants’ payment system should handle the payment. * **Coupon code** (discount_coupon) — a discount coupon is issued to user. Talkable handles distributing this type of incentives. * **Non-monetary** (other) — used when a campaign has a non-monetary rebate like *“Free T-shirt”* or *“One Month Free”*. This should be handled on the merchant’s side. More information on the reward is specified in incentive_description. Source: https://docs.talkable.com/web_hooks/reward.md =============================================================================== # Reward Webhook The Talkable Reward Webhook notifies your endpoint that a reward is ready to be, or has been given. A reward can be for either an Advocate or for a Friend. Talkable Reward Webhook notifications allow your application to know when to reward users by means other than the standard ‘give them a coupon code’ method. Use cases for the Reward Webhook include: * Providing account credit or account upgrades to a user as a reward * Giving non-monetary rewards such as physical gifts * Sending automated ‘Thank You’ emails after a reward is given to a user * Any event that should trigger at the moment a user has earned a reward ## When does Talkable call the Reward Webhook? Talkable calls the Reward Webhook any time a reward is ready to be, or has been given to either an Advocate or a Friend according to the logic set-up in a Talkable referral campaign. Possible events which will trigger the Reward Webhook are: * Advocate Signup Form submitted (Reason = **signup**) * Advocate shares an offer with Friend(s) (Reason = **shared**) * Friend passes email gating form (Reason = **click**) > **Note:** > > If campaign is setup without email gating form, Reward Webhook with > Reason = click will trigger when Friend clicks through to site. * Friend makes eligible purchase (Reason = **referrer**) * Friend makes eligible purchase (Reason = **referred**) > **Note:** > > Reason = referrer indicates a reward should be given to an Advocate. > Reason = referred indicates a reward should be given to a Friend. ## Set-Up Because the Reward Webhook will trigger at various events depending on the Incentive configuration for each referral campaign, to trigger the Reward Webhook we first must ensure Incentives are correctly configured. To configure incentives: 1. Navigate to **Campaigns** then select the campaign you would like to configure incentives for 2. Proceed to **Rules** then scroll down to **Incentives** section where incentives for both Advocates and Friends can be set-up [Image] 3. Configure the incentives as desired inside the Referral Incentive Editor. To configure Incentive types other than Coupon Codes, please contact your Talkable Customer Success Manager; they will be able to set up “Rebate (store credit)” type incentives and “Non-Monetary” type incentives. > **Note:** > > If there is a delay configured into when the Advocate reward is approved then > the Reward Webhook trigger when the Advocate reward is ready to be, or has > been given. For example, if campaigns are set to send an Advocate their reward > three days after a Friend makes an eligible purchase, then the Reward Webhook > will be called three days after the Friend makes the eligible purchase. You > can select these delays under **Fraud Settings**, which is found under **Menu**. Once incentives are configured for a referral campaign, Talkable will then call the Reward Webhook any time either an Advocate or a Friend should receive a reward. Now, the Reward Webhook can be set-up. [Learn more about General Webhook Set Up Steps](https://docs.talkable.com/web_hooks.md#web-hooks) ## Payload parameters provided by Reward Webhook The sample payload with parameters for Reward Webhook is available here: [Reward Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Reward/post_your_api_reward_web_hook_path). ## Reasons Reward reason can be of 5 following general types. * **signup** — Advocate reward for sign-up (Advocate Signup Form submitted) * **shared** — Advocate reward for sharing an offer with Friend(s) * **click** — Friend reward for visiting claim page (and optionally passing gating) * **referrer** — Advocate reward for eligible referral purchase by Friend * **referred** — Friend reward for eligible referral purchase by themselves ## Incentive types Incentives can be of 3 following general types. * **Rebate** (rebate) — monetary reward, certain amount of money that should be paid out to a customer with a given email. The merchants’ payment system should handle the payment. * **Coupon code** (discount_coupon) — a discount coupon is issued to user. Talkable handles distributing this type of incentives. * **Non-monetary** (other) — used when a campaign has a non-monetary rebate like *“Free T-shirt”* or *“One Month Free”*. This should be handled on the merchant’s side. More information on the reward is specified in incentive_description. ## Coupon codes as a reward > **Important:** > > If referral campaigns are set-up to reward either Friends or Advocates with > Talkable provided coupon codes, then the Reward Webhook is called for > informational purposes only. It is a notification that the reward has been > provided. Note, Talkable gets these coupons either by manual upload from the > Dashboard, or if configured, Talkable will call the [Create Coupon Webhook](https://docs.talkable.com/web_hooks/create_coupon.md#web-hooks-create-coupon) to generate additional coupons > automatically. Source: https://docs.talkable.com/web_hooks/unsubscribe.md =============================================================================== # Unsubscribe Webhook Talkable Unsubscribe Webhook provides notification of a user unsubscribing from Talkable sent referral email. Use cases for the Unsubscribe Webhook include: * Unsubscribing users from in-house marketing newsletters when user unsubscribes from Talkable referral emails * Any event that should be triggered when a user unsubscribes from Talkable referral emails ## When does Talkable call the Unsubscribe Webhook? Talkable Unsubscribe Webhook is called any time a user unsubscribes from a Talkable sent email. ## Payload parameters provided The sample payload with parameters for Unsubscribe Webhook is available here: [Unsubscribe Webhook Payload](https://www.talkable.com/api-docs/index.html?urls.primaryname=webhooks%20api&urls.primaryName=Webhooks#/Unsubscribe/post_your_api_unsubscribe_web_hook_path). --- ## Summary Total documents aggregated: 175 Generated by talkable-llm-txt