API Terminology 101

New to Front? Not sure how to make sense of all our API resources? Wondering what the difference is between a conversation, message, and comment?

We understand. We've been there too. That's why we created this quick primer on Front terminology. We hope that it will help developers like you explore our API more quickly and with less trial and error.

If you already know what Front does, you can skip to the primer on the most important API resources.

What does Front do?

Front is a customer operations platform that makes it easy for teams to collaborate on communications across multiple channels such as email, SMS, chat, WhatsApp, etc. Front provides teammates with shared inboxes that bring in conversations from multiple channels and facilitate the daily work of Front users with spiffy internal collaboration tools such as comments, assignments, and mentions.

Beyond internal collaboration, Front incorporates powerful workflow automation features to help teams manage repetitive tasks and workflows. Automation can be applied through rules that handle routing conversations, assigning tasks to teammates, tagging conversations, and sending predefined responses through message templates, allowing workspaces/teams to focus on more complex and value-added activities.

Front is used by thousands of companies across different industries. For example, it is extremely valuable to customer support teams addressing complex customer issues, logistics companies managing myriads of conversations between numerous parties, finance and accounting departments needing robust workflow automations, hospitality management firms juggling reservations and inquiries across multiple properties, etc. Because of this, Front provides rich analytics and event information to help admins track how teams are performing and find ways to improve their customer communications and response times.

Last but not least, Front was built with integrations in mind (and this is where you come in!). Front integrates with various third-party applications and services, creating a more unified workspace for teams. Integrations with tools like CRM systems, project management platforms, and chat applications help streamline workflows and ensure that teams have access to the information they need when they need it. Integrations can work with our backend Core API, or can surface additional information directly in the UI, such as using the Plugin SDK to bring in third-party context related to a conversation, account, or contact into the Front sidebar or composer.

👍

Learn more about Front on our Help Center .

Important API resources

The following resources are important to understand. Our API provides many additional resources to interact with, but understanding these will give you the foundation you need to get started.

Companies, teams/workspaces, and teammates

API resources are generally available to:

  • the entire company using Front (use the Token Identity endpoint to learn what company your credentials have access to)
  • Teams / Workspaces (a collection of teammates using Front while working across shared inboxes with common rules, shifts, message templates, etc.)
  • Teammates (an individual teammate using Front with access to shared workspace resources but also their own personal resources, such as a private inboxes, private rules, private signatures, etc.)

Accounts & contacts

API resourceDescriptionExamples
AccountsAccounts represent external companies that Front teammates interact with. You can usually think of them as the company's customers. An account will normally include contacts that belong to the account.Teammate Huang receives a new SMS conversation from a contact she doesn't recognize in a personal Front inbox. She selects her CRM integration from the Front sidebar, and realizes that the contact belongs to an account she has had many interactions with. The contact was added to the account by another teammate, and the CRM integration displayed the association to Huang in the Front sidebar.
ContactsContacts represent people or entities such as shared emails that Front teammates interact with. Contacts can be added at the company, workspace/team, or individual teammate level. Contacts can be added to accounts or contact lists but can exist independently of either.Teammate Amber receives an email conversation from a customer contact named Bill introducing her to Jerome, who is a new hire at Bill's company, All Year Fireworks. In Front, Amber makes sure Jerome is added as a contact to the All Year Fireworks account. She also adds him as a personal contact with additional notes since she will have regular interactions with him. As time goes by, she adds additional known handles for Jerome other than his email address, such as his telephone number and social media handles.

Conversations (composed of messages and comments) in inboxes (powered by channels)

API resource

Description

Examples

Channels

Channels represent the communication streams in Front. They are the source of the conversations happening in Front inboxes.

Gmail, Outlook, custom SMTP, SMS, WhatsApp, Instagram, chat, Dialpad, Aircall, custom channels, etc.

Inboxes

Inboxes consolidate conversations from one or multiple channels into the Front user workspace. Inboxes can be individual to one Front user or shared across a Front team/workspace or company.

An individual Gmail channel shown as a personal inbox to a Front team member.

WhatsApp and SMS channels shown as one shared inbox to Front workspace/team members who respond to the conversations in the queue based on assignment rules.

Conversations

Conversations are the parent-level object representing the communications happening in Front inboxes. Conversations appear in one or multiple inboxes. Conversations are composed of messages that contain the actual replies or drafts users are composing. Conversations can have different ticket statuses set by the company if the ticketing feature is enabled.

You receive a new email from a customer in your personal inbox. This email thread is a conversation. The contents of the email the customer sent you represent the first message in the conversation. When you reply to the customer, you've added a second message to the conversation.

Messages

Messages belong to a single conversation. They represent the actual "body" of the conversation, such as email replies between people, text message content, attachments, etc.

Messages can also exist in draft format.

A shared inbox receives an incoming customer chat conversation from a custom channel developed for a specific company chat tool. The incoming content of the customer chat is the first message in the new conversation received in the shared inbox. When Teammate Alex replies to the customer via Front, a second message is created in the conversation and the customer receives this message through the custom website chat UI. The customer then responds and creates the third message in the conversation. Alex is now off-duty, so Teammate Leticia responds via Front, creating the fourth message.

Comments

Comments, known as "discussions" in the Front product but referred to as comments in the API for legacy reasons, represent internal communications that occur within one conversation between Front teammates. Comments appear inline in the conversation thread, but are visually distinguished from the messages in the conversation that are ultimately being sent through the channel. Comments belong to a single conversation.

Teammate Brenda receives an email from a customer with a billing issue. Brenda works in customer support, so rather than forward the email, walk over, or ping her colleague Arjit in accounting about the issue, she mentions Teammate Arjit within a comment in the conversation. Arjit is then brought into the conversation, can read Brenda's internal comment as well as the email messages Brenda has had with the customer, and respond with a comment of his own or reply directly to the customer with another email message.

Tags

Tags are labels you can attach to conversations for your organizational purposes and for triggering advanced workflow automations through rules. Tags can be added at the company, team/workspace, or individual teammate levels.

Teammate Casey creates a rule that automatically moves a conversation to a high-priority shared inbox whenever the tag "High ARR Customer" is applied to a conversation. This tag is available at the company level because they want anyone to be able to use it.

They also apply individual tags to conversations for their own organizational needs. These tags are not available to their teammates or team/workspace.

Message Templates

Message templates save teammates time responding to similar communications. The templates can exist at the company, team/workspace, or individual level, and can be organized into message template folders.

Teammate Agnes receives a very common question via an email conversation in the Support inbox about getting started with the software her company sells. She opens a message template within the Support team/workspace folder and fires it away to the customer. The message template auto-fills the recipient's name in the email, provides a pre-populated response to the common question, and links to a Front-powered knowledge base article for more details.


Rules

API resourceDescriptionExamples
RulesRules are powerful workflow automations that can be set up at the company, team/workspace, and teammate level. Rules help automate complex or repetitive tasks such as assigning a conversation to the correct teammate, moving priority conversations to a special inbox, notifying a manager of an SLA breach, and more. Because rules are so fundamental to the operations of a company, they are currently read only in the API.A Front team/workspace manages multiple inboxes. Some inboxes take higher priority than others, so company admins configure rules that assign emails in the high priority inboxes before assigning emails in lower priority inboxes.

Events & analytics

API resource

Description

Examples

Events

Events represent a myriad of actions that occur in Front, such as a conversation being archived, moved to a different inbox, or assigned to a teammate.

A Front rule tags a conversation with "SLA Breach" due to a lack of response to the customer, moves the conversation to a priority inbox, and assigns the conversation to Teammate David, who is on call. Front generates events for the conversation being tagged, moved, and assigned to a new teammate.

Analytics

Analytics represent statistics such as resolution times and messages received that can be consolidated into reports or exports. The data from these analytics exports/reports can be fed to external systems or automated for distribution to teammates analyzing team performance.

Analytics can be gathered for a range of Front categories such as inboxes, channels, teammates, teams/workspaces, events, and more.

Teammate Joaquín is in charge of monitoring how well his team is responding to customer inquiries. He utilizes the Front analytics dashboard to review team/workspace performance, but also automates exporting the data to other systems through the API.


Knowledge bases


API resourceDescriptionExamples
Knowledge BasesKnowledge bases represent a company's documentation site, powered by Front. Knowledge bases exist at the company level and can be offered in different locales.The Front Help Center is powered by a Front knowledge base.
Knowledge Base ArticlesThe help topics that make up a knowledge base. Articles can be part of Knowledge Base Categories, but don't have to be.This is a Front knowledge base article about Connectors, contained within the relevant knowledge base category .