Application Triggers

Overview

Application triggers let your app listen for events that occur outside of Front. Those events can be used to initiate workflows in Front. The data from the triggering event can be utilized in your workflows (specifically rules at this time) to enable more powerful functionality.

📘

The triggering event only applies to conversations with a given application object

You must configure an application trigger in apps that have application objects already configured. When the triggering event is sent to Front, you specify an application object in the event payload, and rules tied to your application trigger will execute on conversations that contain the identified application object.

For example, you might want to re-open conversations in Front anytime an order changes status. When the event occurs in your order management system, you send Front an event payload identifying the trigger for the change of order status. The event payload would also identify an application object, likely through the link to the order in your management system. Once the trigger is received, any conversations that have a related application object attached for the order would reopen based on a rule. Your rule could also pull additional properties from the trigger's event payload, such as the new status, and make that available through a dynamic variable. The additional data from the property could apply a comment or tag or other action in Front based on the new status.

The example event payload might look like the following:

POST /applications/<application_uid>/events HTTP/1.1
Host: api2.frontapp.com
Content-Type: application/json
Authorization: ••••••
{
    "event_type": "order_change",
    "app_object": {
        "ext_link": "https://ordermanagement.com/f/235"
    },
    "status": "shipped",
    "paid": true
}

Read on to learn how to configure application triggers.

Setup

Application triggers are configured as features on the apps you create on the Developers page in Front. Refer to the Create, manage, and publish apps topic to learn how to create application triggers.

🚧

Publishing triggers is not supported

At this time, publishing an application with triggers is not supported. Application triggers can only be utilized on applications that are private to your company instance, and cannot be triggered by app OAuth tokens.

Sending trigger events

You send an event to Front via a trigger through the Trigger application event endpoint.

Authentication

Before you can make authenticated requests to this endpoint, ensure your API token has access to the "Application Triggers" scope. Requests made with an in inappropriate token will be rejected.

Request format

When making a request to this endpoint, you must include an event_type which matches the one configured in your application's trigger settings. This will be used to associate the event to the appropriate trigger for a given application. For example, you might have an external service that manages contacts. This service might send an event_type of contact_added when new contacts are added, or contact_deleted when contacts are removed.

You also must specify the application object associated with the trigger by sending an object named app_object that contains either an id or ext_link property. Workflows triggered by this event will be run on conversations with that object attached. The application object and application trigger must be configured in the same app.

For the ext_link, you can supply any URL that matches the application object's pattern (for example, if your application matches on URLs structured as https://example.com/<Digits>, then you can send https://example.com/1234 or https://example.com/89394 etc. as the ext_link value. On the other hand, the id can be found by looking at the links object of a conversation (note: not the _links object) that has the attached application object, identifying the link that corresponds to the application object, and then noting the link id.

To further enhance the utility of application properties, you can send additional properties within the request. These properties become accessible in your rule.

POST /applications/<application_uid>/events HTTP/1.1
Host: api2.frontapp.com
Content-Type: application/json
Authorization: ••••••
{
    "event_type": "my_event_type",
    "app_object": {
        "ext_link": "https://example.com/f/23445"
    },
    "my_first_property": "hello world",
    "my_other_property": 42
}

When developing your application, you will be prompted to send a test event. This serves as an example to streamline configuration and make property extraction easier. When sending your test event, use the dryRun query parameter set to true and input whatever ext_link or id you want for the app_object (these don't have to be real for the dry run).

POST /applications/<application_uid>/events?dryRun=true HTTP/1.1
Host: api2.frontapp.com
Content-Type: application/json
Authorization: ••••••
{
    "event_type": "my_event_type",
    "my_first_property": "hello world",
    "my_other_property": 42,
    "app_object": {
        "id": "top_1"
    }
}

Use your trigger in a workflow

After you have configured your application trigger, you can create rules with the rule trigger App event is received. This rule trigger allows you to execute rules whenever the trigger event you select is received by Front. When creating a rule, select your application trigger in the App event is received rule trigger to begin.

The rule will run on conversations that contain instances of the application object that is identified in your application trigger. Remember that the application object and the application trigger must be configured within the same app. The other limitation is that the rule cannot execute an application request from the same app in order to avoid circular logic.

Once you specify your application trigger using the App event is received rule trigger, you can set up your rule to achieve whatever workflow you desire in response to the given event. If you set up your application trigger to extract additional properties from the event payload, you can access those properties in your rule via dynamic variables.

To learn more about rules, refer to our Help Center.

Limitations

• Rate limiting—Because the endpoint to trigger events is part of the Core API, standard rate limiting applies. Additionally, there is a tier 2 limit on a combination event type and application object. In other words, your trigger server can only trigger 5 events of the same type on the same object per second.
• No identical events within 60 seconds—To avoid duplicate processing, we will discard identical events received within 60 seconds. To qualify, events must have the same data in the payload and be of the same type for the same object.
• 50 conversation limit—A single event can trigger workflows on a maximum of 50 conversations. If the application object is attached to more than 50 conversations, any workflow will only run on the most recently-updated 50 conversations.
• Triggered workflows cannot reference an application request from the same app as the trigger—If a workflow that is initiated by a trigger sends an application request in its actions and that request belongs to the same application as the trigger, the request will be skipped. This is to prevent potentially infinite circular execution of workflows, where the workflow responds to an external event, which then makes an update in the external service, which triggers a new external event which Front receives, etc.