Triggers and events

In short: every workflow starts on exactly one kind of event (the trigger), optionally narrowed down with conditions. This article is the reference: per event the technical name, the label in the editor, when it fires, all fields it passes along (with type and choice values) and the content fields a step can read. After that comes exactly how trigger conditions compare.

Where to find this

Account > Workflows, open a workflow. At the top is the When block with the This happens dropdown (the event), Only if (the conditions) and Never twice at once for (the concurrency key).

Who: from the role Organisation admin, for the workflows of an organisation whose AI settings you manage. Only an Account admin can create or change a workflow for the whole account.

The When block of an opened workflow under Account > Workflows, with the This happens dropdown, the Only if block with a condition (Field, operator, Compare with) and the Never twice at once for field.

How a trigger works

• A workflow has one trigger: {"event": "<event>", "conditions": [...]}. In the editor you choose the event under This happens.
• For every event of that kind, aishaa checks the conditions. If they are all met (or there are none), a run starts on the live version of the workflow.
• Every workflow whose trigger matches starts. There is no order or priority between workflows and no workflow passes the work on to another.
• At most one run starts per workflow and event.
• A workflow never reacts to an event it caused itself.
• An event that is 5 or more links deep in a chain of automations no longer starts any work. The run is then recorded as stopped, to prevent a loop.
• A workflow of one organisation only reacts to events of that organisation. A workflow of the whole account reacts to events of all organisations of the account.
• An event only contains references (ids) to tickets, messages, customers and records, never their content. You read the content in a step through the content fields (see below).

Overview of all events

Events a customer is waiting for (message.received and message.understood) run with priority. All others run in the background.

Field types

Every field has a type. It determines how a condition compares it and how you use it.

Fields marked content are not part of the event itself. aishaa reads them at the moment a step uses them (see “Content fields”).

message.received: A message comes in

Fires when a message from outside the organisation comes in live in a conversation: from the customer or from an external participant. Not for imported history and not for messages the organisation sends itself. At this moment aishaa has not read the message yet. If you want to steer on the meaning of the message (topic, urgency, whether a reply is needed), choose message.understood.

Content fields: trigger.ticket.* and trigger.message.* (see “Content fields”).

message.understood: Message read

Fires after aishaa has read and understood an incoming customer message: the question, the topic, the urgency and whether a reply is needed. This is the event on which you sort and answer customer messages. The blocks agent.reply (Write the reply) and case.process (Update cases) only work in a workflow with this trigger.

Content fields: trigger.ticket.* and trigger.message.*. The text of the message is trigger.message.text.

Good to know about message.understood:

• The event fires for a message that came in by itself. If a colleague asks for a proposal themselves, no new workflow run starts.
• If the customer writes again before the previous message has been answered, the open answering runs of the older message stop and the new message takes over.
• If reading the message fails, the event does not fire.

action.resolved: An action is handled

Fires when an action is no longer waiting: a proposal has been carried out, has failed or has been rejected, a request to a person has been answered, a task has been done, or something has expired.

Content fields: trigger.ticket.*.

A workflow that is itself waiting for a request, proposal or message does not need this event: the waiting step continues by itself as soon as the action has been handled.

object.linked: Something is linked to a customer

Fires once per new link: a lookup in a connected system found a record for the customer, or a person, aishaa or a workflow linked something. Not when a source confirms an existing link again.

Content fields: trigger.record.* (only filled if the object is a record), trigger.customer.* and trigger.ticket.*.

object.unlinked: A link to a customer is removed

Fires when the link of an object with a customer ends: a person undid it, or whatever made it has been withdrawn.

Content fields: trigger.record.*, trigger.customer.* and trigger.ticket.*.

recording.transcribed: A conversation is transcribed

Fires when a recorded conversation with a customer has been transcribed, with the speakers told apart. What happens next (a report, a task, the dossier) you build in the workflow. You read the text directly as trigger.recording.transcript.

Content fields: trigger.recording.* and trigger.customer.*.

ticket.created: A conversation starts

Fires when a conversation starts: a customer’s first live message opened it, or a colleague started it. Not for imported history or restored conversations.

Content fields: trigger.ticket.* and trigger.customer.*.

ticket.status_changed: A conversation’s status changes

Fires when the status of a conversation changes (closed, reopened, answered, set aside), by a colleague, a rule or an aishaa task. Not for imported history.

Content fields: trigger.ticket.* and trigger.customer.*.

ticket.assigned: A conversation is assigned

Fires when a conversation is assigned to a colleague, to a different colleague, or to nobody.

Content fields: trigger.ticket.* and trigger.customer.*.

schedule.due: On a schedule

Fires when the workflow’s own schedule comes round. This event only starts the workflow the schedule belongs to, never another one. It mentions nothing else: a scheduled workflow looks up what it works with in its own steps.

Content fields: none.

The schedule is in the trigger itself, as trigger.schedule:

A trigger other than schedule.due may not have a schedule. More about setting it up in the editor is in Scheduled workflows.

Content fields

An event only refers to tickets, messages, customers, recordings and records by their id. aishaa offers the content as extra fields under trigger, grouped per object. You refer to them directly in a step, for example {{trigger.message.text}}; no separate step is needed to fetch them.

This is how content fields work:

• aishaa only reads the content when a step uses the field, and only for that step. A step after a wait step sees the content as it is at that moment.
• aishaa only reads within the account and the organisation of the run.
• If the object has disappeared, the fields are empty. You can test that with missing in a step.
• A customer’s e-mail address and phone number are the primary address and number, otherwise the oldest.
• trigger.ticket.channel is the channel of the last incoming message, otherwise the channel the conversation started on.
• A trigger condition cannot read a content field. Test content in a flow.condition (Condition) or flow.switch (Choose a route) step.

Trigger conditions

A condition is {"path": "trigger.<field>", "op": "<operator>", "value": <value>}. In the editor the block is called Only if, with Field, the operator and Compare with.

• All conditions must be met (and). There is no “or”. If you want to react to one thing or another, use a flow.switch or flow.condition step in the workflow, or create two workflows.
• Without conditions the workflow reacts to every event of the kind.
• A trigger condition only reads the event’s own fields (the tables per event above). The path must start with trigger.. A content field such as trigger.message.text or trigger.ticket.customerEmail gives an error: deciding whether a workflow starts must cost nothing. Test content in a step.
• Conditions cost nothing (no AI is involved). That is why the editor can show, for the latest events, which condition stopped a start.

Operators

Write the operator in lower case, exactly as in the table.

How it compares

• Numbers as numbers. If the field and the value are both a JSON number, aishaa compares them as numbers. So write a number without quotation marks: "value": 80, not "value": "80". With quotation marks it is compared as text, and then "9" is greater than "10".
• Moments as moments. If both values can be read as a date and time, aishaa compares them as moments.
• The rest as text, case-insensitive. "whatsapp" is equal to WhatsApp. Yes/no fields compare as the text true or false; "value": true works.
• A missing field is equal to nothing. eq, gt, gte, lt, lte and contains are then not met; neq is met; missing is met.
• An empty text ("") counts as filled for exists.
• contains on text looks for a piece of text, case-insensitive: contains "retour" is also met for "Retourzending".

Examples

Only new WhatsApp conversations outside opening hours:

{
  "event": "message.understood",
  "conditions": [
    { "path": "trigger.channel", "op": "eq", "value": "WhatsApp" },
    { "path": "trigger.isNewConversation", "op": "eq", "value": true },
    { "path": "trigger.withinOpeningHours", "op": "eq", "value": false }
  ]
}

Only conversations that are being closed:

{
  "event": "ticket.status_changed",
  "conditions": [ { "path": "trigger.status", "op": "eq", "value": "Closed" } ]
}

Only recordings that are already linked to a customer:

{
  "event": "recording.transcribed",
  "conditions": [ { "path": "trigger.partyId", "op": "exists" } ]
}

Never twice at once (concurrencyKey)

With concurrencyKey (in the editor Never twice at once for) you give a path in the trigger, usually trigger.ticketId. If a new event comes in with the same value while a run of this workflow is still open (running, waiting or paused), that event starts nothing. If the value is empty, there is no limit. The key too must be one of the event’s own fields, not a content field. More in References, routing, repeating and choosing.

Good to know

• Every event has one fixed shape. Build conditions on the technical names and values from this article; the labels are what people read in the editor.
• You can use an id field of a colleague (such as trigger.recordedByUserId or trigger.assigneeUserId) as the assignee of a request or task.
• For customer messages, almost always choose message.understood: then the workflow already knows what is being asked and an agent.reply step can answer.
• Under Field, the editor also has the choice Other field… for a path that is not in the list.

Related

• What are workflows
• Create, test and publish a workflow
• Building blocks of a workflow
• References, routing, repeating and choosing
• Scheduled workflows
• Answering customer messages with workflows
• The workflow definition (for AI assistants)