The Bot plugin helps you 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.

Video tutorial



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. For instance, match a message sent by an user (which triggers the scenario), and then descend through the logic and send 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.

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

Available scenario block types that you can insert

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, eg. an automated campaign starts.

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 3 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.

A scenario being tested in the chat view

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.

Click on "Start again" to reset your test chat

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.

This block is properly configured (green)

This block is not configured (red)

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.

An attempt to save the draft was made, but a block is not configured

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.

Scenarios must start with an Event block, immediately following the Entry gate. You will need to connect scenarios in such a way you never exit previous scenario on an event, and you always enter next scenario on an event.

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).

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
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": "Valerian Saliou",
"email": "valerian@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.

Toggle to OFF the active scenario to pause it

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 live scenario does not run, even if it works in the draft test chat

This issue is common for websites matching message events with a wildcard (*), or matching twice the same pattern for two different scenarios.

As the Crisp Bot is a state machine (pretty much like a circuit), it tries to enter the first scenario it finds a match for on the first block (usually the event block matching a message). Even if further conditions do not match, once it has entered a scenario, it won't exit it and test next ones.

Thus, if you want to match the same message pattern in different scenarios, group them in a common "routing scenario" that matches this pattern once, and routes the bot to the relevant sub-scenario depending on conditions (eg. weekend, conversation is new, etc.). You can use the "Exit gate" block for this, with the "Run scenario" setup, for each sub-scenario to route to.

Most weird "My live scenario does not work" issues can be solved by following this best-practice. Crisp Bot is powerful, which may not make it as straightforward as it could have been if it was simpler.

4. My fuzzy patterns in 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.

You're looking to use a double wildcard instead (**), which is not space-aware.

5. 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.
Was this article helpful?
Thank you!