Events

An event is created everytime something interesting is happening in Front. You'll find in the table bellow the description of all the types of event that exist:

TypeDescriptionSource TypesTarget Types
assignWhen a conversation is assigned to a teammateteammate or ruleteammate
unassignWhen a conversation is unassignedteammate or rule-
archiveWhen a conversation is archivedteammate or rule-
reopenWhen a conversation is unarchivedteammate or rule-
trashWhen a conversation is deletedteammate or rule-
restoreWhen a conversation is removed from trashteammate or rule-
commentWhen a teammate comments on a conversationteammatecomment
mentionWhen a teammate mention another teammateteammatecomment
inboundWhen an incoming message is receivedinboxesmessage
outboundWhen an outbound message is sentinboxesmessage
moveWhen a conversation is movedteammate or ruleinboxes
forwardWhen a message is forwardedteammate or rulemessage
tagWhen a conversation is taggedteammate or ruletag
untagWhen a conversation is untaggedteammate or ruletag
link_addedWhen a link is added to a conversationteammate or rulelink
link_removedWhen a link is removed from a conversationteammate or rulelink
sending_errorWhen an inbox cannot send a messagerecipientmessage
message_bounce_errorWhen a message cannot be delivered to the recipient.recipientmessage
reminderWhen a conversation is reopen by a reminder--
out_replyWhen a reply is sentinboxesmessage
conversations_mergedWhen two or more conversations are mergedteammatedeleted_conversation_ids

Event Preview

When receiving an event from Front (either via a webhook or via a custom channel callback), you will receive the preview of the event. As the callback URL you provided is public, you should not blindly trust any incoming requests. This is why we're sending only a preview of the event.

An event preview has the exact same structure as the full event except that its source, target and conversation only contain an ID, a link to the resource itself and a type. You can then either request the detailed event or each resources separately by following their respective _links.

Search Parameters

Events support search queries via parameter named q

NameTypeDescription
typesarrayList of the types of events you want to list
beforenumber (optional)Timestamp of the max date of the events you want to list based on the event's emission time (see Sorting and filtering)
afternumber (optional)Timestamp of the min date of the events you want to list based on the event's emission time (see Sorting and filtering)

Sorting and filtering

Events are sorted according to the time the event is created on (in reverse chronological order), but filtered (through the q query parameter) based on the emission time. That is, the creation date determines how event information is initially returned to you via the API, but if you use the q query string to filter on before and after timeframes, then the filter applies to the emission date instead of the creation date. In most cases these dates are the same, but they can differ in some situations.

The creation date, target.data.created_at, indicates the timestamp of when the event's target was created. For example, if an event relates to a message, this would be the time the message was sent.

The emission date, emitted_at, indicates the time the event was emitted in Front. In most cases, the emitted_at timestamp matches the created_at timestamp. However, this is not always true, most notably for Messages. The reason is that messages can be imported into Front via the API or by connecting a new channel to Front with prior message history. In this case, a message might have been created a year ago, but imported into Front on the current day. The created_at date will reflect that the message was created a year ago, but the event will be emitted with today's date. You would have to take this difference into account when deciding how to filter results returned by the API. This particular event would return via the API's initial sorting alongside events that had occurred a year ago, but if you applied a filter that selected events that had occurred within the last week, it would show up in those results despite the year old creation timestamp.

You can find more information about Events in community topics such as this one, or post a new question in the Developer Q&A.

👍

Event IDs are sequential and never reused

After dropping the evt_ prefix, the remaining string is a base 36 conversion of the decimal ID. You can always trust that a larger ID is more recent.

Example Event Object

{
  "_links": {
    "self": "https://api2.frontapp.com/events/evt_55c8c149"
  },
  "id": "evt_55c8c149",
  "type": "assign",
  "emitted_at": 1453770984.123,
  "source": {
    "_meta": {
      "type": "rule"
    },
    "data": {
      "_links": {
        "self": "https://api2.frontapp.com/rules/rul_55c8c149",
        "related": {
          "owner": "https://api2.frontapp.com/teams/tim_55c8c149"
        }
      },
      "id": "rul_55c8c149",
      "name": "Important deliveries",
      "actions": [
        "Assign to Leela Turanga"
      ],
      "is_private": false
    }
  },
  "target": {
    "_meta": {
      "type": "teammate"
    },
    "data": {
      "_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
    }
  },
  "conversation": {
    "_links": {
      "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
      "related": {
        "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
        "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
        "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
        "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
        "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
      }
    },
    "id": "cnv_55c8c149",
    "subject": "You broke my heart, Hubert.",
    "status": "archived",
    "assignee": {
      "_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
    },
    "recipient": {
      "_links": {
        "related": {
          "contact": "https://api2.frontapp.com/contacts/crd_55c8c149"
        }
      },
      "handle": "[email protected]",
      "role": "to"
    },
    "tags": [
      {
        "_links": {
          "self": "https://api2.frontapp.com/tags/tag_55c8c149",
          "related": {
            "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations",
            "owner": "https://api2.frontapp.com/teams/tim_55c8c149",
            "children": "https://api2.frontapp.com/tags/tag_55c8c149/children"
          }
        },
        "id": "tag_55c8c149",
        "name": "Robots",
        "highlight": "blue",
        "is_private": false,
        "created_at": 0,
        "updated_at": 0
      }
    ],
    "created_at": 1453770984.123,
    "is_private": false
  }
}