Hey there đFemi here from the Technical Support Engineering team!
Â
We get some questions about using Custom Actions with Custom Objects and Workflows, hereâs how to do that.
Â
Letâs start by taking a look at what my custom API response to the /products endpoint of my test API looks like đ This is important as the request and response type will determine how you structure the Custom Action request.
Â
Â
Now that we know what the response looks like, letâs go ahead and set up our 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. In this post, Iâll be making use of my custom online store that sells football boots.
Click âCreate actionâ to set up your first Custom Action:
Â
Give your Custom Action a clear description đ
Â
Â
Configure the Request details: This is where youâll need to enter the API URL to the 3rd party system youâre connecting to.
Â
Â
Mine is a simple GET request to my API endpoint. Once done, you can click on the Next button.Â
Â
This is where we test the request that we have just configured to make sure it all works đClick on the Test request button
Â
Â
We get a 200 OK response with the data from the API, looks like weâre ready to go!
Â
Click on the Next button again and this is the important bit, the Response mapping, 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.
Â
Â
Now we map the response data to a Custom Object data - what is that?Â
Â
Custom Objects allow you to extend Intercom's standard People and Conversation object data to store data that represents your business in a more flexible way.
Â
First step is to save our Custom Action and then Create a Custom Object data
To get started, go to Settings > workspace data > Custom object data.
Create your first Custom Object by clicking on âCreate new objectâ. Give the object a name (e.g. Boots CO to represent Boots Custom Objects since thatâs what my fictional store sells) and then click âSaveâ.
Â
Â
This creates a new parent object with some recommended default attributes that track some data that are important when using Custom Actions:
- âexternal_idâ
- âexternal_created_atâ
- âexternal_updated_atâ
Â
Once done, we can create attributes that match up to the response of the API. Iâll not include ID since the external_id comes as a default attribute.
Â
Next we add all of our attributes and map them to the response that correlates, then include a reference to Conversations which will allow us to create connections between our Custom Object and the conversation to power the workflow đ
Â
Â
Â
I also toggled the option to âAllow referencing multiple Conversationsâ - we talk about this in our article on Setting up references with Custom Objects. The gist of it is that multiple Conversations can happen about different Boots. Hereâs what the finished Custom Object data looks like đ
Â
Â
What weâll do next is create conversation data where we want to store the boots weâre showing them and the one the customer is deciding to chat about.
Â
First weâll create Conversation data with the format Reference and select the Boots CO Custom Object for the whole inventory that weâre showing, weâll also toggle the âAllow referencing multiple Boots COâ. This is because this is a many - to - many relationship. đ
Â
Next, weâll create another conversation attribute to hold the particular boot that they have decided to chat to us about in the same way we created the first one. Iâm naming this âSelected Bootâ.
This time around the âAllow multiple referencing BO will be turned off since this is to highlight just one particular boot. Â
Â
Once done, we can go ahead and Save everything, then head on back to the Custom Action to finish the Response mapping.
Â
First we map the Intercom Object of the âBoots COâ to the API object thatâs returned, in this case itâs an Array of Products.
Â
Then we match each attribute that we have created in the Custom Object to a matching attribute from the API response. Once done, we select the reference from either People or Conversations to the Boots CO.
Â
Once completed, hereâs what it should look like đ
Â
Â
Thatâs it, your very first Custom Action with Custom Object and conversation references. Next we build out the Automation (Workflow) where we can have this interact with customers.
Â
Hereâs what my workflow looks like and how to add the Custom Action đ
Â
Â
Click on Select the Custom Action and select Boots
Â
Â
Once done, add the message for if the Custom Action fails and then add the Buttons from Custom Objects as the next step under the Custom Action đ
Â
Click on Select data and you can configure the button that shows up đ
Â
Click on Add condition to select the "Conversation > Boots data for Conversation from contextâ option đ
Weâre selecting this because this is where we mapped our data to in the configuration of the Custom Object and Conversation attribute.
Â
Once done, you can select the number of buttons (boots in this case) that you want to show to the customer and what attribute the button should show đ
Â
Â
Save and close that once youâve selected your options, then enter None of the above (or if you have something else you want to link to, you can use this button to connect to another path).
Â
Click on Save selection to and then click on the Selected Boot conversation data (remember, we named the other conversation data this to track the particular boot the customer wanted to chat about.)Â
Â
Â
Â
I connected the buttons to other paths to get the data. You can click on the {..} to select the attributes and the scroll down the list until you get the Conversation > Selected Boot (Boot CO) options and structure the message however you want it đ
Â
Â
Completed Workflow đ
Â
Â
Hereâs what a Preview conversation of the workflow looks like
Â
Â
You can see the details saved to the conversation attributes, both for the Boots data and for the Selected boot
Â
Â
Selected Boot đ
Â
Â