{"id":25009568,"url":"https://github.com/kentico/xperience-module-intercom","last_synced_at":"2025-04-12T19:10:24.548Z","repository":{"id":45938446,"uuid":"420087014","full_name":"Kentico/xperience-module-intercom","owner":"Kentico","description":"Kentico Xperience integration with the Intercom chat service.","archived":false,"fork":false,"pushed_at":"2024-07-16T14:45:28.000Z","size":57058,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-12T19:09:56.293Z","etag":null,"topics":["integration","intercom","kentico-xperience"],"latest_commit_sha":null,"homepage":"https://xperience.io","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kentico.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-22T12:17:42.000Z","updated_at":"2024-07-16T14:45:32.000Z","dependencies_parsed_at":"2024-07-16T15:24:11.490Z","dependency_job_id":null,"html_url":"https://github.com/Kentico/xperience-module-intercom","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"Kentico/repo-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kentico%2Fxperience-module-intercom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kentico%2Fxperience-module-intercom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kentico%2Fxperience-module-intercom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kentico%2Fxperience-module-intercom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kentico","download_url":"https://codeload.github.com/Kentico/xperience-module-intercom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248618277,"owners_count":21134200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["integration","intercom","kentico-xperience"],"created_at":"2025-02-05T04:40:19.139Z","updated_at":"2025-04-12T19:10:24.524Z","avatar_url":"https://github.com/Kentico.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kentico Xperience Intercom modules\n[![Stack Overflow](https://img.shields.io/badge/Stack%20Overflow-ASK%20NOW-FE7A16.svg?logo=stackoverflow\u0026logoColor=white)](https://stackoverflow.com/tags/kentico)\n\n|  | Package |\n| ------------- |:-------------:|\n| Administration | [![NuGet](https://img.shields.io/nuget/v/Kentico.Xperience.Intercom.Admin.KX13.svg)](https://www.nuget.org/packages/Kentico.Xperience.Intercom.Admin.KX13) |\n| Live site - ASP.NET Core | [![NuGet](https://img.shields.io/nuget/v/Kentico.Xperience.Intercom.KX13.svg)](https://www.nuget.org/packages/Kentico.Xperience.Intercom.KX13) |\n\n[Intercom integration](https://www.intercom.com/) for [Kentico Xperience](https://xperience.io/)\n\nThis repository contains the source code for modules that integrate Kentico Xperience with the Intercom chat service.\n\n## Description\n\nThe Intercom integration modules provide the following features:\n* Synchronization of Xperience contact data to contacts in your Intercom organization. Depending on your site's personal data policy, this synchronization can be disabled, or conditionally applied only to contacts who agree with a specific consent.\n* Transfer of data submitted through the Intercom chat to corresponding contact attributes in Xperience.\n* Logging of custom activities in Xperience when users perform specified actions in the Intercom chat.\n* HtmlHelper API that helps developers generate scripts that add the Intercom chat interface on the pages of your live site.\n\nThe project consists of two modules:\n* **Administration** - Adds the *Intercom* application to the Xperience administration interface. The application is used to set up the integration and allows you to toggle the Intercom functionality on or off.\n* **Live site** - Provides an HtmlHelper API to simplify generating of scripts that add the Intercom chat interface to your site's pages. Adds endpoints that recieve requests from Intercom webhooks, which are used to update contacts and log activities.\n\n## Compatibility\n* *Kentico Xperience 13.0.0* or newer. \n* Only the **ASP.NET Core** development model for the live site is supported.\n\n## Requirements and prerequisites\n\n* **Xperience Enterprise** license edition for your site's domain, as the integration uses on-line marketing features (contacts and activities).\n* Your Xperience administration application must run using the secured **HTTPS** protocol.\n* The *Enable on-line marketing* setting needs to be selected in the Xperience *Settings* application.\n* You need to have an *Intercom* account, workspace and app created. You can register a free developer account at [https://www.intercom.com/](https://www.intercom.com/). For more information, see the [Intercom Developer Hub Docs](https://developers.intercom.com/building-apps/docs/welcome).\n* **Important**: The integration optionally synchronizes contact data from Xperience to your Intercom workspace. As a result, the **personal data** of visitors may be exported to a third party. If necessary, update your website's personal data policy and any related consents.\n\n## Setup (Developers)\nThe setup of the Intercom integration consists of the following steps:\n1. [Install the administration package](#install-the-administration-package)\n2. [Install the live site package](#install-the-live-site-package)\n3. [Add Intercom webhook endpoints](#add-intercom-webhook-endpoints)\n4. [Add Intercom Messenger to your website](#add-intercom-messenger-to-your-website)\n5. [Configure Intercom and Xperience](#configure-intercom-and-xperience)\n\n### Install the administration package\n1. Open the solution with your Xperience administration project (*~/WebApp.sln*).\n1. Navigate to the *NuGet Package Manager Console*.\n1. Run `Install-Package Kentico.Xperience.Intercom.Admin.KX13 -Version 1.0.0`\n1. Rebuild the CMSApp project.\n\n### Install the live site package\n1. Open the solution with your live site project (e.g., *~/DancingGoatCore.sln*).\n1. Navigate to the *NuGet Package Manager Console*.\n1. Run `Install-Package Kentico.Xperience.Intercom.KX13 -Version 1.0.0`\n1. Rebuild your live site project.\n\n### Add Intercom webhook endpoints\n\nTo allow Intercom to update the data of contacts and log custom activities in Xperience, your live site application needs to process webhook requests. Add endpoints for these requests to your website:\n1. Edit your live site project's startup class (*Startup.cs* by default).\n1. Add the following using statement: `using Kentico.Xperience.Intercom;`\n1. Within the `ConfigureServices` method, call `services.AddHttpClient();`\n1. Register the Intercom endpoints in the `Configure` method:\n```\napp.UseEndpoints(endpoints =\u003e\n{\n   endpoints.Kentico().MapRoutes();\n   \n   // Registers endpoints that process requests from Intercom webhooks \n   endpoints.MapKenticoIntercomRoutes();\n   ...\n```\n\nYour live site application can now process Intercom webhook requests using the following routes:\n* **https://{live_site_url}/kentico.xperience.intercom/updatecontact**\n* **https://{live_site_url}/kentico.xperience.intercom/logactivity**\n\n### Add Intercom Messenger to your website\n\nTo add Intercom Messenger (chat interface) onto your website's pages, use the `@Html.IntercomScripts()` HtmlHelper provided by the installed live site module. The method generates the required intercom scripts using the configuration provided in the Xperience administration.\n\nPlace the scripts before the closing `\u003c/body\u003e` tag on every page where you want the Intercom Messenger to appear. For example, a suitable location is your site's main **_Layout.cshtml** view if you want to add Intercom to all or most pages (when using MVC architecture for the site).\n\n```\n@using Kentico.Xperience.Intercom\n\n  ...\n\n  @Html.IntercomScripts()\n\u003c/body\u003e\n```\n\nThe generated scripts automatically ensure that the names and email address of your contacts in Xperience are synchronized to the corresponding fields of contacts in Intercom. You can configure the synchronization in the Xperience administration according to your site's personal data policy. It can be disabled completely or conditionally enabled only for contacts who agree with a specific consent.\n\n### Configure Intercom and Xperience\nCommunication between Xperience and your Intercom app requires configuration on both sides.\n\nOpen the Xperience administration and navigate to the **Intercom** application. Fill in the settings in the **Setup** section:\n* **Enable Intercom** - Toggles the Intercom functionality on or off for your website.\n* **Intercom App ID** - The ID of your Intercom app (workspace). See [Where can I find my workspace ID (app ID)?](https://www.intercom.com/help/en/articles/3539-where-can-i-find-my-workspace-id-app-id).\n* **Intercom Client ID and Secret** - The Client ID and Client secret values of your Intercom app.\n  1. Open the Intercom Developer Hub (access the *Settings* of your Intercom workspace and go to *Developers \u003e Developer Hub*).\n  2. Edit your Intercom app.\n  3. Navigate to **Configure \u003e Basic information**.\n  4. Copy the values to the corresponding settings in Xperience.\n\u003cimg src=\"https://user-images.githubusercontent.com/16876168/142841507-339fdb5f-3491-4b9f-9f5f-b170ed50306e.png\" height=\"250\"\u003e\n\n* **Intercom Identity Verification Secret** - To ensure secure communication, [Enable identity verification](https://www.intercom.com/help/en/articles/183-enable-identity-verification-for-web-and-mobile) in Intercom:\n  1. Access the **Settings** of your Intercom workspace.\n  2. Go to **Security \u003e Enforce identity on web**.\n  3. Enable the **Enforce identity verification** option.\n  4. Copy the **Identity verification secret** value to the corresponding setting in Xperience.\n* **Send contact attributes to Intercom** - Choose how the integration synchronizes the names and email adress of contacts from Xperience to your Intercom organization (depending on your site's personal data policy). You can leave the synchronization enabled for all contacts (*Always*), disable it completely (*Never*), or enable it only for contacts who agree with a selected consent.\n\n**Save** the settings in the Xperience *Intercom* application.\n\nNext, you need to provide an access token that allows Xperience to obtain data from your Intercom workspace via the API.\n1. Open the Intercom Developer Hub (access the *Settings* of your Intercom workspace and go to *Developers \u003e Developer Hub*).\n2. Edit your Intercom app.\n3. Navigate to **Configure \u003e Authentication**.\n4. Click **Edit**.\n5. Enable **Use OAuth**.\n6. Add the following **Redirect URLs**:\n\n   *{Xperience administration domain}/CMSModules/Kentico.Xperience.Intercom.Admin/Pages/Intercom_AccessTokenDialog.aspx*\n   \n   The redirect URL must be absolute, including the protocol, domain and virtual directory. If your Xperience administration application is available on multiple domains, add all of the possible options. For example:\n   \n   `https://adminDomain.com/CMSModules/Kentico.Xperience.Intercom.Admin/Pages/Intercom_AccessTokenDialog.aspx`\n7. **Save** the authentication settings.\n8. Return to the Xperience *Intercom* application.\n9. Click **Get token** next to the **API access** field in the **Intercom data access** section.\n\n\u003cimg src=\"https://user-images.githubusercontent.com/16876168/143205457-9a651aa3-0d1c-4334-9ea1-e74410f09072.png\" height=\"400\"\u003e\n\nYour marketers can now set up the required contact synchronization and activity logging using the Intercom Series feature and webhooks.\n\n## Intercom Series webhooks (Marketers)\n\nTo set up synchronization of contact data from Intercom to Xperience, as well as logging of custom activities in Xperience, you need to use the Intercom Series feature and webhooks.\n\nSee [Orchestrate your customer messaging with Series](https://www.intercom.com/help/en/articles/4425207-orchestrate-your-customer-messaging-with-series) for general information about this Intercom feature.\n\n### Update contact data in Xperience\nWhen visitors use the Intercom chat, you may wish to transfer specific pieces of the entered data into your Xperience contacts. To set up when and how the data is transferred, create an Intercom Series according to the following steps:\n\n1. Log in to your Intercom workspace.\n2. Navigate to **Outbound \u003e Series**.\n3. Create a **New series** or edit an existing one that you use for your Intercom chat.\n4. Switch to **Edit** mode.\n5. Add blocks to build your chat experience (RULES, BOT, etc.).\n![Intercom_Series_Contact_Data](https://user-images.githubusercontent.com/16876168/142988821-58c9db39-09e7-47ac-9cf0-f5a7e8854dd4.png)\n6. To transfer data into Xperience contacts, add the **WEBHOOK** block.\n7. Set the following when configuring the Webhook block:\n\t* **HTTP method**: POST\n\t* **Webhook URL**: {your live site URL}/kentico.xperience.intercom/updatecontact\n\t* **Webhook header** - add and set the following keys:\n\t\t* **Content-Type**: application/json\n\t\t* **XperienceAPIKey:** open the *Intercom* application in the Xperience administration and copy the value from **Webhook request security \u003e Your API Key** \n\t* **Webhook body** - add keys for all contact attributes that you wish to update in Xperience.\n\t   * Important: The webhook body must always contain the **ContactGuid** key, with the **User ID** people attribute as the value.\n\t   * Set the keys according to the following names of Xperience contact fields:\n\t      * ContactEmail\n\t      * ContactFirstName\n\t      * ContactMiddleName\n\t      * ContactLastName\n\t      * ContactJobTitle\n\t      * ContactAddress1\n\t      * ContactCity\n\t      * ContactZIP\n\t      * ContactMobilePhone\n\t      * ContactBusinessPhone\n\t      * ContactNotes\n\t      * ContactCompanyName\n\t      * Additionally, your developers may implement handling for custom contact fields.\n\t   * For the key values, select the corresponding people attribute from Intercom from which you want to take the data.\t\t\t\t  \n![Intercom_Webhook_Contact_Data](https://user-images.githubusercontent.com/16876168/143006883-0d181788-d1fd-48fa-9456-4c265c51ea59.png)\n8. Save the webhook.\n\n**Note**: Intercom checks if a user matches a Series block every time they visit your website, and periodically in the background. After you change and save a Series, there may be a delay before the results impact visitors on your website.\n\nWhen visitors go through the Series in the Intercom chat on your website and submit information, the data of the matching contact in Xperience is now updated correspondingly.\n\n### Log custom activities in Xperience\nWhen visitors use the Intercom chat, you may wish to log activites in Xperience at certain points during the conversation. To set up this logging of activities, create an Intercom Series according to the following steps:\n\n1. Log in to your Intercom workspace.\n2. Navigate to **Outbound \u003e Series**.\n3. Create a **New series** or edit an existing one that you use for your Intercom chat.\n4. Switch to **Edit** mode.\n5. Add blocks to build your chat experience (RULES, BOT, etc.).\n6. To log Xperience activities, add the **WEBHOOK** block.\n7. Set the following when configuring the Webhook block:\n   * **HTTP method**: POST\n\t* **Webhook URL**: {your live site URL}/kentico.xperience.intercom/logactivity\n\t* **Webhook header** - add and set the following keys:\n\t\t* **Content-Type**: application/json\n\t\t* **XperienceAPIKey:** open the *Intercom* application in the Xperience administration and copy the value from **Webhook request security \u003e Your API Key** \n\t* **Webhook body** - add keys for activity fields that you wish to fill in Xperience.\n\t   * Important: The webhook body must always contain the following keys:\n\t      * **ActivityType** key, with the code name of the corresponding Xperience activity as the value. You can find the activity type code names in the Xperience administration in *Contact management \u003e Configuration \u003e Activity types*.\n\t      * **ContactGuid** key, with the **User ID** people attribute as the value.\n\t   * Optionally, you can add keys for the **ActivityURL** and **ActivityValue** fields.\n\t   * For the key values, select the corresponding people attribute from Intercom or enter a value directly.\n![Intercom_Webhook_Activity](https://user-images.githubusercontent.com/16876168/143006758-0f817d86-08ff-4434-81af-5704ef9347fc.png)\n8. Save the webhook.\n\n**Note**: Intercom checks if a user matches a Series block every time they visit your website, and periodically in the background. After you change and save a Series, there may be a delay before the results impact visitors on your website.\n\nWhen visitors go through the Series in the Intercom chat on your website, activites are logged in Xperience according to the Series rules. The comment field of the logged activities contains a link to Intercom, where marketers can view the conversation history from the given chat interaction.\n\n## Synchronize data to custom contact fields (Developers)\n\nIf your Xperience contacts use [custom fields](https://docs.xperience.io/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-contacts/adding-custom-fields-to-contacts) and you wish to synchronize Intercom data into these fields, you need to implement additional handling of the data.\n\n1. Open the solution with your **live site project** (e.g., *~/DancingGoatCore.sln*).\n1. Prepare a separate assembly (Class Library project).\n1. Create a custom module class in the assembly.\n1. Override the module's **OnInit** method and assign a handler method to the **IntercomEvents.UpdateContact** global event (available in the *Kentico.Xperience.Intercom* namespace).\n1. Load the provided contact data from the event arguments and save the values into the appropriate Xperience contact fields.\n\nFor more details, see the example in this repository: [SampleModule.cs](https://github.com/Kentico/xperience-module-intercom/blob/master/src/Kentico.Xperience.Intercom.AspNetCore.SampleModule/SampleModule.cs)\n\n## Get involved\n\nCheck out the [contributing](CONTRIBUTING.md) page to see how to file issues, start discussions, and begin contributing.\n\n## Questions \u0026 Support\n\nSee the [Kentico home repository](https://github.com/Kentico/Home/blob/master/README.md) for more information about the product(s) and general advice on submitting questions.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentico%2Fxperience-module-intercom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkentico%2Fxperience-module-intercom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentico%2Fxperience-module-intercom/lists"}