Custom Integrations

Nathan Begbie Updated by Nathan Begbie

Why Use a Custom Integration?

Custom integrations can power up your helpdesk experience by linking your Turn service to external systems like Customer Relationship Management System, your patient database or whatever external service you are running.

What Can You Do With Custom Integrations?

  • Actions - Allowing helpdesk operators to trigger external webhooks for a given message
  • Suggested Replies - Given the message history with a given patient, generate a suggested reply that a helpdesk operator can choose to use
  • Additional Context - fetch additional data and display it in the sidebar of your application. Thisis particularly useful should you wish to store additional contact data in a separate data store.

Setting Up the Custom Integration

First, navigate to "Settings" and then click the "Integrations" tab, and then from the drop down button "Add an Integration", select "Custom Integration"

At this point you need to provide a couple of fields:

Name: How you will identify the relevant integration.

URL: this is the endpoint that your custom integration will call with various JSON payloads. Your service can only receive payloads at this single endpoint.

HTTP Authentication type and API Token: these features are required when setting up a custom integration with Turn.io, but they relate specifically to how your service works. The HTTP Authorization type can either be BEARER or TOKEN. This just means that, say for example you chose BEARER and you set the API Token to 123, then whenever Turn makes a request to your service, it will include the HTTP Header Authorization: Bearer 123 in every call. This means that you can be sure that the service is able to verify that the requests are coming from Turn. If however, you are just testing out this functionality, and you do not want to implement any authentication in your application, you do not have to worry about what you select or enter in these fields (but you will need to enter something).

Once you select 'Create Integration', Turn.io will attempt to send a handshake to the service that you just created. If you haven't set anything up yet, that's okay. The handshake will fail. Once you've set up your service, you can attempt to re-enable the

Implementing Your Custom Integration

As long as you are able to set up a service that can receive HTTP calls, you can integrate with what ever service you want to. However, we've provided a few starter kits and examples in Javascript and Python

Using the Turn Javascript Integration library

One of the ways in which you can create a custom integration library is by using the Turn npm package. The library requires that you give it the SECRET that Turn generates when it creates the integration. It uses this secret to authenticate the calls from Turn.

A very detailed breakdown of the calls and responses that are available to you are given in the developer documentation, which we strongly recommend that you read.

If you would like to try creating your own custom integration using the Javascript library, use the pre-built Repl.it we have set up for you.

Other Examples in Python

There are a number of repos that we have created as examples to try out and experiment with. They are ready-to-run examples with Repl.it Click here to see them all.

If you'd like to walk through some of the functionality available with custom integrations, you can use some template examples as a starting point with the:

turnio-duckduckgo-replit - An example Turn.io suggested reply integration on Replit. This will return the abstract from the DuckDuckGo API as a suggested reply in the Turn.io UI

turnio-integration-replit - An example Turn.io UI integration on Replit. This extends the Turn UI with a quick reply, custom profile information, and action menus.

Was this article helpful?

New to webhooks?

How to set up a RapidPro integration

Contact