This guide will teach you how to start a chatbot scenario automatically, without users sending a message themselves.

There are three main ways to start a scenario with the chatbot plugin, we have created guides to cover these different methods and allow you to efficiently understand how a scenario can be started, as well as some good practice advice to help you along the way.

Looking for a different way to start your scenario? Check out these guides as well:
How to start a Bot Scenario when a user sends a message
How to start a Bot Scenario manually

🤖 If you're just getting started with our chatbot software, feel free to check out this guide to take you through your first steps.

There are two main ways to programmatically start a scenario, without waiting for users to contact you:
The first way would be to use the SDK to push an Event,which can be detected by the Bot
The second one is to use the SDK to push a message on behalf of the user,as if they had sent it themselves

Let's explore how to set this up and understand the differences between these two methods.

Starting a Bot scenario automatically, without a user sending a message requires using the Crisp SDK (available with Javascript and iOS/Android SDKs). You can visit our Developer Hub to learn more about the SDK

Table of Content

Starting a Scenario by pushing a new Crisp Event
Starting a Scenario by pushing a Message on behalf of the user
Frequently Asked Questions

Starting a Scenario by pushing a new Crisp Event

This method requires that the user has an email address set in the conversation. Crisp Events are attached to the user's profile, so this condition is necessary in order to start your Bot Scenario this way.

When creating a Scenario, you have the option to begin with an Event block "New Crisp Event" which is able to detect when a Crisp Event has been pushed with the SDK.
When a Crisp Event whose name matches the one you specified in your scenario is pushed, the Bot will be triggered.

For instance, if we want our scenario to be triggered when users subscribe to our Premium plan, we can start our scenario with a "New Crisp Event" block with value premium-subscription
Then, we can simply implement the SDK method in our platform's code to programmatically push that event when we want to by using:
$crisp.push(["set", "session:event", ["premium-subscription"]]);

We've made a quick example to show how to configure such a scenario with the Bot plugin:



Only Crisp Events pushed with the SDK can be detected by the Bot. This method does not apply to Events pushed with the REST API

As we mentioned, starting a scenario automatically by pushing a Crisp event with the SDK requires an email address to be set in the user's session. If you would like to start a scenario automatically for a visitor (a user without email address available), check the second method below

Starting a Scenario by pushing a Message on behalf of the user

In cases where the user does not yet have an email address set in their session, and you would still be able to trigger a Bot Scenario without them proactively sending a message, you can use the SDK to send a message on their behalf!

Indeed, as you may have learned in this article, the Bot is able to detect when messages containing specific patterns are sent. And it happens that the SDK also allows you to push a message, just like if the user had sent that message themselves.
For instance, in order to propose options (such as a scenario containing button pickers) when the user opens the chatbox, we could very well create a scenario that detects a message pattern such as Hello, I have a question" and use the SDK to automatically push that very message, with:
$crisp.push(["do", "message:send", ["text", "Hello, I have a question"]]);

There are numerous use-cases where this could be leveraged to start a scenario at key moments. Let's see another example in a short video, to show you how to configure the scenario and use the SDK!



A common way of implementing this is by using the available callback methods available with our SDK.
For instance, ce following snippet allows you to push this message when the chatbox is opened for the very first time by your users, in order to avoid unnecessary messages and only trigger your Bot scenario when there is a certain degree of intent from the user to contact you:

<script>
$crisp.push(["on", "chat:initiated", function() {
    $crisp.push(["do", "message:send", ["text", "I have a question"]])
}])
</script>

Frequently Asked Questions

Still have some questions about the Bot that were not covered in this article or related guides? Perhaps you'll find the answer here!
Here are some of the most frequently asked questions about programmatically starting a Bot Scenario with the SDK.

Don't hesitate visiting this in-depth article to learn more about the Bot and master your craftsmanship of scenarios

If your question does not figure here, share it with us directly by chat, we'll be available!

I am pushing a Crisp Event, but my Bot is not starting, why is that?

This can be troubleshooted by following a few steps.
Ensure that your scenario was properly saved and deployed. You can also verify that it is enabled from the Scenario Manager view.
Make sure your scenario is properly configured and that the name of the Event in your "New Crisp Event" block matches the one you are pushing with the SDK. Also ensure that your users have an email address set in the conversation prior to the Crisp Event being pushed. You can also inspect the conversation itself in your Crisp inbox and check the "last profile events" widget to verify that your event was properly pushed.
A scenario will not start if an operator has sent a message during the past 20 minutes, you can hover messages in that conversation to view the timestamps if you have any doubt. Also note that if you use a "Exit Block - Stop Scenario" at the end of your flow, it will prevent your scenario from triggering again during the next 24 hours, if it already ran once during this conversation.
Finally, there could be an issue in your script where you are using the SDK to push the Crisp Event, make sure to follow good practices to easily debug your code.

I don't have access to the code of my website, is there any other way to push Crisp Events?

While pushing Crisp Events requires using the SDK in the code of your website or application, you can also do with Google Tag Manager and similar tools if these are used on your website.
In GTM, you can create a "Custom HTML" tag to execute any SDK command, provided that Crisp is loaded on the page where you are injecting GTM. The Tags you create can be associated with a "Trigger" in order to determine how and when it should be executed.

For instance, to push a Crisp Event named "my-event" with GTM, you can create a "Custom HTML" Tag containing:

<script>
    $crisp.push(["set", "session:event", ["my-event"]]);
</script>

If I choose to push a message with the SDK to start my Bot Scenario, will this create a conversation?

Yes, pushing a message on behalf of the user will indeed create a conversation in your Crisp inbox. Messages pushed on behalf of the user will appear exactly as if users had sent it themselves, and it will be visible in conversations.

What else can I do with the SDK?

There are loads of possibilities with the SDK! You can programatically open and close the chatbox, hide it, push custom data and segments, and much more. The SDK also allows you to listen to some events, in order to execute code when a user opens the chatbox, or when Crisp has loaded on your page.

You can read more about the SDK in our Developer's Hub, it provides a very useful set of tools!

Updated on: 11/03/2024