Add a 3rd party integration

Introduction

Throughout the course of a conversation, we may want to communicate with systems outside of OpenDialog to send or receive data. This may be as simple as a "ping" to a URL representing a milestone in the user's journey, or an integration with an external data source which takes some input data from the conversation, and outputs some new data to return to the conversation.

OpenDialog communicates with 3rd party systems in 3 ways:

• with LLM's through LLM actions, which we covered here and you can learn more about here.

• through prebuilt actions, which you can read more about here.

• through custom actions, which we will be using for this tutorial guide.

What you need before you build

The webhook action allows you to send and receive data from an external service via a HTTP POST request to a provided webhook URL.

Some of your favorite third-party tools like Calendly offer API functionality, and you can find the webhook URL and your personal access tokens through your account settings.

If you don't have a service set up for your own custom systems, reach out to an engineering friend to get you set up.

See it in action

Step by step guide

Once you have a service that provides the desired functionality, it's time to create your action in OpenDialog.

Set up your new webhook action

Remember, you will need a webhook URL to interact with either provided by your engineering team or the third party tool you wish to interact with directly.

For this tutorial, we will be using a mock webhook example, available through Postman here.

Set up the input and output attributes

Now, we can set up the input and output attributes we want to send and retrieve via our action.

• Input attributes contain the information we will be collecting from our scenario and sending to our webhook endpoint.

• Output attributes contain the information we get back as a result of the action being performed.

For more information on attributes, check out the documentation on attributes here.

Once we have added our input attributes, we now need to configure the information we are expecting back as a result of our action once it has run. We do this, using output attributes.

Using the examples as listed in the instructions - the action we have set up will:

• retrieve the values for the first_name and last_name attributes in the scenario

• upon running the action, will provide the service with the values against first_name and last_name

• will return the value for full_name

Test your action

Now, we can test our action by providing values against the input attributes, and check the result the webhook action comes back with.

Example

{
  "first_name": "John",
  "last_name": "Smith"
}

If all goes well, you will get a succesful response back with the preset values from the endpoint.

Add your action to the conversation design

To execute the action at a particular moment in the conversation, we need to add it in the conversation design to the intent we want the action to run on.

With your action set up and your intent selected, let's set them up to work together!

You are all set! When your scenario matches this intent, your action will be run and the related output attribute will be populated.

Use output attributes in messages

You can use the value of output attributes from your action in your messages, to further personalise them. For example, if you want the welcome message to refer to the user by their name. To do so, we will need to update its message in the message editor, to reference the specific output attribute.

You have now succesfullly added an integration to your scenario, and used it's output in your messages!