Connect an external API with your WhatsApp Flows

Using custom integrations, it’s possible to configure requests to external APIs and use them in a WhatsApp flow to obtain data and perform actions in your system. In this guide you will learn how to configure a custom integration with requests that use API keys as an authentication scheme.

Disclaimer: Request configuration requires understanding of APIs and authentication schemes, so we recommend you to have a developer or tech-savvy person do or help during this process

Understanding custom integrations

To make the process of configuring integrations easier in the long run, we think it’s important to understand the nature and relationship between the different entities involved in this guide:

  • Integration: Entity that allows us to group multiple related requests. An integration also contains basic configuration options, like the authentication scheme that all the requests that belong to it will use and the definition of the fields used to authenticate with your API.
  • Credential: Entity that stores values for the authentication fields defined in the integration it belongs to. An integration can have multiple credentials, which allows us to, for example, change the authenticated user or account in the API request depending on the WhatsApp flow we use the integration in.
  • Action: Entity that stores the configuration of a request to an API. We can define inputs and outputs in an action, which will allow us to use the data provided by the WhatsApp user in the request and pass parts of the API response back to the WhatsApp flow, respectively. As mentioned before, an integration can have multiple actions, all using the same authentication scheme.
entity relationships

Creating the integration

To create a custom integration, we will first need to log in to Dashboard. After that, we can access the integrations section via the sidebar:

Sidebar

In that section there will be a list of available CRM and custom integrations. To create a new custom one, we need to click the “New integration” button.

new integration button

This will redirect us to the integration creation view. In the first section, we can set our new integration’s name and optionally a description and logo. After that, we can set the authentication scheme for all the actions we will create for the integration. Currently, we only support API key authentication.

setting name and authentication scheme

By clicking on “Save and continue”, the integration will be saved with the currently set data and the authentication section will appear.

Configuring authentication

Once the basic info of our integration is saved, we need to configure the authentication that the actions will use later on. For API key authentication, there are currently 4 steps:

  1. Adding authentication fields: In this step we will define the fields that our APIs need for authentication. For example, Truora’s APIs just require an API key in every request’s headers. As such, we would need to create only one authentication field:

    adding an authentication field

    Some things to note here:

    • We must set an identifier for the authentication field. This identifier must only contain lowercase, digits and underscores (’_’). It must also not start with a digit or underscore and not end with an underscore. We can also optionally enter a custom name for the field to easily recognise it later.
    • We can select text and password types for an authentication field. The difference between the two is that password authentication fields have their values end-to-end encrypted in our systems.
    • At this point we are not setting any actual API key, we are just defining the fields that will contain those keys. Please do not enter any credential at this point.
    • Authentication fields can be required or optional. We won’t need to enter values for optional fields when setting actual credentials.
  2. Configuring test request: With the authentication fields added, now it’s time to configure a request to test the authentication. Click “next” and a component will open to set the request data. When setting headers we can click on the “+” button inside a header’s value field to add a reference to one of the authentication fields defined earlier.

    configuring a test request

    In our case, we are setting a reference to our authentication field in the “Truora-API-Key” header. We recommend using an endpoint that only retrieves information so that you don’t accidentally make changes to your system data while making tests.

  3. Creating a credential: After finishing our request configuration and clicking on “Save and continue”, the credentials step will show up. We first need to create a credential that will contain values for our authentication fields. To do so, click the “Add credentials” button. A modal will appear, in which we can set our new credential’s name and enter actual values for each authentication field.

    testing step
    adding a credential
  4. Actually testing the authentication: Clicking on “Save and continue” will trigger a request to your API (with the data of the credential we created), and seconds later the response will be shown to you. Make sure the status code and the response body are correct.

    testing in progress
    test response

    If the response is correct, we can proceed by clicking the “Close” button. If there was an error, try checking your configured test request and/or create a new credential in case you think an incorrect API key was entered.

    test response failure

Setting additional credentials

Now, we will be shown a table containing our existing credentials. Here, we can also:

  • Create additional credentials (we recommend creating a credential pointing to a testing account/user, if you haven’t already done so)
  • Edit the name of existent credentials
  • Test any credential we want (using the test request configured in the previous step)
  • Remove credentials we don’t need anymore or that had incorrect values
credentials table

Creating actions for our integration

After we are done managing credentials, clicking on “Continue to actions” will show us the actions section.

credentials table

To create our first action, we need to click the “Add action” button. Another view will appear with a number of steps:

  1. Setting a name and optional description to easily recognise the action. In this guide we will create an action to retrieve a specific order’s status given its ID.

    new action's name
  2. Defining inputs. These will be used to receive values from previous steps in our Whatsapp flow and insert them in our request. In this case, our only input will be the order ID given by the user in the flow.

    action inputs

    The input’s identifier follows the same rules used for authentication fields’. One can also create optional inputs for things like filters that will not be always provided by the user.

  3. Configuring the actual request in the same manner as the test request in the authentication section. However, in this case we can add references to both authentication fields and inputs.

    action headers
    action query parameters

    As you can see, we have added a query param containing a reference to our order ID input and a header with a reference to our API key.

  4. Testing the request by setting a test value for each input we defined earlier and selecting a credential. Here we recommend to use a credential pointing to a test account or user.

    test action step
  5. Reviewing the response and setting outputs. After making sure the response has a correct status and body, we can select certain parts of the latter to set them as outputs.

    test response

    In our case, there are various potential attributes to use, but we will only create an output for the status property. This way, we can use it in future steps inside a flow.

    setting the action's output

    As you can see in the image, the properties from the JSON can be selected in the identifier field, but there might be cases when our API sometimes responds with additional fields. For these cases, we can manually enter the identifier and set the output as not required.

With all of this done, all that is left is clicking on “Save action” to get redirected to the initial actions section. From here, we can click on “Finish integration” to get redirected to the general integrations view. Our new integration should now appear there.

actions table with our new action
our new integration!

Next steps

Once we have successfully created a custom integration, we can use its actions inside a flow (via our flow builder) to interact with external systems. You can find a guide for that here!