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!
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 Changed • URL Change Detected
→ Awaiting Operator • User Email Updated
→ User Name Updated • User Phone Updated
→ Custom Data Updated • Segments Updated
→ New Crisp Event • New User Message
● Action Blocks
→ Send Message: Composition • Send Message: Text
→ Send Message: Button Picker • Send Message: Field Input
→ Send Message: File Attachment • Send Message: Animation (GIF)
→ Send Message: Carousel • Send Message: Private Note
→ Update User: Update User Name • Update User: Update User Email
→ Update User: Update User Phone • Update User: Update Custom Data
→ Update User: Set with Bot Memory • Update User: Add Session Segment
→ Update User: Submit Event • Update User: Ask User Feedback
→ Internal Actions: Update Chat State • Internal Actions: Wait
→ Internal Actions: Block User • Internal Actions: Mention Operator
→ Internal Actions: Assign Operator • Internal Actions: Submit Web Hooks
→ AI Actions: Helpdesk AI
● Condition Blocks
→ Conversation is New • Session Segment
→ Check Custom Data • Current Page URL
→ User Location • User Language
→ Current Hour • Current Day
→ Bot Memory has Data • User Email is Matching
→ User Email is Set • User Phone is Set
→ User Name is Set • Conversation State
→ Conversation State • Support is Available
→ HTTP Response Match
● Exit Blocks
→ Stop Scenario • Run Scenario
● Block Options
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
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!
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.
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
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.
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
"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
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)
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.
This Event block is used to detect the moment the user's email address is either set or changed.
This Event block is used to detect the moment the user's phone number is either set or changed.
This Event block is used to detect the moment the user's nickname is either set or changed.
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
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
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.
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.
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.
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.
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 }}
This Action block will display a "composition animation" for the duration you specify
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
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
This Action block allows you to attach an externally-hosted file, by using its URL.
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.
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.
This Action block allows you to set or update the user's nickname in the conversation.
This Action block allows you to set or update the user's email address in the conversation.
This Action block allows you to set or update the user's phone number in the conversation.
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
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.
This Action block will add a segment to the ongoing conversation
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.
This Action block can be used to send an automated Raring/Feedback Request to the user, inside of the conversation.
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)
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.
This Action block is used to block the current user from sending messages into your conversations.
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.
This Action block lets you assign or reassign the conversation to the selected operator of your team
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.
This allows you to pass value memorized during your scenario, or to pass a static value to help differentiate this webhook blocks from others when you receive them on your server.
Currently at least one static or memorized data is required. If you do not need to pass additional information, you can simply use a dummy static data key/value pair
Once your webhook blocks created, you need to configure where your webhooks will be received.
To do that, simply head over to:
Settings > Website Settings > Advanced Configuration > Webhooks
There you can create a new webhook and name it, specify the endpoint url of the server receiving the webhook, and select the very last event plugin:event which is used by the Chatbot.
Note that webhooks are only fired when your scenario is deployed live
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 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.
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.
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
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.
If you are looking to check if a custom data key exists, regardless of its value, you can use the wildcard * as value. Here is an example to check if a Shopify order exists before sharing a tracking link, with this condition block: shopify_latest_tracking_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.
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.
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
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
This Condition block will check if the current day (based on the selected timezone) matches the days specified.
This Condition block allows you check if a specific key/value data pair has been memorized by the Bot during this specific scenario
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.
This Condition block checks if the user's email address is set in the conversation
This Condition block checks if the user's phone number is set in the conversation
This Condition block checks if the user's nickname is set in the conversation
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"
This Condition block can be used to determine if the user is still present in the chat, or if he has left.
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.
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 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.
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
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, in order to start a previous scenario for instance. To go back to a previous step within the same scenario, you can Proxy blocks.
All the previous block you've been through have options available, which offer interesting productivity gains.
No wizardy here, each block can be copied to your clipboard by clicking the "Copy block" button.
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.
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!
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.
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.
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.
You can simply connect your block to another one previously used one with a wire, and this without any issue. The block you then link towards will be executed even if it was already used in the past.
This is for instance helpful if you wish to share a button picker to offer your users the option to go back to a previous step. Once the event block of your button added, you can then connect it to the step you wish to take them back to.
However it can be cumbersome to have wires around going back across your scenarios, rendering it quite difficult to manage. To resolve that, you can also use Proxy blocks.
You can select the block you wish to go back to and from to see an option appear: "Copy as a Proxy". You can then paste this block in your flow (in our earlier example, after the event block of our button) and when this block is executed it will take them back to that block automatically, just as if you had connected it, but without the extra wires, to make it more readable.
When you receive a reply to a story in Crisp, we will automatically add a label inside of that message. You will see a prefix "Reply to a story".
To detect these messages, you can then simply use a User Message Matches Event block with the value **Reply to story: **, which the bot will pick up to start your flow. This can allow you to automatically resolve these conversations, or perform any other actions you'd like to implement.
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 Changed • URL Change Detected
→ Awaiting Operator • User Email Updated
→ User Name Updated • User Phone Updated
→ Custom Data Updated • Segments Updated
→ New Crisp Event • New User Message
● Action Blocks
→ Send Message: Composition • Send Message: Text
→ Send Message: Button Picker • Send Message: Field Input
→ Send Message: File Attachment • Send Message: Animation (GIF)
→ Send Message: Carousel • Send Message: Private Note
→ Update User: Update User Name • Update User: Update User Email
→ Update User: Update User Phone • Update User: Update Custom Data
→ Update User: Set with Bot Memory • Update User: Add Session Segment
→ Update User: Submit Event • Update User: Ask User Feedback
→ Internal Actions: Update Chat State • Internal Actions: Wait
→ Internal Actions: Block User • Internal Actions: Mention Operator
→ Internal Actions: Assign Operator • Internal Actions: Submit Web Hooks
→ AI Actions: Helpdesk AI
● Condition Blocks
→ Conversation is New • Session Segment
→ Check Custom Data • Current Page URL
→ User Location • User Language
→ Current Hour • Current Day
→ Bot Memory has Data • User Email is Matching
→ User Email is Set • User Phone is Set
→ User Name is Set • Conversation State
→ Conversation State • Support is Available
→ HTTP Response Match
● Exit Blocks
→ Stop Scenario • Run 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.
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.
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
"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
✹ [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
✹ [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.
✹ [Send Message] Carousel
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.
This allows you to pass value memorized during your scenario, or to pass a static value to help differentiate this webhook blocks from others when you receive them on your server.
Currently at least one static or memorized data is required. If you do not need to pass additional information, you can simply use a dummy static data key/value pair
Once your webhook blocks created, you need to configure where your webhooks will be received.
To do that, simply head over to:
Settings > Website Settings > Advanced Configuration > Webhooks
There you can create a new webhook and name it, specify the endpoint url of the server receiving the webhook, and select the very last event plugin:event which is used by the Chatbot.
Note that webhooks are only fired when your scenario is deployed live
✹ [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.
If you are looking to check if a custom data key exists, regardless of its value, you can use the wildcard * as value. Here is an example to check if a Shopify order exists before sharing a tracking link, with this condition block: shopify_latest_tracking_url: *
✹ 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.
✹ 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, in order to start a previous scenario for instance. To go back to a previous step within the same scenario, you can Proxy blocks.
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.
How can I create loops, to take my users to a previous step?
You can simply connect your block to another one previously used one with a wire, and this without any issue. The block you then link towards will be executed even if it was already used in the past.
This is for instance helpful if you wish to share a button picker to offer your users the option to go back to a previous step. Once the event block of your button added, you can then connect it to the step you wish to take them back to.
However it can be cumbersome to have wires around going back across your scenarios, rendering it quite difficult to manage. To resolve that, you can also use Proxy blocks.
You can select the block you wish to go back to and from to see an option appear: "Copy as a Proxy". You can then paste this block in your flow (in our earlier example, after the event block of our button) and when this block is executed it will take them back to that block automatically, just as if you had connected it, but without the extra wires, to make it more readable.
How can I detect replies to Instagram stories with the Bot?
When you receive a reply to a story in Crisp, we will automatically add a label inside of that message. You will see a prefix "Reply to a story".
To detect these messages, you can then simply use a User Message Matches Event block with the value **Reply to story: **, which the bot will pick up to start your flow. This can allow you to automatically resolve these conversations, or perform any other actions you'd like to implement.
Updated on: 28/10/2024
Thank you!