Actions use APIs to connect to external systems to fetch and/or update existing data. That’s why it’s important to keep a couple of things in mind when setting up Actions in Intercom.

If you’re utilizing third-party (not in-house built APIs) with Actions in Intercom, you likely have little to no control over how they work or the response you receive from a request.

That being said, the below guide is still useful guidance, but some sections may not be fully applicable to your use case.

Our engineers have compiled a list of points to note when designing or modifying your existing APIs to work with Fin and Actions in Intercom.

First, we strongly recommend that you enable Identity Verification. Identity verification is the most important security control to set up. This will prevent malicious actors from impersonating your users via the Messenger which can lead to them getting access to someone else’s conversations or to execute Actions on that user’s behalf.

Our team is currently working on a feature that allows you to sign multiple attributes via our JavaScript API using JSON Web Tokens (JWTs). If you’re interested in this feature, feel free to contact our Support team via Messenger and they’ll be happy to work with you to get this enabled.

Protecting attributes from updates is most important for the identifying attributes in Actions, when the Action surfaces sensitive data or manipulates data.

For example, if your Action is making a request to API using “GET /accounts/<account_id>/invoices” then you want to be sure account_id is protected so the user can't just enumerate account_ids collecting data. However, if your action is "GET /pizza-order-status/<order_id>" then you might not care about the trustworthiness of "order_id" and you don't care whether or not you surfaced this info to the right person.

Moreover, you should ensure that the attribute your Action uses to uniquely identify your users (email, for example) is trustworthy. This means that you need to know that you trust the source of your Action’s identifying attributes. For example, if your Action identifies the user by user_id, identity verification is signing the user_id attribute or if your Action identifies the user by email or any other attribute, then that attribute is protected, and it's not collected from the End User without some verification.

This prevents malicious actors from being able to, for example, provide someone else's email address and access an action such as “Get bank statements by email”, which would expose sensitive financial data.

Where possible, we suggest that you do not use email as a primary identifier of fetching data of your users, but something more random such as a unique, non-guessable user ID.

For performing Identity verification on leads, our team is currently working on a One Time Password (OPT) feature that will help you verify someone’s identity if they’re contacting your support as a lead. If you’re interested in this feature, feel free to contact our Support team via Messenger and they’ll be happy to work with you to get this enabled.

You should also ensure that the user can’t perform actions that they are not authorized to do, for example, cancel someone else’s order by knowing the order ID. This logic is not handled within Intercom and you/your security team should carry out a risk assessment and come up with appropriate methods to handle authentication and authorization.

Intercom currently supports static tokens, HTTP tokens and OAuth (closed beta, contact us via the Messenger for more information on this). Whatever token you use, it is your responsibility to make sure it is kept secret and updated if it gets leaked anywhere as soon as possible. As best practice, we recommend you use OAuth tokens wherever possible.

Ideally, the API should only return the data necessary for your Workflow. However, this can be unrealistic and the API might return a good amount of data that’s actually not required to carry out the Workflow where the Action is used.

If you’re building APIs from scratch to be exclusively used with Actions and Fin Workflows, you can either:

Some considerations that should be included when deciding what and how much data your API returns include:

Moreover, you should always remove the ability for users to provide malformed data or just type things.

For example, you should not ask the user to type in their account ID, but present them with their account IDs (based on a known, secure identifier) and let them pick from a dropdown list. More on how to collect data from users can be found here.