Skip to main content

Event Hooks

Event Hooks run an execute action after an event in Flowcall. Use them when an action should happen outside an active flow—for example, send conversation details to a CRM a few minutes after a customer returns on WhatsApp or live chat.

Event Hooks are under Broadcasts → Event Hooks. The currently available event is Conversation session started.

Choose event hook channels​

Each hook runs for the channels selected under Channels:

  • WhatsApp: conversation sessions on your WhatsApp number.
  • Live chat: conversation sessions in the live chat widget on your website.

Select more than one channel to run the same action for each of them. Hooks created before live chat support run for WhatsApp only until you add Live chat.

When a WhatsApp conversation session starts​

For WhatsApp, Flowcall starts a new conversation session when:

  • the customer sends an inbound message;
  • the customer has not sent a WhatsApp message for at least 24 hours; and
  • no workflow is active for that conversation.

A customer's first-ever inbound WhatsApp message also starts a session. Messages received while a workflow is already active continue that workflow and do not create this event.

The hook is scheduled from the time of the first message in the new session. Each hook runs once for that session after its configured delay.

When a live chat conversation session starts​

For live chat, Flowcall starts a new conversation session when the customer sends a message and has not sent a live chat message for at least 24 hours. A customer's first-ever live chat message also starts a session.

If the live chat customer details form is set to After first visitor message and the visitor still has required details to enter, the first message waits for the form. The session starts when the customer submits the form, not when the first message is sent. The delay counts from the form submission, so the name, phone, and email the customer entered are available to the action. If the customer never submits the form, no session starts and the hook does not run. If the details match an existing customer who sent a live chat message in the 24 hours before the held message, the conversation continues that customer's session and no new event is created.

Each hook runs once for a session after its configured delay.

Which ticket the hook uses​

The ticket is resolved when the delayed hook runs, not when the session first starts. Flowcall selects a ticket from the session's channel that was created after the session started. If there is none, it selects the customer's ticket whose creation time is closest to the session start time, from any channel. This lets a ticket created shortly after the first message become the action's input, even when the customer also has a recent ticket on another channel, such as email.

The same selected ticket is used for:

  • the Ticket task condition;
  • ticket-field input mappings; and
  • data points resolved from ticket shared state.

If Flowcall cannot find a ticket for the customer, the action cannot run.

Create an event hook​

  1. Open Broadcasts → Event Hooks and select Add hook.
  2. Enter a unique Name.
  3. Leave Event set to Conversation session started.
  4. Set the Delay in minutes. The allowed range is 1 minute to 30 days.
  5. Select one or more Channels. New hooks start with WhatsApp selected.
  6. Optionally choose one or more values under Ticket task condition.
  7. Choose the Execute action to run.
  8. Map every action input and API input. API inputs that the execute action requires are labelled Required.
  9. Turn on Enabled, then select Save hook.

The execute action must already exist in the Data Library. Its configured inputs determine which mapping rows appear in the hook.

Limit a hook by ticket task​

Use Ticket task condition when the action should run only for tickets created by particular tasks.

  • Select one or more tasks to allow tickets created by any of those tasks.
  • Select No task to allow a ticket that is not linked to a task.
  • Select both tasks and No task to allow either case.
  • Leave the field empty to allow every ticket, regardless of task.

Flowcall first selects the ticket closest to the event and then checks this condition. It does not search for another ticket when the closest ticket does not match. A non-matching run is skipped without calling the execute action.

Map action inputs​

Every input required by the selected execute action must have a source. The available sources are:

SourceValue used
Ticket fieldA field from the selected ticket. Use a path such as id, taskId, or payload.subject.
Event fieldA value captured when the session started.
LiteralThe same fixed text on every run.
Data pointA built-in or Data Library value inferred from the selected ticket. Available for API inputs only.

Event fields​

The Event field source can provide:

FieldWhat it contains
Account IDThe account where the session started.
Customer IDThe customer who sent the message.
Channelwhatsapp or chat-widget (live chat).
Session started atThe date and time of the first message in the new session.
First message IDThe ID of the WhatsApp or live chat message that started the session.

Data points from the selected ticket​

For an API input, choose Data point to resolve a value from the selected ticket's shared state. This includes built-in values such as customerPhone and compatible data points from your Data Library.

Library data points are available when their source is Order, Customer, Order list, or Standalone. These sources can be resolved from the conversation and ticket data already stored by Flowcall. Data points backed directly by a Custom API or Google Sheet are not available in an Event Hook because the hook does not make an additional lookup to calculate an input.

For example, an action that sends a ticket to an external help desk could map:

API inputSourceSelected value
phoneData pointcustomerPhone
ticket_idTicket fieldid
conversation_started_atEvent fieldSession started at
sourceLiteralflowcall_whatsapp

Objects and lists are passed to the action as JSON text. A value that is unavailable is passed as an empty string, unless the execute action requires that API input.

Required API inputs​

An execute action can mark some of its API inputs as required. If a required API input has no value when the hook runs, Flowcall skips the run and does not call the execute action. A value made only of spaces counts as empty.

The required setting belongs to the execute action, so it applies everywhere the action is used. Flows also wait for every required input before they call the action.

For example, to push leads to a CRM only for customers who shared a phone number, make phone a required input of the lead action and map it to the customerPhone data point. Live chat visitors who did not share a phone number are skipped. Every WhatsApp customer has a phone number, so those runs go ahead as normal.

Changes and scheduled runs​

When a session starts, Flowcall saves the hook configuration for that scheduled run. Editing, disabling, or deleting the hook does not change a run that has already been scheduled. The new configuration, including channel changes, applies to future conversation sessions. Required inputs are read from the execute action when the run starts, so a change to them also applies to runs that are already scheduled.

Execute-action calls are recorded in API Logs, where you can inspect the request and troubleshoot failures.

  • Data Points — built-in and reusable values available to flows and hooks.
  • Execute Actions — configure the side effect an Event Hook runs.
  • Custom APIs — configure the endpoint behind an execute action.
  • Broadcasts — other outbound and event-driven automation.