NAV Navbar
  • Introduction
  • Getting events from Front
  • Controlling Front
  • Dialogs
  • Accessing Front data
  • Introduction

    Front supports plugins. A plugin is a small web application that can communicate with Front using a JavaScript API. It allows you to extend Front with new features, making it possible to connect it with other tools you use and optimize the workflow of your team:

    Plugin example

    Creating a plugin

    You can use any web framework or library you wish: it's just a web page that can communicate with Front. It has to be hosted on your servers and include our library. Just add:

    <script src="https://dl.frontapp.com/libs/frontjs.min.js"></script>
    

    To create a new plugin, go to > Plugins & API > Plugins ans click on "Add a plugin":

    Add a new plugin

    We provide a small sample plugin that shows some basic things you can do using our Javascript API. You can check the code on https://github.com/frontapp/frontapp.github.io. If you want to test directly, you can even set the plugin URL to be https://frontapp.github.io/plugin.html to see what the basic plugin can do.

    Security

    In order to avoid compromising your data, every time the plugin SDK is loaded, Front will check if the plugin's current URL matches the one saved in the settings. If it doesn't, no data will be sent to it. This is why we recommend designing your plugin as a single page applications.

    Authentication

    On your side, it might be desirable to ensure that your plugin is indeed requested by Front, especially if it displays confidential information.

    Front provides a simple way to verify that your plugin is requested by Front. In the settings of your plugin, you will see an authentication secret. This secret will be passed as a query parameter named auth_secret when requesting your plugin.

    Plugin authentication

    If you need any help in getting your plugin working, would like more information or a new feature please drop us a line at api@frontapp.com we will be happy to help.

    Mobile restrictions

    Plugins can be used on Mobile devices directly from a conversation. Some helper methods have not been implemented and will not work on iOS and Android:

    - insertHTML
    - setPanelWidth
    - updateDraft
    - addTopic 
    

    Getting events from Front

    Front.on('conversation', function (data) {
        // triggered when a conversation is loaded
    });
    
    Front.on('no_conversation', function () {
        // triggered when no conversation is selected
    });
    
    Front.on('panel_visible', function (visible) {
        // triggered when your plugin becomes visible or invisible
        // you can also test Front.visible
    });
    

    Every time the current conversation changes (for example, when you click a new conversation in the list), an event is sent to our library.

    The data object sent to the callbacks of the event contains 4 fields:

    The contact object will look like this :

    {
      "id": "crd_55c8c149",
      "handle": "john.doe@frontapp.com",
      "initials": "J",
      "display_name": "John Doe",
      "description": "",
      "avatar": null,
      "color": "hsl(47,60%,70%)",
      "source": "email",
      "role": "reply-to",
      "num_notes": 0
    }
    

    The conversation object will look like below, for clarity sake some objects have been removed:

    {
      "id": "cnv_55c8c149",
      "link": "https://app.frontapp.com/open/cnv_55c8c149",
      "message_type": "email",
      "status": "unassigned",
      "replied": false,
      "reacted": false,
      "num_messages": 1,
      "contact": {}, // Similar to the contact JSON above
      "assignee": "Teammate-alias",
      "inboxes": ["support"],
      "followers": ["jane"],
      "tags": [],
      "seen_by": ["jane"],
      "subject": "test again",
      "summary": "Just testing some stuff",
      "has_draft": false
    }
    

    The message object will look like below, message found in otherMessages will not have body field as they are only loaded when expanded.

    {
      "id": "msg_55c8c149",
      "ext_id": "086b97289e93b01b@frontapp.com",
      "type": "email",
      "status": "imported",
      "date": 1422909585000,
      "inbound": false,
      "blurb": "This is a test",
      "recipient_opened_date": null,
      "subject": "More testing",
      "body": "This is a test", // body will only be loaded in the first message
      "from": {
        // Similar to the contact JSON above
      },
      "recipients": [
        {
          // Similar to the contact JSON above
        }
      ],
      "attachments": [{
          "id": "fil_55c8c149",
          "uid": "1234567890",
          "filename": "chart.jpg",
          "content_type": "image/jpeg",
          "size": "391970"
      }]
    }
    

    Controlling Front

    The javascript library exposes several helper functions to send commands to the app. Most functions accept either an alias or an object returned by Front.fetchInboxes, Front.fetchAllowedTeammates or Front.fetchAllowedTags.

    Unassign

    Front.unassign();
    

    Unassign the currently selected conversation.

    Assign

    Front.assign('teammate_alias');
    

    Assign the currently selected conversation to a teammate.

    Toggle archived

    Front.toggleArchive();
    

    Toggle the archive flag of the currently selected conversations.

    Toggle trashed

    Front.toggleTrashed();
    

    Toggle the trashed flag of the currently selected conversations.

    Open URL

    Front.openUrl('https://app.frontapp.com/open/cnv_55c8c149');
    

    Request Front to open a URL. Using a conversation URL (cf: the field link in the conversation object), it lets you open a conversation.

    Compose new message

    Front.compose({
        from: 'mychannel@company.com',
        to: ['someone@somewhere.com'],
        cc: ['copy@example.com'],
        subject: 'Optional subject',
        body: 'Optional body',
        attachment_uids: [],
        hide_composer: false
    });
    

    Open a new message. Will do nothing if an inbox cannot be selected (for example, if you try to compose to a Twitter handle, but have no Twitter inbox).

    The options object accepts the following fields :

    Compose reply

    Front.reply({
        to: ['someone@somewhere.com'],
        subject: 'Optional subject',
        body: 'Optional body',
        attachment_uids: []
    }, replyAll);
    

    Send a reply to the latest message of the current conversation. Will do nothing unless a conversation is selected.

    The options object accepts the following fields :

    The replyAll parameter will transform a simple reply in a reply all if set to true.

    Compose forward

    Front.forward({
        to: ['someone@somewhere.com'],
        subject: 'Optional subject',
        body: 'Optional body',
        attachment_uids: []
    });
    

    Update draft

    Front.updateDraft(draft_id, {
        recipients: {
            to: ['email@example.com'],
            cc: [],
            bcc: []
        },
        attachment_uids: []
    }, callback);
    

    Updates the draft of the current conversation. You can get the draft_id by calling the fetchDraft method.

    Tagging/Untagging a conversation

    Front.attachTag('feature_request');
    Front.detachTag('feature_request');
    

    You can add or remove tags from a conversation. For this, you will need the alias of the tag. The alias is a URL-friendly, human-readable name for the tag that is unique to your company. You can find the alias of a tag by looking at your browser URL when you click on a tag in Front.

    Moving a conversation to an inbox

    Front.moveToInbox('contact');
    

    You can move a conversation to an inbox. You can request a conversation to be moved to a team inbox not accessible by the user, but they will get a confirmation dialog (as they will lose access to the conversation).

    Front.search('search query terms');
    

    Perform a search

    Insert HTML

    Front.insertHTML('Automatically inserted HTML');
    

    Lets you insert HTML in the message composer where the user cursor is.

    Add topic

    Front.addTopic({
        type: 'web',
        name: 'Link example',
        ext_link: 'http://example.com'
    }, function() {
        console.log('done');
    });
    

    A topic is an external link attached to your conversation. It has a type, a name and an URL.

    Field Type Description
    type String Type of the topic. Can be either web, github, jira, trello or assana.
    name String Name of the link which will appear on the conversation.
    ext_link String URL of the topic.

    Set Width

    Front.setPanelWidth(400);
    

    The plugin initially appears with a width of 300px. However, you can request more space very easily:

    Dialogs

    Dialogs can be used to ask the user for confirmation or input a value. Use them instead of window.alert, window.confirm, window.prompt.

    Unlike window.alert, Front dialogs are asynchronous and expect a callback.

    Alert

    Front.alert({
        title: 'Title of the alert',
        message: 'Body of the alert.',
        okTitle: 'Label of the OK button (optional)'
    }, function () {
        console.log('User clicked OK.');
    });
    

    The Front.alert() method displays an alert dialog with the optional specified content and an OK button.

    Report

    Front.report({
        title: 'Title of the report',
        message: 'Body of the report'
    }, function() {
        console.log('User closed the report');
    });
    

    The Front.report() method displays an alert dialog with the optional specified content without any buttons.

    Confirm

    Front.confirm({
        title: 'Title of the confirm dialog',
        message: 'Body of the dialog.',
        okTitle: 'Label of the OK button (optional)',
        cancelTitle: 'Label of the OK button (optional)'
    }, function (confirmed) {
        console.log('User confirmed?', confirmed);
    });
    

    The Front.confirm() method displays a modal dialog with an optional message and two buttons, OK and Cancel.

    The callback will received a confirmed boolean, indicating whether the user clicked OK or Cancel.

    Prompt

    Front.prompt({
        title: 'Title of the confirm dialog',
        message: 'Body of the dialog.',
        okTitle: 'Label of the OK button (optional)',
        cancelTitle: 'Label of the OK button (optional)'
    }, function (val) {
        console.log('User entered:', val);
    });
    

    The Front.prompt() method displays a dialog with an optional message prompting the user to input some text.

    The callback will receive a val with the text entered by the user (or null if the user canceled).

    Prompt Date

    var position = {
        left: event.screenX - window.screenX,
        top: event.screenY - window.screenY,
    };
    
    Front.promptDate({
        position: position,
        val: defaultDate,
        before: forceSelectionBefore,
        after: forceSelectionAfter
    }, function (date) {
        console.log('User selected:', date);
    }));
    

    The Front.promptDate() method displays a dialog to select a date. It will pass the callback a JavaScript Date (or false if the user canceled):

    Item List

    Front.fuzzylist({
        items: [
            {title: 'Options 1'},
            {title: 'Options 2'},
            {title: 'Options 3'}
        ]
    }, function (item) {
        if (item)
            console.log('User selected', item.title);
        else
            console.log('User canceled');
    });
    

    The Front.fuzzylist() method displays a list of elements with a search field (for quick selection).

    You can pass extra parameters in addition of title. They will still be in the item when the callback is called.

    Copy to Clipboard

    Front.copyToClipboard('payload');
    

    This method will copy a string to the user's clipboard.

    Accessing Front data

    The plugin API enables you to extract some data from Front, always remember that these data are relative to the teammate using the plugin, if teammate A does not have access to inbox B then you will not see inbox B when calling fetchInboxes().

    Fetching data through the plugin API is asynchronous, this means that you will need to provide the js library with a callback every time you want to retrieve data.

    Please also note that the data you extract from these calls is just a snapshot of Front's state when you asked for it, any updates happening afterward will not update the data you received nor call your callback again.

    User Profile

    {
        "url": "/api/1/companies/planet_express/team/bender",
        "alias": "bender",
        "given_name": "Bender",
        "family_name": "Rodriguez",
        "email": "bender@planet-express.com",
        "avatar": "https://nibbler.frontapp.com/api/1/noauth/avatars/123",
        "admin": true
    }
    

    You can get basic info about the user currently connected to Front by accessing Front.user. Keep in mind that the profile might change over time if the user changes their profile.

    Fetch Inboxes

    Front.fetchInboxes(function (inboxes) {
        if (!inboxes) return;
    
        console.log(inboxes);
    });
    

    Sample JSON for an inbox

    {
      "avatar_type": "inbox",
      "class": "inbox",
      "alias": "support",
      "name": "CS",
      "color": "#E151E1",
      "num_new": 30,
      "num_unassigned": 30,
      "last_unassigned_date": 1423821859000,
      "participants": [
        "john"
      ],
      "tags": [
        "test",
        "important"
      ],
      "owner": null,
      "settings": {
        "auto_assign": true,
        "attachment_size_limit": 9437184
      }
    }
    

    This call will send you all the inboxes accessible by the current user (private and shared).

    The callback's inboxes parameter will contain an array of inboxes.

    Fetch Channels

    Front.fetchChannels(function (channels) {
        if (!channels) return;
    
        console.log(channels);
    });
    

    Sample JSON for a channel

    {
      "id": "cha_123",
      "type": "imap",
      "type_name": "email",
      "is_private": false,
      "message_type": "email",
      "address": "contact@company.com",
      "send_as": "contact@company.com"
    },
    

    This call will send you all the channels accessible by the current user.

    The callback's channels parameter will contain an array of channels.

    Fetch teammates

    Front.fetchAllowedTeammates(function (teammates) {
        if (!teammates) return;
    
        console.log(teammates);
    });
    

    Sample JSON for a teammate

    {
      "avatar_type": "teammate",
      "class": "teammate",
      "alias": "john",
      "email": "john@test.com",
      "display_name": "John Doe",
      "given_name": "John",
      "family_name": "Doe",
      "avatar": "/img/avatars/default-avatar-03.jpg",
      "account_status": "active",
      "admin": true,
      "available": true,
      "color": "hsl(91,60%,70%)",
      "initials": "B",
      "num_assigned_received": 0,
      "num_assigned_sent": 0,
      "num_followed": 0,
      "num_drafts": 2,
      "num_unseen_notifications": 0,
      "has_unseen_assigned": false,
      "precog": null
    }
    

    This call will send you the teammates that have access to the current conversation.

    The callback's teammates parameter will contain an array of teammate.

    Fetch tags

    Front.fetchAllowedTags(function (tags) {
        if (!tags) return;
    
        console.log(tags);
    });
    

    Sample JSON for a tag

    {
      "alias": "tag_alias",
      "name": "Alias name"
    }
    

    This call will send you the tags available for the current conversation.

    The callback's tags parameter will contain an array of tag.

    Fetch notes

    Front.fetchNotes(function (notes) {
        console.log(notes);
    });
    

    Sample JSON for a note

    {
      "body": "Awesome note!",
      "text": "Awesome note!",
      "html": "<p>Awesome note!</p>\n",
      "date": 1456348516603,
      "author": "teammate"
    }
    

    This call will send you the notes written for the conversation recipient.

    The callback's notes parameter will contain an array of note.

    Fetch draft

    Front.fetchDraft(function (draft) {
        console.log(draft);
    });
    

    Sample JSON for a draft

    {
      "attachments" : [],
      "ext_id" : "43bb19b05566bc60e0094b2238b318f3@frontapp.com",
      "status" : "draft-compose",
      "id" : "msg_4zd7",
      "body" : "<div>Some HTML body</div>",
      "inbound" : false,
      "recipients" : [
        {
          "display_name" : "Awesome recipient",
          "role" : "from",
          "handle" : "awesome@recipient.com"
        }
      ],
      "from" : {
        "display_name" : "A teammate",
        "handle": "ateammate@frontapp.com"
      },
      "date" : 1493391443349,
      "blurb" : "Some HTML body",
      "type" : "email",
      "subject" : "Re: a message"
    }
    

    This call will send you the draft of the current conversation. If the conversation has no draft, the draft value in the callback will be null, else, it will look like any other message object representation.