Custom Channel

With Twilio Autopilot, you can build your own channel integrations to integrate your custom-built chat or existing messaging platforms that we don't support natively. In this guide, we will walk you through sending a message to the custom channel endpoint and the structure of the Autopilot response so you can build a bot on any channel.

When should I use a custom channel?

You should use a custom channel when you want to build a bot on a channel that Autopilot does not support natively. For example, if you want to build a bot on your custom-built webchat or a platform like Intercom, Front or Discord.

Sending a Message

When a user sends a message to the bot, you need to receive that message and send it to the custom channel endpoint.

Custom Endpoint

To send a message to Autopilot, you need to make an HTTP POST request to the custom endpoint you can find below:

https://channels.autopilot.twilio.com/v2/{AccountSid}/{AssistantSid}/custom/{YourCustomChannelName}

Replace the following in the url:

{AccountSid} = You Account Sid found in Console->Autopilot->Your Assistant ->Overview ->Properties

{AssistantSid} = You Autopilot Assistant Sid found in Console->Autopilot->Your Assistant ->Overview ->Properties

{YourCustomChannelName} = The name of your custom channel (For example: "webchat" or "discord")

Parameters

The Custom Channel endpoint takes the following parameters:

Authentication

Your POST request must be authenticated using your AccountSid and token like any other Twilio API request.

The Response

When you send a message to the custom endpoint you will get a JSON back with the content to display back to the user.

{
	"response": {
		"says": [
			{
				"speech": "Good morning! Welcome to the <say-as interpret-as='interjection'>Owl Insurance Company</say-as>. I'm your virtual assistant. How can I help you today?",
				"text": "Good morning! Welcome to the Owl Insurance Company. I'm your virtual assistant. How can I help you today?"
			}
		],
		"shows": [{
		            "display_text": "Twilio Owls"
		            "images": [{
		                "label":"owl"",
		                "url":"https://demo.twilio.com/owl.png""
		            }, {
		                "label":"Another Owl"",
		                "url":"https://demo.twilio.com/owl.png""
		            }]
		    }]
		,
		"listen": {
		}
	},
	"dialogue": {
		"sid": "UK410ec15153a63ff0bed851467309bcbd",
		"current_task": "insurance_greeting",
		"user_identifier": "nico",
		"memory": {
			"existing_customer": "false",
			"aquisition": "website",
			"twilio": {
				"custom.chat": {
				}
			}
		}
	}
}

On the Say the Speech version includes SSML, the Text version strips out the SSML.

Your channel integration should take this content and render it back to the user.

Autopilot will still do all the dialogue and state management for Actions like Collect. It will just respond with one message at a time.

Autopilot URL Parameters

Example 1: Using TargetTask parameter at the end of the URL

https://channels.autopilot.twilio.com/v2/<ACCOUNT_SID>/<ASSISTANT_SID>/custom/{YouCustomChannelName}?TargetTask=handle_appointment_confirmation

Any message sent to number or messaging service configured with this URL will land in the handle_appointment_confirmation task.

Example Function

- Make sure you enable ACCOUNT_SID and AUTH_TOKEN in the Functions -> Configure.

var got = require('got');

exports.handler = function(context, event, callback) {
    
    // Takes the first message, creates the channel webhook
    console.log(event);
    
    // Pipe body to Autopilot
    let requestPayload = "UserId=user123&Language=en-US&Text=hi there"

    got.post('https://channels.autopilot.twilio.com/v2/'+context.ACCOUNT_SID+'/{AssistantSid}/custom/chat', 
    { 
        headers: { 
            'content-type': 'application/x-www-form-urlencoded',
            'accept': 'application/json',
            'authorization' :  'Basic ' + new Buffer(context.ACCOUNT_SID+ ':' + context.AUTH_TOKEN).toString('base64')
        },
        body: requestPayload
    }).then(function(response) {
        let apResponse = JSON.parse(response.body);
        console.log(apResponse);
        callback(JSON.stringify(apResponse));
        
    }).catch(function(error) {
        callback(error)
    });
  
};

Deprecated Versions

• Custom Channel V1 is deprecated. It will continue to work but it won't be evolved to support future functionality.