Custom Channel Tutorial

With our Custom Channel you can easily connect any message-based system to Userlike and complement the Channels we already support. This could be another messenger app, an own SMS gateway, or your email server.

Messages coming in through the Custom Channel appear in the Message Center and senders are identified as Contacts through their email address. When your Operators respond in Userlike, the Contacts receive the reply on the message system you connect.

For your Custom Channel you need to implement two JSON API endpoints, one on the Userlike side – where you send messages, and one on your message system’s side – where you receive messages. The Custom Channel supports text, voice and media messages, along with line preview for media links.

Channel setup

Start by creating a Custom Channel in the Channel wizard. There you fill out the following fields:

  • **Channel name:** Name of your Custom Channel
  • **Outbound URL:** URL of your API endpoint
  • **Outbound auth token:** Authentication token to access your API endpoint
  • **Inbound auth token:** Authentication token to access the Userlike API endpoint
  • **Inbound URL:** URL of the Userlike API endpoint. It will be generated and appear in the Channel settings after the Channel setup
  • **Default Widget:** Widget that will handle messages sent to the Channel. The Widget’s settings apply to assign the right Operator, display the correct language and use the right privacy settings.
  • **Additional Widgets (upcoming feature):** Widgets on which you enable the transfer of Conversations from your Website Messenger to the Custom Channel.

After filling out the form, click **Create Channel**.

API documentation

In the following sections you learn how to set up your API endpoint and how to access Userlike’s API endpoint. This should give you a straightforward understanding of how to get your Custom Channel up and running with your use case.

TopicDescription
Inbound messagesSending inbound messages to the Userlike API endpoint
Inbound media messagesSending inbound messages with media attachments to the Userlike API endpoint
Outbound messagesSending outbound messages to your API endpoint
Outbound media messagesSending outbound messages with media attachments to your API endpoint
ExamplesPython server example

Sending inbound messages to the Userlike API endpoint

To send a message to the Custom Channel you need to send a JSON paket as POST request to the **Inbound URL** endpoint, which you find in the Channel’s settings.

Include an **API-SECURITY-TOKEN** header in the POST request, with the value of the **Inbound auth token**, which you also find in the Channel’s settings.

The email field in the JSON message describes the identity of your Contact. Be aware that this field needs to be verified on your side because it enables users with the same email address to gain access to previous Conversations with the Contact.

Sending inbound messages with media attachments to the Userlike API endpoint

To send a message with a media attachement to the Custom Channel you need to send a JSON paket as POST request to the **Inbound URL** endpoint, which you find in the Channel’s settings.

Include an **API-SECURITY-TOKEN** header in the POST request, with the value of the **Inbound auth token**, which you also find in the Channel’s settings.

With the **"url"** field in the JSON message you can pass a URL to your media file. Userlike will try to fetch the asset and convert it to a preview that can be displayed in the Message Center. Userlike will store a copy of the asset with the Conversation for later access. The preview supports all common media types.

Sending outbound messages to your API endpoint

For every message sent by an Operator in your Message Center, Userlike sends an HTTP POST request to your API endpoint, which is defined by your **Outbound URL**.

Include an **API-SECURITY-TOKEN** header in the POST request and make sure to check the value against the value of your **Outbound auth token**.

Sending outbound messages with media attachments to your API endpoint

For every message with a media attachement sent by an Operator in your Message Center, Userlike sends an HTTP POST request to your API endpoint, which is defined by your **Outbound URL**.

Include an **API-SECURITY-TOKEN** header in the POST request and make sure to check the value against the value of your **Outbound auth token**.

Python Server Example

We prepared a Python sample server that implements a sample POST request handler and a console-based input client to test the Custom Channel setup.