Custom channels allow you to synchronize a wide variety of third party messages into Front, which can then be tagged, assigned, and replied to by your teammates in Front. Whether you’re looking to integrate phone call logs, SMS services, or website live chat, this guide will walk through the necessary steps. For details on when to use a custom channel vs an application channel, please see our Overview page.

📘

Replies to channel messages must use the same channel.

You cannot receive an inbound message through a channel, and then reply to the message via another Front inbox such as your personal email account or a team inbox. If you would like to receive a message via a non-native channel and then reply to the message via another Front inbox, use the Import Message API endpoint instead.

Creating your channel

To create a custom channel, navigate to Settings → Inboxes and either create a new inbox or select an existing one. Under the “Channels” tab, click “Add channel” and then select “Custom”.

Configuring your channel settings

During the channel creation process, you’ll have options to configure the following settings:

Sending and receiving messages

Now that you have your channel configured, let’s take a look at how you can use your custom channel to actually send and receive messages.

As an example, imagine you are configuring a custom website live chat widget for your website, and you want those messages to be handled in Front.

Receiving messages (syncing messages into Front)

When a website visitor sends a message using your live chat widget, you would then POST the content of that message to the Incoming URL provided in the “API Endpoints” section of your channel’s settings. Your POST request here should match the specifications of the Receive custom messages endpoint. If the request is successful, the response will include status of accepted and a message_uid you can use to fetch the full message and conversation created in Front. To do so, use the Get Message endpoint and use the uid as a resource alias. For example, https://api2.frontapp.com/messages/alt:uid:abcd1234. Keep in mind that the process of creating the message and/or conversation record in Front is asynchronous — depending on factors such as the size of the message or existing conversation, it may take up to a few seconds to be available for fetching through the Get Message endpoint.

Managing threading

It’s worth noting that the Receive custom messages endpoint supports a metadata.thread_ref in the request body. That value is useful for controlling message threading, which defines how new conversations will be created in Front. By default, messages will be threaded by the sender, but specifying a thread_ref provides extra control that can be useful in some cases. For example, imagine that leads using our website live chat might return multiple times to our website over the course of a few weeks, but have different inquiries each time — in this case threading by sender would mean a very long single conversation. If we instead specified a thread_ref for each 24 hour session, conversations could be more easily oriented about actual live chat sessions.

Sending messages (accepting messages sent by agents in Front)

If you just want your custom channel to receive messages but don’t expect agents in Front to reply to them (like phone logs for example), there’s no need to build support for messages being sent from Front.

In the case of our chat widget example though, we would need to support the case where a Front teammate replies to an inbound message (or composes a new outbound). In this case, Front will POST the message to the Outgoing URL you set in the channel’s API Endpoints settings. The body will match the Message schema, an example of which is provided below:

{
  "_links": {
    "self": "https://api2.frontapp.com/messages/msg_55c8c149",
    "related": {
      "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
      "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
    }
  },
  "id": "msg_55c8c149",
  "type": "email",
  "is_inbound": true,
  "draft_mode": null,
  "created_at": 1453770984.123,
  "blurb": "Anything less than immortality is a...",
  "author": {
    "_links": {
      "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
      "related": {
        "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
        "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
      }
    },
    "id": "tea_55c8c149",
    "email": "[email protected]",
    "username": "leela",
    "first_name": "Leela",
    "last_name": "Turanga",
    "is_admin": true,
    "is_available": true,
    "is_blocked": false
  },
  "recipients": [
    {
      "_links": {
        "related": {
          "contact": "https://api2.frontapp.com/contacts/crd_55c8c149"
        }
      },
      "handle": "[email protected]",
      "role": "to"
    }
  ],
  "body": "Anything less than immortality is a complete waste of time.",
  "text": "Anything less than immortality is a complete waste of time.",
  "attachments": [
    {
      "filename": "attachment.jpg",
      "url": "https://api2.frontapp.com/download/fil_55c8c149",
      "content_type": "image/jpeg",
      "size": 10000,
      "metadata": {
        "is_inline": true,
        "cid": "123456789"
      }
    }
  ],
  "metadata": {}
}

You can then forward that message to whatever third party service you’re looking to integrate with — in the case of our live chat example we’d simply push the response message to the client-side chat widget.

In some cases, there might be errors that happen on your channel when Front POSTs a message to your custom channel. To help debug these issues, and to convey failures to users, you can include a certain error code and message in your response. If you wish to indicate that an error occurred while sending a message, you can respond in the following format:

{
  "type": [ERROR_CODE],
  "message": [MESSAGE]
}

If type is any of the following, it will indicate in the UI that the message failed to send.

bad_request
authentication_required
forbidden
not_found
request_timeout
too_many_requests
internal_error

Including the message property is optional. If you do include it, that string will be presented to users as the reason that the message failed to send, pictured below

When receiving a message sent from Front at your Outgoing URL, you can validate that the payload came from Front by following our example here.

That’s it! If you have any questions about custom channels or other feedback, please reach out on the Front Community.