How to add the chatbot plugin to my website?
The chatbot plugin helps you to create your own chatbot. Draw complex response flows, with events (eg. user sent message), actions (eg. send response message) and conditions (eg. check segment). The Bot plugin is able to answer messages coming from any source, eg. chatbox, Messenger, etc.
This guide goes into explaining how the Bot plugin works, and how you can get the most out of it. Our chatbot plugin comes with a visual builder so you can build chatbot scenarios without any coding skills.
To access the chatbot plugin and install it, simply go to Plugins > Bot
Bot Plugin is available from the Crisp Unlimited plan
A chatbot is not a live chat, if you're looking for ways to add a live chat to your website, please click here
Don't forget to subscribe to our Youtube Channel for tips and tricks about Crisp and customer service.
The Bot plugin is capable of the following use cases (amongst non-listed others):
Simulate an human conversation, with fallbacks if the bot does not understand
Automate responses to common questions, with choice buttons to guide the user to more precise answers
Pre-qualify people when they land on your website (eg. is the visitor a developer, sales, CEO, etc.?)
Auto-assign & mention operators from your team, based on certain criteria (eg. user country, language, clicked choice buttons, etc.)
Automatically block users based on behavior
Forward data to your own backend via Web Hooks
A Bot scenario is a map of connected blocks, which are used to create a response flow logic. At the very beginning, it matches a message sent by an user, or a Crisp event, and then descends through the logic and sends response messages based on certain conditions and further events from the user.
You can create as many scenarios as you need. Scenarios are handy to organize your Bot into different sections, eg. one scenario can be used to qualify visitors by asking them questions, while another one can be used to answer on questions about, say, GDPR.
Thanks to our no code builder, you can create custom chatbot to let you build the scenario that better fit with your needs.
You can deactivate and activate scenarios at will, without having to remove them.
Available scenario blocks types are the following:
Entry gate: entry of your scenario, this block does nothing (it serves as the first configured block)
Event block: an event that triggers progress in the scenario map, eg. message received
Action block: proceed an action, eg. send a message
Condition block: check for a condition, eg. if user has an email set
Exit scenario: exit of your scenario, this block is not required in all scenarios; handy if you want to connect your scenario to another scenario (ie. exit to another scenario), or stop scenario
The entry gate cannot be configured.
The event block can be configured to listen to the following events:
User Message Matches: If user message matches at least one of predefined messages.
Message Action: If an user action occurs on a message, eg. button clicked.
User Email Is Set: If email is updated in an active conversation.
User Phone Is Set: If phone number is updated in an active conversation.
User Nickname Is Set: If nickname is updated in an active conversation.
Data Is Set: If data is updated in an active conversation.
Segments Are Set: If segments are updated in an active conversation.
User Changes Page: If an user in an active conversation changes page.
Crisp Event Fires: If a Crisp event fires (the user email must be set).
In new conversations, your scenario can only start with one of these two blocks: "User Message Matches" or "Crisp Event Fires". The chatbot won't start if you use another event block at the beginning of the scenario.
For active conversations, you can use any block to start the chatbot.
The action block can be configured to perform following actions:
Send Message: Send a message to the user. Text, file, form, etc.
Show Compose: Show a compose indicator to the user, for a pre-defined duration.
Push Session Event: Push an event to the session, eg. to fire an automated campaign.
Set Session Segment: Add a segment, or multiple segments to the session.
Set Session Data: Add a data key, or multiple data keys to the session.
Block User: Block user from using the chatbox.
Change Chat State: Resolve or unresolve the conversation, to clean up the inbox.
Set User Nickname: Set the user nickname value for conversation.
Set User Email: Set the user email value for conversation.
Set User Phone: Set the user phone value for conversation.
Mention Operator: Mention target operator and send a notification.
Assign Operator: Set target operator as assigned to conversation.
Store Memorized Value: Remember context memory in conversation data.
Wait: Hold for a few seconds and do nothing.
Web Hooks: Send 'plugin:event' to your Web Hooks.
The condition block can be configured to check for the following data points:
Check Session Segments: If the session has any segment from defined list of segments.
Check Session Data: If the session has a data key that matches defined value.
Check User Location: If user is geolocated in defined country.
Check User Language: If user has any language from the defined language list.
Page URL Matches: If browsed page matches any defined URL pattern.
Time Of The Day Between: If current time of the day is in a defined time range.
Day Of The Week Matches: If current day of the week matches a selected day.
Memory Value Matches: If memorized value is set or equal to a defined value.
User Email Matches: If user email matches any defined email pattern.
User Has Email Set: If user has an email address defined on their profile.
User Has Phone Set: If user has a phone number defined on their profile.
User Has Nickname Set: If user has a nickname defined on their profile.
Check Chat State: If current conversation state matches (eg. 'resolved').
Check User Availability: If user availability is either online or offline, as defined.
Check Website Availability: If website availability is either online or away, as defined.
Conversation Is New: If conversation is new, ie. there is only a single message.
HTTP Response Match: Call external HTTP URL and check response for a match.
The exit scenario block can be configured to exit to:
Run Scenario: Exit to another Scenario, which is run when the block fires.
Stop Scenario: Stop current Scenario, and prevent it from re-firing for the session in the next 24 hours.
To make sure your scenario works properly before you hit the green "Deploy / Publish" button, you can test it in the right chat view in the scenario editor.
Make sure to hit the blue "Save Draft" button if you have unsaved changes, as the test mode uses the last saved draft scenario.
You can easily reset the test system by clicking on "Start again" in the yellow "The scenario is running" bar, to start over again.
When you test a scenario in the test chat view in the Bot plugin interface, conditions will always match (as there's no data to match them against there). Also, you won't be able to test some events and actions there (ie. event and actions that are outside of the chat context).
When you insert a new block, you need to configure it before it can be saved / accepted by the plugin.
To help you recognize blocks that are awaiting configuration, the Bot plugin will show an icon on each block, letting you know whether the block is properly configured or not.
When you save your Bot draft, make sure all blocks are properly configured (ie. green icons on every block). Otherwise, you will not be able to save the draft.
Large scenarios can be difficult to maintain on the same interface, especially as they grow larger. In this event, it can be a good idea to split it up in smaller scenarios, and connect those together.
Scenarios can be connected together using the Exit scenario block. Scenarios that are disabled won't be branched to; this can be handy if you need to disable parts of your larger scenario in a click.
Make sure you're not creating infinite loops in your connected scenarios. Though this will not put into danger our systems (as we require an event as the starting block of a scenario), such loops can be quite frustrating for your users (they can create a parrot effect for the end user, ie. the bot keeps repeating itself).
For advanced uses, the Bot plugin can be used to send collected data to your HTTP server via Web Hooks (see our article on how to use Web Hooks).
Here's how to set this up:
Before we can fire events from the Bot, we need the Web Hook connection to your HTTP server to be active:
Go to your Crisp Dashboard
Click on "Settings"
Click on "Website Settings" and then pick your website
In your website settings, scroll down to "Advanced configuration"
Open the "Web Hooks" section
Click on "Add a Web Hook"
Enter a name for the hook, the URL of your endpoint (see our doc on Web Hooks data format)
In the "Filter Events" list, scroll down and select plugin:event
Finish by clicking on "Add Hook Target"
Now that our hook binding is configured and active, we can start crafting Bot events, which will come to your HTTP endpoint as the plugin:event namespace:
Go to your scenario
Where relevant, add an Action block
In the block configuration, pick the "Web Hooks" action type
Enter a custom event name (for you to recognize which event it is)
Enter some data (you can even enter saved values from memory keys)
Close, save and deploy live scenario
Let's fire a test event from the chatbox:
Go to your chatbox, and trigger the scenario flow down to the Action block that contains the "Web Hooks" action type configured in (2)
A Web Hook will be emitted from Crisp servers, you will receive an HTTP payload similar to the one below:
Yes! A scenario can be paused in a single click. Go to the Bot plugin home section, and look for your scenario in the left sidebar. Toggle the green button to OFF.
The Bot plugin is part of the Unlimited plan. It is not available separately from Unlimited.
Ensure you deployed live the last version of your scenario draft (hit the green button)
Open a private browsing session and check from a fresh chatbox session; some scenarios may be locked if you test them over and over again in the same chatbox session
Make sure your scenario event block fires properly (ie. ensure you test with the correct message pattern)
Check all blocks are properly configured (there is no red icon on the left of a block, icons are all green)
Some languages, such as Chinese, Thai and others have no spaces between words in sentences. In such case, the regular pattern wildcard (*) won't work to match "any word" between given words. As well, Hebrew and Persian, due to their right-to-left writing, will not support single-wildcard fuzzy matching rules.
You're looking to use a double wildcard instead (**), which is not space-aware and does not consider character ordering (LTR vs RTL).
Feel free to contact us if you have any question, or if you cannot solve your issue. We'll gladly help you.
Enjoy 5 chatbots examples by clicking on this link. You can even download scenarios to import them in your chatbot dashboard. It may help you better understand how to set your dream chatbot.
This guide goes into explaining how the Bot plugin works, and how you can get the most out of it. Our chatbot plugin comes with a visual builder so you can build chatbot scenarios without any coding skills.
To access the chatbot plugin and install it, simply go to Plugins > Bot
Bot Plugin is available from the Crisp Unlimited plan
A chatbot is not a live chat, if you're looking for ways to add a live chat to your website, please click here
Video tutorial
Don't forget to subscribe to our Youtube Channel for tips and tricks about Crisp and customer service.
What can I do with the Bot plugin? (use cases)
The Bot plugin is capable of the following use cases (amongst non-listed others):
Simulate an human conversation, with fallbacks if the bot does not understand
Automate responses to common questions, with choice buttons to guide the user to more precise answers
Pre-qualify people when they land on your website (eg. is the visitor a developer, sales, CEO, etc.?)
Auto-assign & mention operators from your team, based on certain criteria (eg. user country, language, clicked choice buttons, etc.)
Automatically block users based on behavior
Forward data to your own backend via Web Hooks
What is a Bot scenario?
A Bot scenario is a map of connected blocks, which are used to create a response flow logic. At the very beginning, it matches a message sent by an user, or a Crisp event, and then descends through the logic and sends response messages based on certain conditions and further events from the user.
You can create as many scenarios as you need. Scenarios are handy to organize your Bot into different sections, eg. one scenario can be used to qualify visitors by asking them questions, while another one can be used to answer on questions about, say, GDPR.
Thanks to our no code builder, you can create custom chatbot to let you build the scenario that better fit with your needs.
You can deactivate and activate scenarios at will, without having to remove them.
Which scenario block types can I use?
Available scenario blocks types are the following:
Entry gate: entry of your scenario, this block does nothing (it serves as the first configured block)
Event block: an event that triggers progress in the scenario map, eg. message received
Action block: proceed an action, eg. send a message
Condition block: check for a condition, eg. if user has an email set
Exit scenario: exit of your scenario, this block is not required in all scenarios; handy if you want to connect your scenario to another scenario (ie. exit to another scenario), or stop scenario
Entry gate features
The entry gate cannot be configured.
Event block features
The event block can be configured to listen to the following events:
User Message Matches: If user message matches at least one of predefined messages.
Message Action: If an user action occurs on a message, eg. button clicked.
User Email Is Set: If email is updated in an active conversation.
User Phone Is Set: If phone number is updated in an active conversation.
User Nickname Is Set: If nickname is updated in an active conversation.
Data Is Set: If data is updated in an active conversation.
Segments Are Set: If segments are updated in an active conversation.
User Changes Page: If an user in an active conversation changes page.
Crisp Event Fires: If a Crisp event fires (the user email must be set).
In new conversations, your scenario can only start with one of these two blocks: "User Message Matches" or "Crisp Event Fires". The chatbot won't start if you use another event block at the beginning of the scenario.
For active conversations, you can use any block to start the chatbot.
Action block features
The action block can be configured to perform following actions:
Send Message: Send a message to the user. Text, file, form, etc.
Show Compose: Show a compose indicator to the user, for a pre-defined duration.
Push Session Event: Push an event to the session, eg. to fire an automated campaign.
Set Session Segment: Add a segment, or multiple segments to the session.
Set Session Data: Add a data key, or multiple data keys to the session.
Block User: Block user from using the chatbox.
Change Chat State: Resolve or unresolve the conversation, to clean up the inbox.
Set User Nickname: Set the user nickname value for conversation.
Set User Email: Set the user email value for conversation.
Set User Phone: Set the user phone value for conversation.
Mention Operator: Mention target operator and send a notification.
Assign Operator: Set target operator as assigned to conversation.
Store Memorized Value: Remember context memory in conversation data.
Wait: Hold for a few seconds and do nothing.
Web Hooks: Send 'plugin:event' to your Web Hooks.
Condition block features
The condition block can be configured to check for the following data points:
Check Session Segments: If the session has any segment from defined list of segments.
Check Session Data: If the session has a data key that matches defined value.
Check User Location: If user is geolocated in defined country.
Check User Language: If user has any language from the defined language list.
Page URL Matches: If browsed page matches any defined URL pattern.
Time Of The Day Between: If current time of the day is in a defined time range.
Day Of The Week Matches: If current day of the week matches a selected day.
Memory Value Matches: If memorized value is set or equal to a defined value.
User Email Matches: If user email matches any defined email pattern.
User Has Email Set: If user has an email address defined on their profile.
User Has Phone Set: If user has a phone number defined on their profile.
User Has Nickname Set: If user has a nickname defined on their profile.
Check Chat State: If current conversation state matches (eg. 'resolved').
Check User Availability: If user availability is either online or offline, as defined.
Check Website Availability: If website availability is either online or away, as defined.
Conversation Is New: If conversation is new, ie. there is only a single message.
HTTP Response Match: Call external HTTP URL and check response for a match.
Exit scenario features
The exit scenario block can be configured to exit to:
Run Scenario: Exit to another Scenario, which is run when the block fires.
Stop Scenario: Stop current Scenario, and prevent it from re-firing for the session in the next 24 hours.
How can I test my scenario before I deploy it live?
To make sure your scenario works properly before you hit the green "Deploy / Publish" button, you can test it in the right chat view in the scenario editor.
Make sure to hit the blue "Save Draft" button if you have unsaved changes, as the test mode uses the last saved draft scenario.
You can easily reset the test system by clicking on "Start again" in the yellow "The scenario is running" bar, to start over again.
When you test a scenario in the test chat view in the Bot plugin interface, conditions will always match (as there's no data to match them against there). Also, you won't be able to test some events and actions there (ie. event and actions that are outside of the chat context).
How can I make sure a block is properly configured?
When you insert a new block, you need to configure it before it can be saved / accepted by the plugin.
To help you recognize blocks that are awaiting configuration, the Bot plugin will show an icon on each block, letting you know whether the block is properly configured or not.
When you save your Bot draft, make sure all blocks are properly configured (ie. green icons on every block). Otherwise, you will not be able to save the draft.
How to connect scenarios together?
Large scenarios can be difficult to maintain on the same interface, especially as they grow larger. In this event, it can be a good idea to split it up in smaller scenarios, and connect those together.
Scenarios can be connected together using the Exit scenario block. Scenarios that are disabled won't be branched to; this can be handy if you need to disable parts of your larger scenario in a click.
Make sure you're not creating infinite loops in your connected scenarios. Though this will not put into danger our systems (as we require an event as the starting block of a scenario), such loops can be quite frustrating for your users (they can create a parrot effect for the end user, ie. the bot keeps repeating itself).
Enjoy 5 chatbots examples while clicking on this link. You can even download scenarios to import them in your chatbot dashboard.
How can I send events to my external servers?
For advanced uses, the Bot plugin can be used to send collected data to your HTTP server via Web Hooks (see our article on how to use Web Hooks).
Here's how to set this up:
1. Setup the Web Hook
Before we can fire events from the Bot, we need the Web Hook connection to your HTTP server to be active:
Go to your Crisp Dashboard
Click on "Settings"
Click on "Website Settings" and then pick your website
In your website settings, scroll down to "Advanced configuration"
Open the "Web Hooks" section
Click on "Add a Web Hook"
Enter a name for the hook, the URL of your endpoint (see our doc on Web Hooks data format)
In the "Filter Events" list, scroll down and select plugin:event
Finish by clicking on "Add Hook Target"
2. Fire an event from the Bot
Now that our hook binding is configured and active, we can start crafting Bot events, which will come to your HTTP endpoint as the plugin:event namespace:
Go to your scenario
Where relevant, add an Action block
In the block configuration, pick the "Web Hooks" action type
Enter a custom event name (for you to recognize which event it is)
Enter some data (you can even enter saved values from memory keys)
Close, save and deploy live scenario
3. Receive an event from the Bot
Let's fire a test event from the chatbox:
Go to your chatbox, and trigger the scenario flow down to the Action block that contains the "Web Hooks" action type configured in (2)
A Web Hook will be emitted from Crisp servers, you will receive an HTTP payload similar to the one below:
{
website_id: "fd7e9cfe-5a92-49f3-afe1-5e40fdc7a629",
event: "plugin:event",
data: {
"website_id": "fd7e9cfe-5a92-49f3-afe1-5e40fdc7a629",
"plugin_id": "730a3692-55ac-4cc4-a305-10bb23730e80",
"urn": "urn:crisp.im:bot:0",
"name": "sales-bot-triggered",
"data": {
"lead_type": "developer",
"name": "John Doe",
"email": "john.doe@crisp.chat"
}
}Can I pause a scenario?
Yes! A scenario can be paused in a single click. Go to the Bot plugin home section, and look for your scenario in the left sidebar. Toggle the green button to OFF.
Which plan do I need to use the Bot plugin?
The Bot plugin is part of the Unlimited plan. It is not available separately from Unlimited.
Troubleshoot common issues
1. The bot does not work when I test it live on my chatbox
Ensure you deployed live the last version of your scenario draft (hit the green button)
Open a private browsing session and check from a fresh chatbox session; some scenarios may be locked if you test them over and over again in the same chatbox session
Make sure your scenario event block fires properly (ie. ensure you test with the correct message pattern)
2. It says "invalid data" when I save my scenario
Check all blocks are properly configured (there is no red icon on the left of a block, icons are all green)
3. My fuzzy patterns in Hebrew, Persian, Chinese, Thai and others don't work
Some languages, such as Chinese, Thai and others have no spaces between words in sentences. In such case, the regular pattern wildcard (*) won't work to match "any word" between given words. As well, Hebrew and Persian, due to their right-to-left writing, will not support single-wildcard fuzzy matching rules.
You're looking to use a double wildcard instead (**), which is not space-aware and does not consider character ordering (LTR vs RTL).
4. I still cannot find a solution to my issue
Feel free to contact us if you have any question, or if you cannot solve your issue. We'll gladly help you.
Enjoy 5 chatbots examples by clicking on this link. You can even download scenarios to import them in your chatbot dashboard. It may help you better understand how to set your dream chatbot.
Updated on: 13/06/2022
Thank you!