Custom Actions are no-code and deeply embedded integrations that can connect your live external data with Intercom. This live data can be used to power bot and Inbox workflows, allowing your customers to self-serve their queries automatically in the Messenger.

A great way to get started is to think of common questions that your teammates spend considerable time answering, using information currently not available in Intercom.

These can be questions where your customers simply want to get information that you store on an external system such as, “What is my order status?”, or take action like, "Reschedule a delivery" or "Process a refund" in your external system.

When you know which questions you want to solve, it’s surprisingly simple and quick to set up a Custom Action with little to no technical expertise.

First, navigate to Settings and go to Apps & Integrations where you’ll find “Custom Actions”:

This is where you'll set up all the different connections you have to external data (e.g. Shopify, Salesforce, etc.) depending on your use case. Click “Create action” to set up your first Custom Action:

Give your Custom Action a unique name that explains exactly which action it will be taking (e.g. “Get order ID”). Use the description field to tell teammates when to use this action and what information they can expect it to fetch (e.g. “Get order for a given ID. Order ID should be stored in Conversation CDA”).

We’ll use an everyday use case as an example: An E-commerce retailer that uses Shopify wants to pull in the order information.

Next, fill in the request details. This is where you’ll need to enter the API URL to the 3rd party system you’re connecting to (e.g. Shopify, Salesforce, etc.).

You can specify what action you’d like this request to take by selecting the method:

Using the same Shopify example, we’ll ask the request to GET information from the Shopify API and enter the URL:

You can choose to add any additional parameters to this request by selecting “+ New key value pair” under HTTP Headers:

Custom Actions support both fixed and dynamic tokens for authentication. Under the Authentication tab, you can select the authentication token you want to use in the request, which will then be added to the header.

If you're making a POST or a PUT request, you'll have an option to provide a request body to include any data you want to send in the request:

Next, you’ll need to test this action to make sure it’s fetching the right data from the 3rd party system you’re connecting to.

Enter a test value (e.g. the order number) to check the Custom Action has been configured correctly. You should get a green tick and see the details of that request if the connection is validated with the API.

This step is optional but it’s important if you want to use the data in your bot flows, particularly for GET requests. It tells the action where to store this information in Intercom so that it can be given to customers in your Workflows as answers to their questions.

Learn about the handling of Custom Action storage, authorization and execution.

JSON response data can be stored in:

Select the Intercom object and then map it with the external API object.

Now select the data attributes in Intercom you want to store this information in. For the Shopify example, we selected “Conversation” as the Intercom object and then selected the Conversation CDA in Intercom “ccda_shopify_order_fullfilment_status” and mapped it with the API attribute in Shopify: “order.fulfillment_status”:

We also added another object mapping for “People” and then selected the CDA in Intercom “cda_shopify_order_fullfilment_status” and mapped it with the API attribute in Shopify “order.fulfillment_status”:

When mapping with Custom Objects, you must map the ID to the external_id field otherwise it will create duplicates with each GET request. Learn more about setting up right references with Custom Objects

Find the supported JSON objects and arrays for response mapping here.

The next step is to select which references from People or Conversation relate to your Custom Object you want to update.

Once you’ve tested your Custom Action successfully, you’re ready to set it live.

Now you can use it in Workflows or in the Inbox to allow customers to self-serve or your support team to fetch data from external sources 🎉

If you want to deprecate old Custom Actions that are no longer required, you can move them into draft state.

Find and click on the Custom Action you want to move to draft from Settings > Apps & Integrations > Custom Actions.

Then select "Move to draft".

This will check for any dependencies on this Custom Action. You'll need to review and resolve these dependencies before moving it to draft state. For example, you may need to remove this Custom Action from a Workflow first.