Articles on: Crisp Chatbot

Understanding and Mastering the Crisp Chatbot

In this article, we will dive deeper into how the Bot plugin works, and offer information on various concepts helpful to follow good practices and quickly build efficient scenarios.

The Bot plugin allows you to create scenarios which you can adapt to a wide range of usages.
For instance, you can have a scenario dedicated to handling requests while you are away, another scenario to automatically add a segment to email conversations, or asking a user for information, among many other things.

You essentially configure these scenarios by adding and customizing various "blocks". By connecting these blocks, you can create a flow of actions, conditions, and events which reflect the journey you have prepared for your users.

Just discovering the Bot plugin? Check out our Getting Started with the Bot plugin article first!


Table of Content

Crafting Guides
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Building a list of buttons and offer choices to users
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Adding External and Embedded links in a button
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Using Field Inputs in a scenario
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Updating User information in the conversation
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Creating a Products Carousel
Blocks available with the Bot plugin
‎ ‎ ‎ ‎ ‎ ‎ ‎ Event Blocks
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → User Message Matches‎ • Button/Input Action
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Conversation State ChangedURL Change Detected
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Awaiting OperatorUser Email Updated
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → User Name UpdatedUser Phone Updated
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Custom Data Updated‎ • Segments Updated
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → New Crisp EventNew User Message
‎ ‎ ‎ ‎ ‎ ‎ Action Blocks
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Send Message: CompositionSend Message: Text
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Send Message: Button PickerSend Message: Field Input
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Send Message: File AttachmentSend Message: Animation (GIF)
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Send Message: CarouselSend Message: Private Note
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Update User: Update User NameUpdate User: Update User Email
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Update User: Update User PhoneUpdate User: Update Custom Data
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Update User: Set with Bot MemoryUpdate User: Add Session Segment
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Update User: Submit EventUpdate User: Ask User Feedback
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Internal Actions: Update Chat StateInternal Actions: Wait
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Internal Actions: Block UserInternal Actions: Mention Operator
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Internal Actions: Assign OperatorInternal Actions: Submit Web Hooks
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → AI Actions: Helpdesk AI
‎ ‎ ‎ ‎ ‎ ‎ Condition Blocks
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Conversation is NewSession Segment
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Check Custom DataCurrent Page URL
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → User LocationUser Language
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Current HourCurrent Day
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Bot Memory has DataUser Email is Matching
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → User Email is SetUser Phone is Set
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → User Name is SetConversation State
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Conversation StateSupport is Available
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → HTTP Response Match
‎ ‎ ‎ ‎ ‎ ‎ Exit Blocks
‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ → Stop ScenarioRun Scenario
Block Options


Blocks available with the Bot plugin



When creating Bot scenarios, you will encounter the following types of blocks:
Event block: an event that triggers progress in the scenario map, eg. message received
Action block: Performs an action, eg. send a message
Condition block: checks for a condition, eg. if user has an email set
Exit scenario: used to end the scenario; this block is not always required but is also useful for connecting to another scenario or stopping the current one.

The "Entry Gate" is simply your starting point. This is where your scenario starts, from which you should connect your very first block



Event Blocks



The Event Blocks are "listeners". They are used to detect when something has happened, such as when the user has sent a message, when the state of a conversation changed, or if a button was clicked for instance.

When an Event block is reached, the scenario will pause itself until the event it is monitoring occurs.

Event blocks are also the main way to start your initial Bot scenario. When starting a scenario, the first Event block you should use right after your Entry Gate should be either a "User Message Matches" or "New Crisp Event". During the execution of the scenario however, you can use any of the listed Event block to pause the scenario until the event you are monitoring occurs.

Let's have a look at the available Event blocks!

✹ User Message Matches


This Event block detects when a message was sent by a user. It accepts 3 different parameters, which can also be combined:

Message Patterns => Used to detect any message sent by a user, or only specific terms
Message Origins => Detect messages sent from a specific channel (such as Whatsapp, Instagram, Chatbox... Or all of them)
Negate Match => If enabled, will instead catch message which do not contain the terms specified in the "Message Patterns"

Detecting any message sent by a user is done by simply using the wildcard * as the Match value. This will indicate your Bot to catch any message sent by the user. To detect specific terms, you have the option to wrap them inside * and ** wildcards, let's review the difference between both, and share a few use-cases.

Single wildcards * around a term will help you detect these terms inside of a sentence, surrounded by other words. For instance, in order to capture the word "help" inside of the message "Hello, I need help from your support team" you will need use a Match value of *help*. Single wildcards will also be able to detect punctuation next to the term you're detecting, no worries! *hello* will be just able to detect "hello there", "hello!" or "hello, i need help"

Double Wildcards ** are used exclusively to detect a term directly wrapped around different characters. This is especially for Asian languages such as Simplified Chinese or Japanese for instance, but also to detect broader terms and potential variations. As an example, using a Match value of **count** will detect "count" but also "account", "counting", "accounting", etc.

Example of configuration of a "User Message Match" to detect any message on all channels

Don't hesitate visiting this guides to learn more about how a Bot Scenario can be started when a message is received:
Starting Bot Scenario when a user sends a message
Starting Bot Scenario programmatically by pushing a message with the SDK

✹ Button/Input Action


This Event block is used to detect when a button was clicked by the user, or when a field input was filled.

For a button, the Match value should simply be the name of the button you'd like to monitor.

Example of configuration of "Button" events, to detect which one the user clicked and continue with that branch

For a field input, the value should be what you would like the user to set. If you want to accept any entry to continue, you can use * as a value

Example of configuration of an Event "Field" block to validate and memorize the value provided by the user

"Memorize" Allows you to memorize the value of a button/field after it is completed. Especially useful to register information if the field was used to collect an email address, name, or any other textual data you'd like to keep in memory

✹ Conversation State Changed


This Event block is used to detect when the state of a conversation has changed, among one of the three states:
Pending — a conversation which contains unread messages
Unresolved — when a conversation is still on-going, but messages have been read
Resolved — the conversation has been marked as resolved (closed)

✹ Awaiting Operator


This Event block is used to pause the scenario, and resume it if the last message sent by the user is still unread after 3 minutes.

Note it is not possible to stack these blocks to multiply the duration time, it will always look for the last message sent by your user.

✹ User Email Updated


This Event block is used to detect the moment the user's email address is either set or changed.

✹ User Phone Updated


This Event block is used to detect the moment the user's phone number is either set or changed.

✹ User Name Updated


This Event block is used to detect the moment the user's nickname is either set or changed.

✹ Custom Data Updated


This Event block is used to detect the moment a specific custom data is set in the conversation.

If you choose to specify several, the Bot will validate this step once any of the specified custom data is set in the conversation

✹ Segments Updated


This Event block is used to detect the moment specific segments are set in the conversation.

If you choose to specify several, the Bot will validate this step once any of the specified segments is set in the conversation

✹ URL Change Detected


This Event block is used to detect the moment a user changes page on your website, during the execution of the scenario.

If you specify several urls, this block will trigger once the user navigates to any of the specified URLs

When specifying a URL to check, you can use wildcards in order order to check for any path or sub-path.

Single wildcards * inside of a URL are used to detect any specific sub-folder. For instance, to detect both https://acme.com/fr/account and https://acme.com/en/account
You can use a Match value of https://acme.com/*/account

Double wildcards ** inside of a URL are used if you would like to match not only a specific sub-folder, by and of the path contained in these ones as well.
For instance, to match both https://acme.com/fr/dashboard/index.html or https://acme.com/fr/helpdesk/getting-started/how-to-install
You can use a Match value of https://acme.com/fr/**

In order to detect a whole domain, such as acme.com you would therefore need to check for 2 urls: https://acme.com and https://acme.com/** in order to cover both the home page, and any of its sub-paths.

✹ New Crisp Event


This Event block is used to detect when a specific Crisp event has been pushed with the SDK (Javascript, iOS, Android, React Native)

This particular Event block is mainly used to start a Bot scenario automatically, before the user has sent a message for instance. Because Crisp events are then attached to the user's profile, it requires the user to have an email address set in his session (for the event to be attached to that profile)

Don't hesitate visiting this dedicated guide to learn more about it.

✹ New User Message


This Event block is used to detect when new message of any type has been a user

This block behaves in a similar way to the "User Message Matches" with a value *, meaning that it will detect any new message sent by the user.
Unlike the former, this Event block is also able to detect files uploaded by the user, pictures, or audio message for instance.

This block does not allow you to detect specific message patterns however, it will trigger when users submit any message of any type.

Action Blocks



The Action Blocks, as their name suggest, allow you to perform an action during the execution of the scenario. They can be used to send messages to a user, resolve a conversation, memorize information, and much more.
They are separated into 3 categories, the "Send Message" one which allows you interact with your users and configure a unique message for each language you wish to support, the "Update User" which lets you memorize data

"Send Message" allow you to specify the locale for which the message is addressed. The "default locale" represents the message that will be displayed if the language of the user doesn't match any of the localed you have configured on your Message blocks. You can also use it if you would like to have a universal message, displayed for all users across any language
"Update User" are aimed at adding/updating information about the user in the current conversation.
"Internal Actions" are used when you would like to affect a conversation's state and perform actions that are not directly visible to your users in the conversation.
"AI Actions" is the latest addition to the Bot features, allowing you to leverage AI within your scenarios.

✹ [Send Message] Text


This Action block is used to send a regular message.

Just like any message sent in the chatbox, you can format it with markdown in order to customize it further.

When sending a message, you can use regular markdown in order to format it, but it is also possible to input variables that have been memorized during the scenarios (for instance, with the Button/Input Action" Event block.
You also have access to several global variables, as long as these information are present in the conversation:
{{ name.full }}, {{ name.last }}, {{ name.first }}, {{ email }}, {{ phone }}, {{ city }} and {{ country }}

You can also customize your messages with even more variables, the Bot also lets you access the custom data set in conversations and contact profiles with {{ data.key_name }}
If a conversation or contact has a Custom data such as "subscription: premium", you can output with {{ data.subscription }}

✹ [Send Message] Composition


This Action block will display a "composition animation" for the duration you specify

✹ [Send Message] Button Picker


This Action block will send button pickers to your users.

It will let you display a serie of button (choices) that your users can click. Button pickers can lead them to a different "branch of your scenario" when combined with Event blocks "Button/Input Action" below them.
Button pickers can also be used to open a link, by clicking the "gear" icon in each button's configuration. You can select among 2 options:
External link to open the url in a new tab of the browser
Embedded link in order to open the url directly in the chatbox (especially useful to easily share a calendar, form or article for instance

You can toggle the "Required" option in order to prevent the user from being able to send messages until the previous button/field form has been completed

Configuration of a Button "action" to offer users 3 different options to select from

Configuration of a Button "action" to share an embedded link in the chatbox

✹ [Send Message] Field Input


This Action block will send a field input to your users.

It will let you display a text area where your users can input information. Field inputs submission is then verified by the Event block "Button/Input Action" below them, which allow the user to continue the scenario once they have completed this step.

You can also memorize the value given by the user, to re-use it later update the user's profile, or set a custom data for instance.
Once a value has been "memorized" in a key, you can reuse that key in the "Update User" action blocks to automatically set the user's email, phone, nickname, custom data, etc.

You can toggle the "Required" option in order to prevent the user from being able to send messages until the previous button/field form has been completed

Example of a required field "action" to ask users for their email address

✹ [Send Message] File Attachment


This Action block allows you to attach an externally-hosted file, by using its URL.

✹ [Send Message] Animation (GIF)


This Action block allows you to insert a GIF animation, by using the URL of the animated image.



This Action block is used to to send a Carousel of items/products.

Each item can be customized with a title, image, or description, and allows you to add buttons which will open the URL you specify there once clicked by a user.

✹ [Send Message] Private Note


This Action block sends a private note message in the conversation.

Notes are not visible by users, only your operators will be able to view it in the conversation.

✹ [Update User] Update User Name


This Action block allows you to set or update the user's nickname in the conversation.

✹ [Update User] Update User Email


This Action block allows you to set or update the user's email address in the conversation.

✹ [Update User] Update User Phone


This Action block allows you to set or update the user's phone number in the conversation.

✹ [Update User] Update Custom Data


This Action block will add or update a static custom data in the conversation.

The Custom Data set from this block is "static", meaning you cannot use variables memorized during the scenario.
To use a variable, you will need to use the "Set with Bot Memory" block

✹ [Update User] Set with Bot Memory


This Action block will add or update a custom data in the conversation, by using a memorized value.

You can use any value that was "memorized" during this scenario. For instance, if you have asked users for a specific information with a field input and memorized it inside of a key.

✹ [Update User] Add Session Segment


This Action block will add a segment to the ongoing conversation

✹ [Update User] Submit Event


This Action block is used to push an event in the user's profile.

For instance, this can be used if you'd like to trigger an automated campaign from your scenario.

✹ [Update User] Ask User Feedback


This Action block can be used to send an automated Raring/Feedback Request to the user, inside of the conversation.

✹ [Internal Actions] Update Chat State


This Action block changes the state of the conversation among one of the three states:
Pending — a conversation which contains unread messages
Unresolved — when a conversation is still on-going, but messages have been read
Resolved — the conversation has been marked as resolved (closed)

✹ [Internal Actions] Wait


This Action block will temporarily pause the execution of the scenario for the duration specified.

The maximum time is 30 seconds.
Note that messages sent by operator during a "Wait" block will not interrupt the scenario.

✹ [Internal Actions] Block User


This Action block is used to block the current user from sending messages into your conversations.

✹ [Internal Actions] Mention Operator


This Action block allows you to mention an operator.

The mention will appear as a private note, and the operator will be notified according to their notification settings.

✹ [Internal Actions] Assign Operator


This Action block lets you assign or reassign the conversation to the selected operator of your team

✹ [Internal Actions] Submit Web Hooks


This Action block allows you to submit Webhooks from your scenario.

The "name" specified there, along with the (memorized or static) custom data will also appear in the payload.
More information about sending Webhooks with the Bot plugin in this guide

✹ [AI Actions] Helpdesk AI


This Action block allows you to suggest articles relevant to the query of your user

This special block leverages AI to suggest Helpdesk articles relevant to the last messages sent by the user. The AI is able to parse the content of the last messages sent, identify the request, and offer the user to visit articles relevant to their question.
You can customize the message attached, but also specify the locale of the articles which should be suggested.

When adding this block to your flow, you can also add a second Action block next to it (by adding a new child from its parent block). This secondary block will be executed if the AI does not find any article pertinent enough to be shared with the user.

A dedicated guide on this feature is available here

Condition Blocks



Condition Blocks are used to verify if a specific condition is met before continuing with your flow, but also to split them into different branches.
Each of these block accepts a "is" or "is not" parameter, allowing you to check the opposite as well.

For instance, after your initial "User Message Matches" Event block, you can split your scenario into 2 branches to check on one hand if the conversation is new ("is)" in order to ask the user for more information automatically, and on the other if it is not a new conversation ("is not") to greet the user a welcome back message.

Condition blocks also allow you to check for more condition within the same block. The Bot will then check if all the conditions specified are met in order to proceed further down on that branch.

✹ Conversation is New


This Condition block allows you to check if the conversation new, meaning that there was no previous message history

This block is often used right after the first "User Message Matches" Event block, when you would like a scenario to trigger the first time they contact you exclusively.

✹ Session Segment


This Condition block allows you to check if a specific segment exists in the conversation

If you choose to specify several, the Bot will check if any of the specified segment is present in the conversation

✹ Check Custom Data


This Condition block allows you to check if a specific segment exists in the conversation

If you choose to specify several, the Bot will check if any of the specified custom data is present in the conversation

✹ Current Page URL


This Condition block checks whether the current URL browsed by the user matches the ones you've specified here.

When specifying a URL to check, you can use wildcards in order order to check for any path or sub-path.

Single wildcards * inside of a URL are used to detect any specific sub-folder. For instance, to detect both https://acme.com/fr/account and https://acme.com/en/account
You can use a Match value of https://acme.com/*/account

Double wildcards ** inside of a URL are used if you would like to match not only a specific sub-folder, by and of the path contained in these ones as well.
For instance, to match both https://acme.com/fr/dashboard/index.html or https://acme.com/fr/helpdesk/getting-started/how-to-install
You can use a Match value of https://acme.com/fr/**

In order to detect a whole domain, such as acme.com you would therefore need to check for 2 urls: https://acme.com and https://acme.com/** in order to cover both the home page, and any of its sub-paths.

Example of configuration to detect a whole domain (home page any any sub-pages)

✹ User Location


This Condition block is used to detect the user's geographical location, based on his current IP address.

If you choose to specify several, the Bot will check if the user is from any of the specified countries.

✹ User Language


This Condition block is used to detect the user's language.

This information is fetched from the user's browser language preference, or information provided by the origin channel (Messenger, WhatsApp, etc) when available.
If you choose to specify several, the Bot will check if the user matches any of the language you've specified

✹ Current Hour


This Condition block will check if the current time (based on the selected timezone) matches the time range specified.

As an example, if you would like to check if the user is contacting you out of business hours, you could proceed one of the following way:
- checking if the time is between 18:00 and 09:00
- checking is the is not between 09:00 and 18:00

✹ Current Day


This Condition block will check if the current day (based on the selected timezone) matches the days specified.

✹ Bot Memory has Data


This Condition block allows you check if a specific key/value data pair has been memorized by the Bot during this specific scenario

✹ User Email is Matching


This Condition block allows you to check if the user's email address matches a specific one.

This block is a good way to perform an action when specific users reach out.
For instance, it can be used to create a black list of undesirable users for instance, by blocking them or resolving the conversation automatically should they attempt to reach you.

✹ User Email is Set


This Condition block checks if the user's email address is set in the conversation

✹ User Phone is Set


This Condition block checks if the user's phone number is set in the conversation

✹ User Name is Set


This Condition block checks if the user's nickname is set in the conversation

✹ Conversation State


This Condition block allows you to check the current state of a conversation among one of the three states:
Pending — a conversation which contains unread messages
Unresolved — when a conversation is still on-going, but messages have been read
Resolved — the conversation has been marked as resolved (closed)

To check if a conversation state is either "A" or "B", you can select an additional condition, or simply check if the conversation state is not "C"

✹ User is Available


This Condition block can be used to determine if the user is still present in the chat, or if he has left.

✹ Support is Available


This Condition block detects whether your support team is still online or not.

If even one operator appears online, the support will be considered as "available".
However, if all of your operators are offline or invisible, the support will then be considered as "unavailable".

You can leverage the Availability settings of your account to appear online/offline during certain hours for instance.

✹ HTTP Response Match


This Condition block enables you to check a response from your server.

This block will expect a specific response code and body that you specified.

Exit Blocks



Exit blocks are particular ones, they will terminate the execution of the current scenario and perform an action.
They are optional, and whether you should them (and which one) is very situational. We'll review how they work to help you have a better understanding.

✹ Stop Scenario


This Exit block will terminate the execution of your current scenario.

The "Stop Scenario" is generally used at the end of scenario (as the last block of your different branches) when you would like a scenario to not be trigger again during the exchange.
This is for instance helpful if you would like your scenario not to trigger multiple times when users sens several messages for instance.

By default, a scenario will be able to start again right away. The Exit block prevents it to start again for the next 24h.

Also note that a scenario will also be interrupted when an operator sends a message in a conversation. When an operator has sent a message, this prevents any scenario from firing for the next 20 minutes by default

✹ Run Scenario


This Exit block will stop the execution of the current scenario, and immediately start another one.

This block can be used to easily start a pre-configured scenario at the end of your current one. It is a good way to build more elaborate flow and allows you to manage your different flow more efficiently and ergonomically by dividing your setup into different smaller scenarios.

"Run Scenario" Exit blocks can also be used to create loops, this is something we discuss in this dedicated article.

Blocks Options



All the previous block you've been through have options available, which offer interesting productivity gains.

Copy Block



No wizardy here, each block can be copied to your clipboard by clicking the "Copy block" button.



Copy As Proxy



Proxy block are very powerful and will help you a lot as they prevent you from:
building messy bot scenarios
creating complex loopback behavior

Below is an example of a bot scenario without any proxy block vs one that has embraced it.




Frequently Asked Questions



What better way to end a guide than a FAQ section? If you still have questions, perhaps you'll find the answer you're looking for here!
You'll find some extra information to dive even deeper in the Bot and have the opportunity to review some of the most common questions

Don't hesitate visiting our Getting Started with the Crisp chatbot guide for extra tips!

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

Why are my users unable to type in the chatbox so suddenly?


You may have triggered a scenario with "Required" fields or buttons. This option, available on both of these blocks, will prevent the user from sending message until the previous button or field has been completed.

In such cases, your users will see a yellow banner letting them know that a step is required in order to continue the conversation.

How can I track how often scenarios or specific branches have been followed by my users?


You can do achieve that by using the "Add Session Segment" Action block at key moments of your scenario. For instance, when a specific URL is detected or when you users click on a button!
You will then be able to track the frequency of apparition of these segments in the Analytic tools, allowing you to monitor the paths taken by your users.

Can I use a webhook to send a request to the Bot and continue the flow?


Webhooks allow you to communicate with your server in one-way only.
You can use the Bot to send data from your bot scenario to your server, but if you'd like to do an action or send a message containing information fetched from your database you will need to use the API instead.
Don't hesitate checking our REST API references to get started in that direction.

Updated on: 02/03/2024

Was this article helpful?

Share your feedback

Cancel

Thank you!