Design a Conversation

The Design 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 never ending. The more paths you add, the more the design canvas expands. Zoom in and out to see how this goes - you can use the buttons on the left panel or click Command + Scroll up/down. You can navigate the canvas by holding the Space bar and dragging and dropping.

In the design canvas, you will also be able to see the Build Mode and comments, by clicking on the icons in the left sidebar. The design canvas facilitates everything related to your design in Botsociety.

Paths

Conversations can usually follow multiple Paths. Botsociety gives you the ability to model this natural behavior by designing different conversational Paths.

Paths are a way to visualize and organize parts of the conversation ensign you are building. You can use paths according to the conversational model you are following, such as Happy Path with Repair Path, etc.

At the beginning, the conversation will have one single Path of messages. You can however branch the conversation into a new Path at any point by clicking on “Create Path” on the path header or message editor. You will learn how to connect paths in the Connections section.

Messages

Message Editor

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.

In voice devices, 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 “Add Message type” drop down.

Multimodal Experience

Botsociety allows you to design for multiple devices at the same time. This is what we call the multi modal experience. When designing for multi modal experiences, you can add new devices and see them when you’re previewing the interaction.

Adding a new device

To add a new device, click on the other devices shown on the top left of the message editor.

The content from device 1 is autofilled on device 2 and so on, as long as they have the same message type. That means that SSML will be autofilled in a voice platform, and text might be autofilled in devices that have a screen and a text message type.

Removing a device

After adding a device, you will be able to see a small red circle with an X on it. To delete a device, simply click on that red icon, and the device will disappear.

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 on the last button in the header .

Adding other message types

Suggestions

Suggestions, also known as quick replies, buttons, or choices, are a common message type in chatbots and assistants. They give the user a clear way of proceeding, thus also making it easier for the designer to design the conversation.

You can add Suggestions to any message by clicking on "Add message type" drop down or “Add Suggestions” in the message editor.

Depending on the preset, suggestions might be called chips, choices, quick replies, buttons.

Adding any of the message types above will automatically create paths representing the section of the conversation developed if the user selects that choice.

Editing a message

To edit a message, click on the message and the editor should open. After making your edit, please Save the message or click Cmd (Ctrl) + Enter to save.

When editing a message, it is possible to link that message to another path or message in the design. That is not available when you are initially adding the message.

Play

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 add the suggestions as ways that the user can express the suggestion (think on a voice device). As stated, this will be training data when exported, if you mark up all the utterances as variables.

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.

Changing the bot/user settings

The bot and user settings can be controlled by going to the main menu in the header, then clicking on Settings.

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.

Connections

Child paths

Child paths are created when you create a path that is linked to a “parent” path. A parent path is the main path that a child path stems from.

Child paths can be created by adding Suggestion chips, which create their own child paths automatically to signify the user choosing that suggestion chip, or added by clicking on a path header or message.

Linking paths

You can also link paths or messages with a connection. Linking paths creates the hierarchy that was described in the parent paths and child paths, so one message can lead to another. To link paths, click on on the message editor or at the bottom of a path.

This will add a connection between the messages, and during play, you will be able to see the transition from one message to another.

Design settings

User and bot settings

The bot and user settings can be controlled by going to the main menu in the header, then clicking on Settings. Here you can change the bot name, profile picture (also known as avatar), as well as other settings that are applied to your design file.

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

Note: Our download features are currently in development. Sign up to stay updated with our progress. 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
• In your browser main menu, click File > Print
• 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

Video export

Coming soon.

Presets

A preset defines how your conversation design looks and behaves. It defines for example if your conversation has voice or chat components or both; if your conversation spans across multiple devices; and how it looks. Botsociety provides some presets for you to use called Official presets. You can also create your own presets and share them with your team.

Official Presets

The Botsociety team plans to keep additing official presets to this list. If you have a request, please post it on our forum.

• Google Assistant
• Alexa
• Messenger
• WhatsApp
• SMS
• IVR
• Generic Chat and Voice

Legacy Presets (Formerly Supported Platforms)

• Your Own App/Webite
• Facebook Messenger
• Facebook Messenger Extensions
• Slack
• Google Assistant
• Alexa
• Twitter
• Whatsapp
• Google Hangouts
• Apple Business Chat
• RCS Messaging
• SMS/MMS

Starting from scratch - Creating your own preset

Creating the Background Image

To create a preset that looks like the platform you want to design for, you will need certain assets before you begin.

The most important one is the background image, which should be the UI of your chatbot without any messages on it. You can use our design guide and copy the device frame you want to use.

When designing the background, you can add the name and avatar of the bot, or leave that off, since you’ll have a chance to format those with CSS in the Conversation > Appearance CSS.

Start creating your preset

1. Start by making a design and selecting 'start from scratch' instead of choosing a pre-saved preset.
2. Name your Preset, and add a preset icon under the conversation section.
3. Now, it’s time to define your device.
   1. Add a device, name it, and choose your icon (or change these settings from the default device that we show you).
   2. Next, answer a couple of simple questions about the device you are designing for.
      1. Does the device have a screen?
      2. Does the device support voice?
      3. Are message bubbles shown/visible in the device? For example, a voice device with no screen is not screen enabled, has voice, and does not have visible message bubbles.
      4. Choices (quick replies/buttons) in that device would be played by voice, since there’s no screen to touch. So, according to your device specifications, answer the “choices played by” question as well.
   3. Upload a PNG or SVG of your chat background (including the device frame), then adjust the dimensions accordingly so you see the whole screen on the right. Use our Preset Assets Guide on Figma to guide you.
      • Check the Figma above for the screen borders dimentions, and feel free to adjust accordingly according to your device dimensions.
      • You’ll see that the screen size refers to the area where the messages can go, outlined in red, so make sure that it only covers the part where you later want to see your message bubbles (not including the header, footer, device frame).
   4. Using the screen borders width, you can account for the device frame and potential headers and footers, so use the up/down toggles to achieve the result you want.
      • Tip: To keep the same size for the device but set the screen borders, subtract the left and right screen borders from the width, and the top and bottom from the height.
4. After you have defined the area where the messages go, save the device settings, and you can start to add message types. As you can see, the first message type is already added, but you can change that to fit your needs.
5. In the message type settings box, name the message type, and define for which devices it’s going to be active for.
   1. Clicking on Required makes the message type required for every message in that device, while clicking optional will allow you to choose between this and other message types according to your needs. We find that Optional is the more common option since it gives you more flexibility when designing!
   2. You can also decide who gets to use this message - bots only, users only, or both sides. For a message type like carousel, usually only the bot can send them, so in that case you would switch to Bots only.
6. Now, on to the composition of the message type. Every message type is made of components, which can be text, image, chips (quick replies/buttons), and more to come. Add the components for the message type in the order that you want them to be arranged.
   1. For example, if I want to make a carousel with an image, title, subtitle, and buttons, I should add the following:
      • Image
      • Text
      • Text
      • Chips
   2. Depending on if the said component is required or optional in the message type, select that in the drop down.
   3. In the Placeholder section, you can name the component according to the function is has. For example, title or subtitle.
7. Note that now you can format all the components with CSS, but before we do that, we want to group the components together in a message bubble. Click on + Message Bubble if you’d like these components to all be grouped together in a message bubble. Then, assign Message Bubble 1 to all the components in that message type.
8. Turn the Make Carousel switch to on, click Save, and here you have an unstyled carousel message type.
9. To style the carousel, you can use the CSS dialog boxes. You will notice that every component has its own CSS settings, as well as the message bubble. This allows you to have complete control over individual components, the message bubble(s), and their appearance in the message!
   • When you open a CSS dialog box, you can see that the default view is CSS for All Devices, and for Default (During Play, Before Play, After Play). If there is different styling for the devices, you can scroll and define the CSS specific to the device.
   • In the CSS dialog boxes, you’ll see that you can add code for the bot’s side, user’s side, and both sides. Use both sides if the styling of the component or the bubble is the same, and separate if there are differences, such as message bubble color, etc.
   • Once you define the CSS and click save, you’ll be able to see a preview made from your code for Both sides next to the message type. To see the CSS styling for the separate sides, go to the Design page and add messages from the bot and the user.
10. The dialog box has one more capability we have not explored yet - the Before/During/After Play settings. You can find this under the Default view in the CSS dialog boxes. In those fields, you have the power to add different CSS for different phases of the message being played.
    • If you want something in the message to change during the time it is shown in the Play mode, simply define that CSS here and you’ll be able to see it. Some common examples include the message bubble changing sizes or colors, the text changing colors, etc.
    • You can add that or leave it empty, and press Save.
11. With that, we’ve constructed our Carousel message type. Now, repeat that process for as many message types as you’d like to add.
12. Besides the CSS animations you can add in the Before/During/After Play, after scrolling past the message types, you will find the Animations Settings menus.
    • You should see one animation settings box for paths, and one for each message type you’ve defined.
      • “What are paths?,” you may be wondering. Paths are different parts of the conversation, which can be linked together to make a conversation. If you switch to the Design page by clicking on the pencil icon in the left vertical bar, you will see that there is one path currently.
        • Sometimes, there are transitions in the conversation that happen between paths, and those some of the transitions come with animations.
        • In the path animations box, you can attach animations in a json format to be played before a path or after a path.
      • Making an animation default will cause it to be selected by default in the header of every new path created in the design. You can unselect default animations.
    • If adding animations, note that both for paths and message types, you can add different animations for the different devices you have defined further up in the Settings.
    • If you added path animation types, click Save and continue.
13. Adding animations for all your message types is similar:
    1. click on + Add Animation,
    2. name the Animation,
    3. upload a Before/during/after play message animation (you can have one in each field),
    4. decide whether you want to make that the default animation, and click Save or repeat these steps for your other devices if needed.
14. Repeat those steps to add animations to the desired paths and message types, and once this is complete, you are ready to design.
15. If there are any more styling choices you want to add via CSS - find the list of snippets below - you can do that by adding Appearance CSS under the Conversation section, which is between 'Save and Load' and 'Devices'.
    • This CSS only affects and can be seen in the Play mode, and includes details like showing and styling avatars, user/bot names, changing the orientation of components inside a message bubble, defining an imported font, etc.
    • In this field, you can also style Stemmed messages from choices, which are the message that gets sent after a user clicks on a choice/button. Read more on that below.
    • We recommend to use the Appearance CSS after you design a path or two and check the design preview on Play.

You should have everything in the preset defined now, so start designing! If there are changes you need to make while designing, you can go back to the Settings and make them, just remember to click Save in the box and on the preset.

Changing the message type components after it is being used may cause some issues, so delete the messages added or add a new message type to avoid that.

Appearance CSS

Appearance CSS is a section of the preset settings which allows for close to complete customization of your preset. In this section, using classes which will modify elements in the design like messages, avatars, names, and more, you will be able to create the final experience that you want your customers to have.

You can use appearance CSS for two main purposes:

1. A user would like to apply something to all of the messages (example: a font) without having to repeat it in all of the message types or devices, or
2. A user would like to act on a particular class of a particular case, as documented below

To make it easier for you, we will pre-populate the most common CSS code for a chatbot in every design that is started from scratch.

Most of the time, global CSS only affects what is shown on Play and it overrides any other CSS in the settings.

To change your preset's Appearance CSS, click on the following button.

You should see a pop-up window like the one below:

Global CSS classes

In addition, you can find the CSS classes which can be manipulated below:

• x-device: the device

• x-with-screen: devices with a screen

• x-without-screen: - devices without a screen

• x-device-content: the “screen” of the device

• x-message-list: contains the list of messages (the history and the currently playing)

• x-message: the message, contains all message types and lottie animations

• x-playing: the message currently playing

• x-pre / x-during / x-post: the current animation state of the message

• x-played: a message that has been already played (all of these is the history)

• x-bot / x-user: the “sender” of the message

• x-solo: if it’s the only message in the block

• x-first: if it’s the first of the block

• x-middle: if it’s a middle message of the block

• x-last: if it’s the last of the block

• x-has-ssml: if it’s message has an ssml message type

• x-has-text: if it’s message contains at least a text component

• x-has-image: if it’s message contains at least a image component

• x-has-chips: if it’s message contains at least a chips component

• x-has-carousel: if the message has at least one message type with the flag “Carousel” on

• x-has-message-type-{name}: {name} is the name of the message type defined by the user (spaces will be replaced by -, eg: "My custom carousel" becomes my-custom-carousel )

• x-message-container this contains the x-avatar, the list of all the x-message-type and x-sender-name

• x-avatar the avatar only (needed to style the size of the avatar)

• x-message-type: the container of a single message type

• x-message-type-{name}: a message type; {name} is the name of the message type defined by the user (spaces will be replaced by -

• x-message-items-container: the container of one of more x-message-items

• x-message-item: a single message item. If there is the Carousel flag on, there could be many items per message type

• x-message-animation: the lottie animation container

• x-message-bubble: the message bubble of a message (useful for the grouping border radius)

• x-stemmed-message-bubble: the bubble for the user message created by the selection of a choice

• x-stemmed-message-text: the text for the user message created by the selection of a choice

• x-path-animation: the container of the path Lottie animation
• x-pre/x-post: the current animation state of the path (we only have x-pre right now)
• x-playing: the currently playing path animation
• x-played: a path animation that has been already played

CSS Behaviors

Making the chat content scroll

  overflow-y: auto !important;
  display: flex !important;
  justify-content: flex-end;
  flex-direction: column;
}

Hiding Scrollbars

.x-device-content {
  scrollbar-width: none; /* Firefox */
}
.x-device-content::-webkit-scrollbar {
  display: none; /* Safari and Chrome */
}

Message pre-animation

.x-message.x-playing.x-pre {
  animation: slide-up-fade-in ease 500ms;
  animation-iteration-count: 1;
}
/* Animations */
@keyframes slide-up-fade-in {
  0% {
    opacity: 0;
    transform:  translate(0px, 40px);
  }
  100% {
    opacity: 1;
    transform:  translate(0px,0px);
  }
}

Feel free to add them to your Appearance CSS section and get in touch with us if you encounter any issues.

Team presets

Saving a preset for your team

When creating a preset, you can share it with your team by selecting "Team” in the "Preset visible by" drop down menu.

You should see something like this:

For your team members to use this preset, all they have to do is create a design in the team space and either:

1. Choose the preset under "Team Presets," or
2. Make a design from scratch, then go to the preset settings on the bottom left, and click on Open under "Load Existing Settings." Then, they can select the team preset, like shown below:

Changing a team preset

Anyone on the team who has edit access can edit a team preset. However, please keep in mind that the team preset is changed, so any changes that will be made will be reflected in all the designs that use that preset.

If you want to make a change but don’t want to change the preset for all your team members, you can make a copy of the preset by clicking and continue editing this preset copy.

If you are deleting a message type that is already used in another design, we will make a copy of that preset to avoid breaking the team designs. Then, you can save that preset as a team preset if you’d like to move forward with that preset instead of the original one.