Skip to content
IconEngage

Start a flow from your system

Let your own system start a flow for one contact through the IconEngage API, with a Started by API trigger and a key that has the automation.trigger permission.

The Started by API trigger lets your own system, such as your shop, CRM or booking tool, start a flow for one customer. For example, it can start an order-confirmation flow when an order is placed.

Set it up

  1. Open the flow and add Started by API from Start when. A flow can have only one.
  2. Click the trigger. The panel shows the endpoint for this flow, with the flow's ID, and an example request.
  3. Publish the flow. Only a published flow that isn't paused can be started.
  4. Create an API key with the automation.trigger permission. No preset includes it, so choose Custom and tick it. See Create and manage API keys.

What your system sends

Your system calls POST /api/public/v1/flows/{flow_id}/runs with the customer's phone number, and optionally the sending number and values for the flow's variables. The developer guide has the full request, the answers and the errors: Start a flow with the API.

Good to know

  • The customer is added if they're new. They're named by phone number.
  • The 24-hour window still applies. If the customer hasn't written in the last 24 hours, or has never written, the call is refused unless the flow's first message is a template.
  • One run at a time. If the customer is already in a run of this flow, the call is refused.
  • A retry doesn't start a second run. Each call carries an Idempotency-Key. A retry with the same key returns the first run.
  • Every run counts towards your plan's automation runs, like any other trigger.

Related

Still need help?

Write to us at [email protected] and tell us what you were trying to do. Already a customer? Sign in to IconEngage — the same articles are under Help in the app.