Written by Nathan Skiles, Technical Support Engineer @ Kustomer
With all of the different actions available in Kustomer’s workflows, it can be easy to overlook one of the more versatile tools available to you: the REST API action which allows you to make API calls to data sources or integrations and either create, read, update, or delete data in Kustomer.
These steps can also be used to query the Kustomer API and perform actions outlined in the Kustomer API Docs, which is the most common use case. This allows you to access any data from your instance of Kustomer that may not be available to you through other workflow actions.
There are two different flavors of API actions, but ultimately they do similar things in slightly different ways.
-
The REST API: JSON action step is generally the step that you’ll be using to make requests. Used when making an API call to a server that accepts JSON-formatted requests and is generally the step that you will be using.
-
If the server receiving your requests requires a different format for your data, you can use the REST API: Generic step which allows you to customize the request body as a text string.
Setting up an API request step
In this article, we are going to be building a workflow that marks conversations done and applies a specific disposition when a tag of our choosing is added to a conversation. To get started with making API requests we’ll need to create a workflow with a Rest API: JSON action step.
Once you have an API Request step created we’ll have to determine which endpoint we are going to want to make a request to, and because we are going to be making changes to a conversation we can use the conversations endpoint and a PUT request to make these updates.
Where {id} is the ID of the conversation we would like to make an update to. We know we want to update the conversation which triggered this workflow so we can grab the conversation ID from the output of the conversation update using string interpolation.
On the Rest API: JSON step we created above, let's set the method to PUT and our Uri (from the documentation and using string interpolation) to:
https://api.kustomerapp.com/v1/conversations/{{{steps.1.id}}}
How to create API keys and where to store them
Requests to APIs generally need to be authenticated, and the Kustomer API is no different. All requests to the Kustomer API are authenticated using an API token included in the Authorization header of your requests. Don’t worry if you’re not quite sure what this means, we will walk through these steps together.
First, to create an API Key in your Kustomer organization, you’ll need Admin permissions then head over to the Settings page in Kustomer and select Security > API Keys
On the API Keys setting page, click the ‘Add API Key’ in the top right corner on the table containing your organization’s API Keys. From here you will be prompted to give the key a Name, Role, Expiration, and IP restrictions.
Naming your key correctly will be very helpful down the road if you ever need to troubleshoot your workflow, the key’s name will generally be displayed in the UI as having taken any action. E.g. a workflow that creates a message with an API key will show as created by the key’s name. For Roles, we can simply select org.tracking. Expiration can be set at your discretion, but keep in mind that if your key expires - whatever is relying on it will be unable to authenticate and break until you are able to add a new key. For the purposes of this walkthrough, 7 days should be fine.
Finally, click on ‘Create’ to generate a new token. This is the only time you’ll be able to see the full token through the Kustomer UI, so make sure you don’t close the window that pops up before copying the key. Once copied, head back to your REST API workflow to store the key securely.
Inside of workflows, there is a feature that can be used for storing secure credentials called Workflow Variables and this knowledgebase article does a pretty good job already at explaining how to create and store variables, so I won’t be going too far into this - I recommend reading the article for more information on this topic.
Back on our REST API let’s store our key in the workflow’s variables, click the vertical dots next to the save button to open the workflow options and then Workflow Variables. When the modal pops up, you’ll be able to see any current variables as well as add new variables. Let’s create a variable named ‘API_Key’ and post our API Key copied above in the Value field. Click save.
Making an API Call
At this point, we have all of the pieces needed to make our API request, so go ahead and start filling out some of the data required to authorize and let the API know what to do with the content of the request.
We will do this in the Headers section of the action step and we will be passing 3 keys in our request: Authorization, Accept, and Content-Type. I won’t go into details on these, I would recommend doing a quick google search to get a basic understanding of these (though not necessary). We will be passing parameters to the call using JSON (JavaScript Object Notation) and they will always be in the following format { “Key”: “Value” } with each key value pair separated by a comma.
First, Authorization is going to be our API Key that we created previously. Let’s clear out the quotations in the Headers section of the action and create a Headers object by inserting curly brackets and inserting our parameters in between them as such. Next, copy our workflow variable by clicking the small key icon above the Headers section and then selecting the variable you created previously should automatically copy it to your clipboard. Now we can pass it to the headers by typing “Authorization: “Bearer -Paste Your Variable Here-” between the curly brackets. Make sure to paste your variable after the Bearer keyword.
Now lets add Accept and Content-Type to the headers in the same way, but instead of our API workflow variable, we are going to give both of these keys a value of “application/json”, which simply specifies the type of data we are working with
We should see something like this in our Headers section now:
The Data section of the Rest API: JSON action will contain the information we want to pass to the API. Since we are trying to update the status of a conversation, our Key will be “status” and our value will be “done” which indicates that a conversation has been marked done.
Finishing Touches
We should now have a working API call triggered on a conversation update. Now we just need to add a conditional branch to our workflow to prevent looping infinitely on the first conversation update (quick way to learn about rate limiting, but a bad idea!).
For this example, I’ve created a condition that checks the changes object on a conversation update for any changes made to the tags. If changes were made to tags, the workflow will check what happened after the update and only continue if a tag was added to the conversation. This is different from just checking for a tag in the update because if you add a tag to a conversation that triggers a workflow, the update you make in your workflow is going to trigger the workflow again, and if that tag is still there we are going to cause another update event… and now we are stuck in another infinite loop. Targeting the changes says, don’t just check if the tag exists, but if it was added in the update made to the conversation which triggered this workflow.
Here’s what that looks like written out. Notice that I chose the Contains keyword in my conditional, tags are an array (meaning you can have multiple tags on a conversation) so we need to clarify that this array of tags should contain the ID of the tag we are adding to the conversation.
Possible Issues
Now we can save our workflow and head over to a test conversation. If all is well, adding the tag we specified to an open conversation will close the conversation. Hopefully, all went well and the conversation closed, congratulations! You just made an API call using workflows to update a conversation.
If nothing happened, head back to the workflow and look through the output of the workflow to see what went wrong (more information on how to do this can be found in our blog post How To Dig Through Workflow Output Data).
Some common issues that you may encounter:
-
If you are getting 401 unauthorized errors in the workflow output, double-check that you’ve included the Bearer keyword in your Authorization header. These issues will likely stem from some sort of error getting your API Key into the headers, so go check over that section.
-
If you see the update in the workflow log, but it didn’t get past your conditional, verify that you are targeting the correct tag by going to the tags setting page, clicking the edit pencil, and grabbing the tag ID from the URL in your browser. (../app/settings/tags/edit/{tag_id}
And of course, always feel free to reach out to support@kustomer.com or visit our knowledge base at help.kustomer.com for further assistance with API calls or workflow.