Setting up a Custom Action

Learn how to create Custom Actions to integrate your external data with bots that resolve more customer questions.

Beth-Ann Sher avatar
Written by Beth-Ann Sher
Updated over a week ago

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.

Creating a custom action

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 it a clear description

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.

An image showing the screen for a Custom Action Get Shopify Order by id.

Configure the request details

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

API Endpoints

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

  • GET - Read and store information from the 3rd party system.

  • POST - Create or add information to the 3rd party system.

  • PUT - Update information in the 3rd party system.

  • DELETE - Remove information from the 3rd party system.

An image showing the screen a Custom Action's API Endpoint Methods.

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

An image showing the screen for a Custom Action's GET Method URL.

Important: To make a request, the URL must be an HTTPS address and return a JSON response.

Note: You can insert attributes from User, Conversation, Company, and events as templated values in the URL and in the request body of POST and PUT methods. Use custom data attributes you have already set up in your workspace. Or, for much greater data flexibility, try using Custom Objects.

HTTP headers

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

An image showing the screen for a Custom Action's 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.

An image showing the screen for a Custom Action's Authentication token setting.

Request body

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:

An image showing the screen for a Custom Action's Request Body data.

Note: Make sure to include appropriate HTTP headers as required by the API you're making a request to (for example, accept: application/json and content-type: application\json)

Test the request action

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.

An image showing the screen for a Custom Action's being tested with a 200 OK and the response data.

Tip: This is all the information you can now use to power your bots and provide customers with fast answers, such as order status.

Important: Testing this request makes a connection with the API so it will complete the action you have created. For example, if you’ve asked it to DELETE data from the API, this information will be deleted. Try testing with a GET request to ensure you’re only reading information and not changing it.

Response mapping the stored data

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.

Note: Common scenarios where you might not need to store data are action request types PUT, POST, DELETE. For all GET requests, if you want to use the data in bots, you’ll need to store this data in Intercom.

JSON response data can be stored in:

  • Standard Objects: User and Conversation attributes.

  • Custom Objects: Object attributes you have created in Intercom.

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

An image showing the screen for a Custom Action's response and Custom Object mapping to a Conversation.

Important: All custom attributes and Custom Objects must be created before they can be used for response storage here. Find out more about creating custom attributes, or learn how to store your data with Custom Objects.

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”:

An image showing the screen for a Custom Action's response and Custom Object Conversation Attributes mapping.

Note: External data can only be stored in custom data attributes and not the standard data attributes.

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”:

An image showing the screen for a Custom Action's response and Custom Object mapping to People and its Attributes..

Mapping response data to Custom Objects

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

An image showing the screen for a Custom Action's response and Custom Object mapping to an Order and its Attributes..

Updating references to People or Conversations

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

An image showing the screen for a Custom Action's response mapping to its Conversation and People references.

Set the Custom Action live

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 🎉

Note: The current timeout limit for Custom Actions is 15 seconds.

Moving a Custom Action to draft

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.

An image showing the screen for a Custom Action with dependencies needing review before being moved to draft.


Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts

Did this answer your question?