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:
| Type | Description | Source Types | Target Types |
|---|---|---|---|
| assign | When a conversation is assigned to a teammate | teammate or rule | teammate |
| unassign | When a conversation is unassigned | teammate or rule | - |
| archive | When a conversation is archived | teammate or rule | - |
| reopen | When a conversation is unarchived | teammate or rule | - |
| trash | When a conversation is deleted | teammate or rule | - |
| restore | When a conversation is removed from trash | teammate or rule | - |
| comment | When a teammate comments on a conversation | teammate | comment |
| mention | When a teammate mention another teammate | teammate | comment |
| inbound | When an incoming message is received | inboxes | message |
| outbound | When an outbound message is sent | inboxes | message |
| move | When a conversation is moved | teammate or rule | inboxes |
| forward | When a message is forwarded | teammate or rule | message |
| tag | When a conversation is tagged | teammate or rule | tag |
| untag | When a conversation is untagged | teammate or rule | tag |
| link_added | When a link is added to a conversation | teammate or rule | link |
| link_removed | When a link is removed from a conversation | teammate or rule | link |
| sending_error | When an inbox cannot send a message | recipient | message |
| message_bounce_error | When a message cannot be delivered to the recipient. | recipient | message |
| reminder | When a conversation is reopen by a reminder | - | - |
| out_reply | When a reply is sent | inboxes | message |
| conversations_merged | When two or more conversations are merged | teammate | deleted_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
| Name | Type | Description |
|---|---|---|
| types | array | List of the types of events you want to list |
| before | number (optional) | Timestamp of the max date of the events you want to list based on the event's emission time (see Sorting and filtering) |
| after | number (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
}
}
Sample code
To help you learn how to use events, the following sample code snippet demonstrates how to fetch all "message" type events from your Front account.