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 Fin, Workflows, and the Inbox, allowing your customers to self-serve their queries automatically.

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 > Integrations > 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 and then select Create custom action from the dropdown menu.

From the Usage dropdown you can choose to set up this custom action for:

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”).

Next, fill in the request details. This is where you’ll need to enter the HTTPS 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:

In this example, we’ll ask the request to GET the order ID from the API and enter the URL.

You can choose to add any additional parameters to this request by clicking Add key value pair and then select Key value pair under HTTP Headers:

Custom actions support both fixed and dynamic tokens for authentication. Under the HTTP Headers, 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 the response for this action to make sure it’s fetching the right data from the 3rd party system you’re connecting to.

Click Test request 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 is all the information you can now use to power your Workflows and provide customers with fast answers, such as order status.

This step is optional but it’s important if you want to use the data in your Workflows, 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 example, we selected "Order" as the Intercom object and then selected "orders" as the API object in the external system and mapped it with the API attribute "order_id":

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

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.

Go to Settings > Integrations > Actions and click on the custom action you want to move to draft then select Set 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.