This guide explains how to start Crisp Workflows from your website or backend, even before the user sends a message.

Programmatic triggers are useful when your product already knows what should happen next: opening a guided support flow, collecting contextual information, starting onboarding from a button, or launching a workflow after a product event. Crisp supports both Web Chat SDK triggers for frontend use cases and the Workflow API for backend use cases.

Before you start

Open Crisp, then go to AI Agent → Automate → Workflow Builder and open the workflow you want to trigger.

Before triggering it from code, make sure that:

• The workflow is saved and deployed → draft changes will not run in production
• The workflow can start from an action block → programmatic starts should not wait for a user-message event as their first step
• You have copied the right workflow ID → workflow IDs still use the internal scenario_... format
• You know where the trigger will run → use the Web Chat SDK in browser code and the REST API from your backend

Get the workflow ID and code snippets

The easiest way to avoid mistakes is to copy a generated snippet directly from the Workflow Builder.

To get a ready-to-use snippet:

1. Open your workflow from AI Agent → Automate → Workflow Builder
2. Hover the workflow in the builder interface
3. Click the three dots menu in the bottom-right corner
4. Select Workflow API
5. Copy the generated snippet for the method or language you want to use

The snippet generator displays the workflow ID and includes ready-to-use examples for common approaches, including the Web Chat SDK, REST API, and backend languages such as Node, Python, cURL, PHP, and Ruby.

Start a workflow with the Web Chat SDK

Use the Web Chat SDK when the trigger happens in the browser, for example when a visitor opens the chatbox, clicks a button, lands on a specific page, or completes a frontend action.

Here is an example that starts a workflow when the visitor opens the chatbox:

$crisp.push(["on", "chat:opened", function() {
 $crisp.push(["do", "bot:scenario:run", [
  "scenario_85c6438c-2310-4d2c-b4dc-c8f8a76d2d19"
 ]]);
}]);

The bot:scenario:run command expects the workflow ID as its first argument. Even though Crisp now uses the term Workflows in the interface, the SDK method and internal IDs still use the historical scenario wording.

Pass memorized values from the SDK

You can also pass variables when starting the workflow. These values are stored for the current workflow run and can be reused as replacement tags inside workflow blocks.

$crisp.push(["do", "bot:scenario:run", [
 "scenario_85c6438c-2310-4d2c-b4dc-c8f8a76d2d19",
 {
  order_id: "12345",
  plan: "pro",
  priority_customer: true
 }
]]);

Inside the workflow, you can reference these values with tags such as {{ order_id }}, {{ plan }}, or {{ priority_customer }}.

Start a workflow with the REST API

Use the REST API when the trigger comes from your backend, product, CRM, billing system, ecommerce stack, or another internal service. This is the right approach when you need to keep the API token secret or trigger workflows from server-side events.

The endpoint format is:

POST https://app.hugo.ai/api/scenario/{workflow_id}/trigger/

Here is a Node.js example:

const url = "https://app.hugo.ai/api/scenario/~c2NlbmFyaW9fYzNkYzc0ZjEtYTE4MS00OWFmLTg1ODktMTc0ODhiMjM4Y2Rj/trigger/";

const options = {
 method: "POST",
 headers: {
  "Content-Type": "application/json",
  Authorization: "Bearer YOUR_WORKFLOW_API_TOKEN"
 },
 body: JSON.stringify({
  session_id: "SESSION_ID"
 })
};

try {
 const response = await fetch(url, options);
 const data = await response.json();
 console.log(data);
} catch (error) {
 console.error(error);
}

The session_id is required because Crisp needs to know which conversation/session should receive the workflow. You can get it from the Web Chat SDK with the session:loaded callback, from Crisp conversation metadata, or from your own backend if you already store Crisp session IDs.

Pass variables with the REST API

The REST API also supports variables. They work like memorized values and can be reused inside the workflow with {{ key }} replacement tags.

const options = {
 method: "POST",
 headers: {
  "Content-Type": "application/json",
  Authorization: "Bearer YOUR_WORKFLOW_API_TOKEN"
 },
 body: JSON.stringify({
  session_id: "SESSION_ID",
  variables: {
   order_id: "12345",
   plan: "pro",
   renewal_date: "2026-06-01"
  }
 })
};

For example, a workflow message could say:

Your {{ plan }} plan linked to order {{ order_id }} renews on {{ renewal_date }}.

Variables should be simple values: strings, numbers, or booleans. They persist during the workflow run and can be overwritten later if the workflow memorizes a new value with the same key.

Common use cases

Programmatic workflow starts are especially useful for:

• Opening a guided support flow → start a workflow when a visitor opens the chatbox from a specific page
• Collecting context early → pass product, account, plan, or order information before the user asks a question
• Starting onboarding → launch a workflow after a user completes signup or clicks an onboarding CTA
• Routing by product event → trigger a specific workflow after an action in your app, such as a failed payment or a trial ending soon
• Connecting backend systems → start a workflow from your CRM, ecommerce backend, billing system, or internal automation tool

Programmatic starts are best used when the trigger is explicit and useful to the user. Avoid launching workflows too aggressively, especially on every page load, as this can feel intrusive and make conversations harder to follow.

Frequently Asked Questions

Still have questions which were not covered in this article? Here is a collection of the most frequently asked questions on this topic.

I am using the SDK correctly but my workflow is not starting, why is that?

Start with the basics: verify that the workflow is saved, deployed, and enabled. Then confirm that you are using the correct workflow ID. This is a common mistake, especially when several workflows have similar names or when a test workflow was duplicated.

Also check the first block of the workflow. If the workflow starts with an event block that waits for a user message, the programmatic trigger may start the workflow but the flow will immediately wait for that event. For most programmatic starts, begin with an Action block such as a message, button picker, field input, or internal action.

Finally, review whether another workflow, operator message, or stop condition is preventing the workflow from running again. If a Stop Workflow block was used earlier, it can prevent workflows from restarting in the same conversation for a while.

Should I use the SDK or the REST API?

Use the Web Chat SDK when the trigger happens in the browser and does not require a secret token. This is ideal for page-level or visitor-level interactions such as opening the chatbox, clicking a button, or navigating to a specific page.

Use the REST API when the trigger comes from your backend or from a system that must authenticate securely. This is the right choice for product events, billing events, CRM events, server-side automations, or anything involving private data.

Can I trigger a workflow with Google Tag Manager?

Yes, as long as Crisp is loaded on the page where Google Tag Manager executes the tag. Create a Custom HTML tag and run the Web Chat SDK command from there.

<script>
 $crisp.push(["do", "bot:scenario:run", [
  "scenario_85c6438c-2310-4d2c-b4dc-c8f8a76d2d19"
 ]]);
</script>

Use GTM triggers carefully. A broad trigger such as all pages can start the workflow too often. Prefer specific pages, button clicks, or custom events.

What else can I do with the Web Chat SDK?

The Web Chat SDK can open or close the chatbox, listen to chatbox events, push session data, update user details, mute sounds, change runtime configuration, and more. It is useful when you want Crisp to react to what happens in your website or application without asking the user to type first.

Updated on: 04/05/2026