Custom Integrations

Nathan Begbie Updated by Nathan Begbie

Setting Up the Custom Integration

First, navigate to "Settings" and then click the "Integrations" tab

Next, from the drop 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.

Implementing Your Custom Integration

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