Front Platform

Welcome to the Front Platform. You'll find comprehensive guides and documentation to help you start working with Front as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Creating a Custom Channel

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 a partner channel, please see our Overview page.

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:

Setting

Description

Channel contact type

The contact type for the messages that will be sent for this channel

Options:

  • Custom:
  • Email
  • Phone

Channel reply mode

Whether users should be able to reply to messages received by this channel

Options:

  • This channel (default)
  • Cannot reply

Allow new messages from channel

Whether users should be able to compose new outbound messages from the channel.

Disabled by default — note that new outbound messages can be sent by custom channels, but replies will not be threaded into the same conversation. If that use case is important to you, please use a partner channel instead.

API Endpoints

Incoming: the URL you should POST new incoming messages to

Outgoing: an optional URL that Front will use to POST any messages sent using the channel

See “Sending and Receiving messages” below for more details

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. 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.

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 to [email protected].

Updated 2 months ago


Creating a Custom Channel


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.