Design a Conversation

These chapters cover the basics of designing a chatbot or voice interaction on Botsociety: canvas, messages, paths, and connections.

Don't feel like reading? Check out our complete workshop on Youtube

The Canvas

In a design page, the conversation design structured in paths is placed in the design canvas. The design canvas is structured like a flowchart and is infinite. The more paths you add, the more the design canvas expands.

To navigate the canvas:

• To move around, scroll or press Spacebar and drag and drop around.

• To zoom in and out use the lens buttons on the left panel . Another way is to press ⌘ command (CTRL on Windows) and then scroll your mouse.

• If you get lost, you can reset the zoom and center the canvas by clicking on the Reset icon between the lens icons on the left panel.

• You can also add free-floating notes on your canvas, more info here

Messages

Writing the message content

Select the Bot Says button to add a message as the chatbot or assistant, or the User Says button in case you want to create a message from the user’s point of view.

We call this the message editor since it’s the space where you add and edit the messages on your design.

Message editors will differ based on the preset you are using and what message types are available, whether the device supports voice or not, etc.

If your design has voice capabilities, you will see the SSML editor, while in devices that do not support voice, you will see the first message type available as the default one.

You can change the type of message added by clicking on the drop-down at the top of the message editor. The drop-down will show you the currently selected message type:

Every message type has its own inputs. For example, a message type 'Image' will have a text input and an image upload:

If you try to add the message now by clicking on the bottom right button, you will see an alert message:

This is because you are missing a required component of the message, the image. To upload it, just click on the image placeholder that says 'Click or drop image here'. Once the image is uploaded, you will be able to add the message.

You can also have message types that have buttons, like the Quick Reply message type:

In that case, you can add one or multiple buttons by filling in where it says 'Quick Reply' and then clicking on 'Add Quick Reply'. You can repeat that operation multiple times to add multiple buttons. Once you add this message, you can decide how the buttons will connect, as this dedicated chapter explains.

All of these components can be combined into a card, which is composed of an image, multiple text inputs, and buttons, like in the RCS preset:

You can also have carousels. Carousels allow you to add the components multiple times in order to create a carousel. You can do that by clicking on the big "+" (plus) icon on the right-hand side of your components. A good example of this is the Messenger carousel:

Editing an existing message

To edit a message, click on the message and to open the editor. You can now perform your edits, changing the message type, or defining the message on different devices.

If you are looking to edit the connections of an existing message, check out the connections chapter.

After making your edits, click on the "Save" button at the bottom right of the message editor to save it. You can also use the Cmd + Enter (Ctrl+Enter on Windows) keyboard shortcut to save.

Moving and reordering messages

To move a message, just drag and drop it around your canvas. You can move a message inside the same path, or you can drag it to another path. The message's connections will be kept even if you move the message around.

Play a message

While there is a Play mode to see the entire design, you can also see this Play icon at the bottom left of the message editor (in voice designs).

If the message is a voice message, clicking the Play button will allow you to listen to it. You can play as many times as you need, which can be helpful when you are adjusting the SSML settings.

Utterances

In conversation design, utterances represent different ways to express a message. In Botsociety, we allow you to add as many utterances as you want in a message, which act as training data when exported.

Adding utterances

To add utterances, click on the “1/1” icon and click “Add utterance” or click Command (Control for Windows) and ArrowUp.

You should see a green light flashing in the editor to signify that this is the new utterance that you are working on. Note that we autofill your first utterance, so you should change this to what you want your second utterance to contain.

Utterances can be only text and SSML, so you cannot change images or other non-text media in a message. Examples of utterances can be text message type, SSML, suggestion chips, the title of a card, the button of a carousel, etc.

Adding an utterance and changing suggestion chips will define alternative content for the suggestion chips themselfs. As with the other utterances, they will be used as training data when exported.

Viewing utterances

To cycle through utterances, you can use the residual menu shown above and click on “Next Utterance” or “Previous Utterance,” or you can use the shortcut Command (Ctrl) + ArrowRight for next and ArrowLeft for previous.

Importing utterances

Want to import utterances from a spreadsheet? It’s possible to import utterances from a CSV file directly onto the message you want to add them to. You can find this option in the residual menu by clicking on the utterances icon.

Simply click on “Import CSV” or click Cmd (Ctrl) + I and upload your CSV file, which has the utterances listed in a vertical list.

Utterances on Play

On Play mode, we currently show the utterance that is the first on the list.

Utterances on Build mode

Utterances that you have added in messages will be visible in Build mode as well, through the white button on the left:

That is so that you can create variables from all the utterances you have added. All you have to do is click on the button above to cycle through them, then select the text you want to declare as a variable.

You will be able to see all the variables from the different utterances on the build mode left-side panel.

Bold, italics, and links: The Markup

On the Botsociety message editor, you can use certain markup rules to transform the text into bold, italics, underlined, and include links.

Bold, Italics, and Underline

For bold text, surround the word or phrase in two underlines from each side. So, writing __Bold__ in the message editor will turn into Bold when the message is added or saved.

For italicized text, add one underline on each side of the word or phrase. So, writing _Italics_ in the message editor will turn into Italics when the message is added or saved.

Finally, for underlined text, add two plus on each side of the word or phrase. Writing ++Underlined++ will return the word with an underline.

These rules work for words or phrases, as long as you do not leave a space between the signs and the first and last letter.

Also, the markdown rules can be combined to create any combination of bold, italicized, and underlined text.

Hyperlinks

You can also add hyperlinks to your text on Botsociety, to mimic how your bot or user would use a link.

To add a hyperlink, add square brackets - [ ] around the word or phrase you would like to have a hyperlink on, and immediately after it (be careful to not leave a space!) add the URL surrounded by parentheses - ( ).

So, the text would look like: [hyperlinked text](https://yourlink.com)

SSML

SSML, which stands for Speech Synthesis Markup Language, is an XML-based markup language for speech synthesis applications. We use SSML to create sound bites for your voice designs.

SSML supports different settings like the following:

• Volume
• Rate
• Pitch
• Emphasis
• Adding a pause

You can use the SSML message header to adjust SSML settings for your voice messages.

If you need to clear any formatting you’ve added, you can do that by pressing the last button in the header .

Multimodal design

Botsociety allows you to design for multiple devices at the same time. When designing for multi-modal experiences, you can define how your experience change (or remains the same) across different devices. You can also preview your design across different designs. To accomplish this, you can define your message on different device, using the message editor.

Note: Some preset (some platforms) do not offer multi-device experiences. In these cases, you will only see one device at the top of your message editor.

Attached devices

By default, your editor will open up with the first device selected. It will look something like this (this example is from the generic preset):

You will notice that the other devices have a little "Link" icon next to them. That represents the fact that, by default, you will be designing messages for these devices as well. In fact, if you try to add a message while that icon is shown, you will notice that the message was defined for both devices:

This is what we call Attached Devices mode. It allows you to quickly design your experience across multiple devices. It is helpful when you expect 90% of your design to be the same across different modalities. By default, the editor will open in Attached Devices mode. You can change the default behavior in the options, as explained below.

Detached devices

If, instead, you want to define a different content depending on the device, you can click on the device icon. Then you will be able to detach it, like so:

Now that the device is detached, you can change the content of that message only for that particular device. This is useful if you need to - for example - change the content of a message on desktop versus mobile.

Another design pattern is removing a device from a message altogether. For example, you may want to have a QR code interaction only designed for mobile. At any time, to remove a device from a message, just switch to the device you want to keep. At that point, you will see a small red "X" next to every other device. Clicking on it will remove the device from the message, like so:

You will notice that the other two devices have a little "Plus" icon next to them. That represents the fact that the message is not defined in these devices yet. You can design that device again simply by clicking on them. If I do so, Botsociety will copy the content over to the new device, if possible:

Note that, since now the devices are detached, changing one device's content will not impact the others. The content is just copied over to get you started.

Device icons overview

To recap, this example shows all of the possible combinations:

• The user is editing the first device
• The message is defined in the second device
• The message is not defined in the third device

Once a message is defined on multiple devices, you will see a device switcher in the canvas:

You will also the device switcher in the Play and in the Video export. It will allow you to preview your design on multiple devices.

This simple approach allows you to create complex design patterns on different devices, as well as defining device-specific content into your design.

Changing the settings

By default, Botsociety will prompt the editing in Attached device mode. This is the most common scenario, but it may not fit your needs. To change this behavior, click on the Main menu and go to Settings > And then switch the Attached Devices option. Now your devices will be detached by default. This setting will only be applied to your current design file.

Paths

Paths are groups of messages. You can link directly to a path, you can move paths around, and you can download a video of your path. In general, you can think of paths as a way to organize your message.

Paths are not intents. You can organize them as you want, regardless of how your engineers will structure the intents of your bots. You can mark up intents later in the build mode.

You can also use paths to create conversational components that can be re-used by the rest of your team. Check out the component documentation here.

Create and edit a path

In the beginning, the conversation will have one path of messages. You can another path by clicking on the Main Menu and then selecting File > New path. You will then be able to place your path where you prefer on the canvas, like so:

You can also right-click anywhere in the canvas to open a contextual menu and create a path that way:

A path is composed of three main elements: the header, the body, and the final link icon:

To move a path, drag and drop anywhere in the path header.

To rename a path, double click on the path name or click on the pencil icon that is shown next to the path name once you hover it.

To create another path connected to the existing one, you can click on the path icon in path header.

To play the path, click on the play icon.

The three dots icon opens a residual menu that allows you to:

• Add animations if any. Animations are Lottie animations that can be attached to the preset to improve your preview.
• Download a video export of your path. Any outgoing connection from your path will be followed and exported as well
• Clone your path. The path that you are cloning is connected to other paths, these connected paths will not be cloned.
• Delete your path

The last icon allows you to collapse your path, hiding its messages:

Copy/paste paths

You can copy and paste paths, inside the same design, or across different design files. To copy a path, click on the path menu and select Copy:

Now you can right-click anywhere in your Canvas in any Botsociety file and choose Paste to paste your copied path:

Change Path Color

To change the path color, open the three dots menu in the menu header. Then choose the 'Change color' option. You can now select any color and it will be applied to the path's outline and header name.

Connections

Connections can be defined between messages, and between messages and paths. A message can have any amount of outgoing connections, and have any amount of incoming connections. A message may also have buttons. Each button can have one or multiple outgoing connections. You can also connect directly to a path. A path can have only one incoming connection. The upside of connecting a path is that you can change the messages inside the path without breaking the connection. Botsociety offers multiple ways of creating a connection right when you are adding a new message or a new path, in order to speed up your design.

Creating and editing connections

To enter the connection editing mode you can click on the link button at the end of any path. That button will allow you to connect that path to any message or to another path, like so:

If you want to create a connection starting from a message, click on the link icon in the message editor:

To edit an existing connection, just click on the connection arrow like so:

You can now click on the dots at either end of the arrow to edit the connection. You can also click on the "X" in the middle of the connection to delete it. If you change your mind while editing your connection, you can press Escape on your keyboard to undo it.

To edit the connections that stem from buttons, you can expand the buttons by clicking on the expansion arrow. After that, you will see the detail of each button connection.

Another way of editing any connection is clicking on the connection itself and then clicking on the connecting dots like so:

Creating a path connected to a message

To create a path that stems from a message, just edit the message and then click on the path icon. Now click anywhere to place your new path.

The newly created path will be connected to your initial message.

Creating a path connected to a path

To create a path that stems from a path, click on the path icon in the path header. Now click anywhere to place your new path.

Note that this works also for empty and newly created paths, allowing you to design all of your paths first, and then filling in the messages.

Creating paths connected to buttons

When you add a message that includes buttons, you will be prompted with the following panel. The panel allows you to quickly create the right path and message structure for you. You can of course edit your connections, paths, and messages later if you change your mind.

Let's unpack these options:

Create a path for each button

Botsociety will automatically create one path for every button. Once you click on this option, click anywhere to place your new paths.

When to use it This option is useful when you are designing separate and equally important experiences for every button. A good example may be a series of quick replies that prompt the user with different interaction patterns, like: "What would you like to do? 1. Open a bank account 2. Get a credit card"

Continue in the same path

Botsociety will not create any additional path, and will just connect each button to the following message in your path.

When to use it This option is useful when your interaction does not really change between buttons. For example, if your buttons are starting from a carousel of products, and the next step is going to be the customer's cart regardless of the product selected.

Happy and unhappy path

C. The first choice on your message will be added as a message on the current path you are designing. Any of the remaining choices will create new paths (after you drop them on the canvas) so you can design the experience for those separately. An example of this is portrayed below:

When to use it This option is useful when you have a happy and unhappy path type of interaction. For example, when you add a quick reply along the lines of Are you ready to proceed? 1. Yes 2. No I need more information

Linking between design files

You can also edit a connection in order to edit to another design file. To do so, edit a connection, and then click on an empty spot in the Canvas, like so: Then select 'Link to Another Design'. You will then be able to choose which design file you want to connect to. You can connect to any design file created in your drafts, or inside your team. You can only connect design files that use the same preset.

Once the linked design file is chosen, a new browser tab will open, containing the linked design file. You are then able to define where the incoming connection ends up in the linked file.

Note that the Play and Prototype mode will not jump between linked design files.

Customizing a connection's color

To customize the color of a connection, click on the connection itself and then click on the three dots menu:

Settings: Changing the bot/user pictures and more

In the design settings, you can change the bot and user settings, such as bot name, user name, and profile pictures (avatars). You can also change other settings that will apply to your design file. To access the settings, click on the main menu hamburger icon in the header, then clicking on Settings. Alternatively, you can click on the Gear icon on the bottom right corner to access the Settings directly:

There, you can add avatars, change the names, add more users/bots participating in the conversation, and choose voices (if in a voice design).

Then, while you are designing, you can choose the bot or user that is the sender of the message by clicking on the drop down at the top of the message editor.

Once you select a different bot or user from the default one, we save that choice so every message after is sent by that same sender. To change this, select the right bot or user from the drop down again.

Download your conversation

You can download your conversation file in different formats, in order to share or present your design.

PDF Download

You can download a PDF version of your design canvas as follows:

• Zoom and pan around your design until you visualize the portion of your design that you would like to export
• Click on the top right icon Download
• Select PDF
• Now you can adjust the size of your export. By default is A4 Letter Size, but you can select a different one
• In the Destination field, choose Save as PDF
• Click Save

If you want to save a PDF that shows the custom path colors, you will have to activate the option called Background graphics Before clicking Save

Video export

To export a video of your entire design file, click on the top right corner on the download icon and then choose 'Download video'

You can also download a specific path video by clicking on the three dots in a path header and then choosing "Download Video":

Once you do, you will be able to select the device that you would like the video export to be in. Once the right device is selected, click on "Start video Download". You will get your video download files in your email as soon as they are ready.

Video export background You can also change the video export background color. To do so, open the settings and then change the color called 'Export Background':

Notes

You can add free-floating notes on your canvas. These notes are helpful to help other users navigate your design, make notes, upload files and/or images. The notes will not show up in the Play or Build experience, and they will not impact your bot's logic and flows.

To add a note, you can right-click anywhere in the Canvas, and then select 'Add note', like so

Once a note is added, you can:

Resize the note. Just drag and drop on the note's border to make it bigger or smaller, like so:

Attach files to the note. To do that, just click on the attachment icon on the right while editing the note. If you upload an image, we will display the image on the canvas

Change note color You can change the background color of a note by clicking on the three dots icon on the top right corner of a note, and then choosing Change Color.

Multi-language designs

Botsociety allows you to design for multi-languages in the same design file. You will be able to select the language that you want to add to your design and visualize the conversations across different languages with the same context. To do this, you need to change your canvas to the Language mode and specify the languages that you want to work with and visualize in your canvas.

The multi-language feature is great if you are:

• Working on a project that is going to be launched in different countries with different languages
• With the need of having one single design file to work with different languages
• Looking to find a fast and more context-oriented way to translate the conversations or localize contents of an entire design file

This also works for the export features, but you need to select the language you would like to export. We will cover everything you need to know to use this feature.

Some other tools in the market do not offer this feature. To be able to design for multiple languages in the same design file, you will need to be switching between languages.

The language mode

By default, Botsociety will assume your designs are in English-US. So, if you are planning to write conversations for another language, you would need to set this up in the language panel. To switch to the language mode, you just need to click on the Language Icon on the left bottom corner of the side panel.

In the language panel, you will be able to add, remove and change the language of your designs. Botsociety will not translate or override any of your conversations to a different language, and you need to set this up correctly to work as you expect. This must be done by a person who will be in charge of translating or writing the localizations of your conversations.

Once you open the language mode, you will notice the language settings in the panel:

• Enabled Languages
• Displayed Language
• Translate from language
• Advanced

We will cover those with more details below.

Enabled Languages

These are the languages you would like to work in your design. By default, English (US) will be selected for any new design file. To enable a new language, you just need to

1. Open the Language mode
2. Click on the Enable Languages button
3. Select as many languages you would like to design

Botsociety offers most languages you would find on Google Translate, but make sure you are using the right country for the idiom you select; For example, English-US or English-UK.

Note: if you are planning to work in another language first, we suggest you do this configuration before you start your design. Otherwise, you can still change this in the advanced settings by replacing one language with another.

Displayed Language

Change this option if you like to change the language of your entire design file. If you are working on a project with multiple languages, Botsociety will enable you to edit one language at once while having a reference from another language that you can set up on your design. Once you select the language you would like to translate, Botsociety will automatically add a red pop up on top of every message that is missing a translation to indicate that the message needs a translation.

Translate from language

The "translate from language" settings will change the main language of your design file. To change this setting, you just need to:

1. Open the Language mode
2. Click on the "Translate from language" button
3. Select the main language of your design

After this, whenever you are translating a conversation to another language, Botsociety will suggest a translated version on the right side of that same conversation based on your choice.

The suggestion pop-up on the right is based on the language you select in this setting. Note that you can also check and translate the utterances as well and you can also see the language for that suggestion on the top left of the pop-up.

Translating the conversations

If you are going to translate or write a localization version of any conversation using Botsociety, you will be able to do this in one single file. To do that, you just need to change the displayed language of your design file and find the flagged messages that need translations. Botsociety will always add a translated version of the same message on the right side; the content of this translated version is based on the settings of "Translate from language".

To translate a message, you just need to click on the red pop up and translate the content with the same message editor you would use in any other design on Botsociety.

Note: This also applies to the utterances of these messages, so you are able to translate those too in the same context as well. If you would like to export those to use in an NLU Engine, such as Rasa or another similar, make sure you select the right language in the Displayed Language, Botsociety will assume this if your preference for the exported.

To give an idea about an ideal workflow for feature, let's say you are designing conversations in English-US and you need your project to be translated to Portuguese-BR.

A good workflow for this would be:

1. Open the Language mode on the bottom of the left side panel
2. On the new panel, on the very first option, add a new language to your design file (Portuguese-BR)
3. Then, change the displayed language to Brazilian Portuguese
4. Make sure you select English-US in the "Translate from Language" option

And now you will be able to work on the Portuguese version of your design file. If you need to do the opposite, meaning start your project in Portuguese and then translating it to English, you have two options:

• If you didn't start your project, make sure you change the language of your design to Portuguese before you start to work;
• If you already started your project, you just need to go back to the Language mode and then, under the Advanced tab, Replace the language you would like to see it (in the example we presented in this document, you would just click in the "Replace pt-BR with en-US" button

Keyboard Shortcuts

You can improve your workflow using keyboard shortcuts. Would like some more? Tell us in the forum!

	Mac	Windows & Linux
Zoom in and out	⌘ Scroll Wheel	Ctrl Scroll Wheel
Reset zoom	⌘ 0	Ctrl 0
Move around	Space bar Drag and Drop	Space bar Drag and Drop
Add Message	⌘ Enter	Ctrl Enter
Change Message Side	⌘ . or Ctrl .	Ctrl Alt .
Add Path	⌘ p	Ctrl p
Add Utterance	⌘ ]	Ctrl ]
Next Utterance	⌘ Option ]	Ctrl Alt ]
Previous Utterance	⌘ Option [	Ctrl Alt [
Import Utterances from CSV	⌘ Option i	Ctrl Alt i
Play Message	⌘ d	Ctrl d
Video Preview	⌘ Option p	Ctrl Alt p
Edit mode	⌘ e	Ctrl e
Build mode	⌘ b	Ctrl b
Comment mode	⌘ Option o	Ctrl Alt o
Revision History	⌘ Option r	Ctrl Alt r
Design Settings	⌘ Option s	Ctrl Alt s