Userlike Bot Language

javascript
-- # document start
config: # A key with the name 'config', containing configuration information for your script
abort: # A map with the key 'abort', this contains a map with a list of keywords that will immediately stop the conversation flow
keywords: - stop skip: # A map with the key 'skip', this contains a map with a list of keywords that will skip optional inputs
keywords: - skip

# ^^^^ All your scripts should start with the block above

0: # Each conversation step has a unique key that is used to identify it. The first step MUST be an integer with the value 0

messages: # This is a node of the type 'message' - "Hello!" # The contents of the 'message' node is a sequence (list/array) of messages your want the bot to send - "I am a bot!"

action: # An action is required in order to move to the next step

next: 1 # In this case, it's a key-value pair pointing to the next step with the key 1

1: # You MUST use integers to identify your steps
input: # This is a node of the type 'input'. It's a map with key-value pairs determining its content and behavior
message: "What is your name?"
type: text
optional: false
when:
valid:
messages: - "Thank you!"
action:
next: 2

2: messages: - "That's all for now!"
action:
end: true # Call the 'end' action when your conversation flow has reached the end to signal that the conversation should not go on

javascript
--
config:
abort: # Define the keyword(s) that should immediately stop the conversation keywords: - stop # If the contact uses the word "stop" during any input step, the conversation is immediately forwarded
action: # Defines the action to perform when the abort keyword is encountered. In this case the conversation is immediately forwarded
forward_any: true

skip: # Define the keyword(s) that should skip optional input steps
keywords:
- skip

# [...the rest of your bot flow]

• Service time: The bot is online only outside of the services times defined in the Widget.

• Backup: The bot is always online, but only takes conversations when no human operators are available for live conversations.

• Human: The bot is always online and takes chats like any other operator.

• Firewall: The bot is always online and receives all incoming conversations (eg. to pre-categorize and forward them)

• End conversation and move it to All conversations

• Unassign conversation and move it to the Inbox, where any operator in your group can see and answer it.

• Forward conversation to an available human operator from the same group.

javascript
# Message node with a single message
1:  # Conversation step
  messages:  # Node type
    - "Single message"  # A sequence with a single message
  action:  # Next action
    next: 2

# Message node with a multiple messages
1:  # Conversation step
  messages:  # Node type
    - "First message"  # Each message in this sequence will be sent to the contact separately
    - "Second message"
  action:  # Next action
    next: 2

# Message node with a multiple messages and links
1:  # Conversation step
  messages:  # Node type
    - "Visit https://www.userlike.com !"  # Each message in this sequence will be sent to the contact separately
    - "https://www.example.com"
  action:  # Next action
    next: 2

# Assuming the contact provided his name and email, you can use this information in a message by expanding the name and email variables
1:
  messages:
    - "Welcome to the chat, {{name}}!"
    - "Your email address is {{email}}"
  action:
    next: 2

javascript
# Media node with a single item
1:  # Conversation step
  messages:
    - "A picture"
  media:  # Node type
    - option:
      link: "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
      mime_type: "image/jpeg"
  action:  # Next action
    next: 2

# Media node with a multiple items
1:  # Conversation step
  media:  # Node type
    - option:
      link: "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
      mime_type: "image/jpeg"
    - option:
      link: "https://d3upe020n1uosc.cloudfront.net/static/web/videos/screencast-fullhd.mp4"
      mime_type: video/mp4
  action:  # Next action
    next: 2

javascript
# Button node with a single button
1:  # Conversation step
  buttons:  # Node type
    - label: "Send email to {{name}}"
      link: "mailto:{{email}}@userlike.com"
  action:  # Next action
    next: 2

# Button node with multiple buttons
1:  # Conversation step
  messages:
    - "We’re happy to help you!"
  buttons:  # Node type
    - label: "Email"
      link: "mailto:support@userlike.com"
    - label: "Website"
      link: "https://www.userlike.com"
    - label: "Phone"
      link: "tel:+4922163060570"
    - label: "Whatsapp"
      link: "https://api.whatsapp.com/send?phone=4915735998856"
  action:  # Next action
    next: 2

javascript
# Asking for information (mandatory)
1:
  input:
    message: "What's your name?"
    type: text
    key: name
    optional: false
    when:
      valid:  # In case the input is valid proceed to the next node
        messages:
          - "Thank you!"
        action:
          next: 2
      exists:  # If the 'name' variable already exists on the contact, we don't need to ask for it and can skip to the next step
        where: contact
        action:
          next: 2

# Asking for information (optional)
1:
  input:
    message: "What's your name?"
    type: text
    key: name
    optional: true
    when:
      valid:
        messages:
          - "Thank you!"
        action:
          next: 2
      skip:  # When the input is optional and the skip keyword is provided, the action defined under "skip" is performed.
        action:
          next: 3

javascript
# Checking if contact name exists
1:
  input:
    message: "What's your name?"
    type: text
    key: name
    optional: false
    when:
      # [...other parameters such as 'valid']
      exists:  # Checks if the key 'name' already contains data
        where: contact  # where to check for the existence of 'name'
        messages:  # We can use the variable in a message node
          - "Welcome back, {{name}}!"
        action:  # What to do next, eg. skip gathering further contact info
          next: 6

javascript
1:
  input:
    message: "What's your email address?"
    type: email
    key: email
    optional: true
    when:
      not-valid:
        messages:
          - "The email format is not valid"
          - "Let's try again..."
        action:
          next: 1
      valid:
        action:
          next: 2
      skip:
        action:
          next: 3
      exists:
        where: contact
        action:
          next: 2

javascript
# Input optional
1:
  input:
    message: "What's your tracking ID?"
    type: regex
    format: "[0-9]{6}-[0-9]{2}"
    key: tracking_id
    optional: true
    when:
      not-valid:
        messages:
          - "The format is not valid, please use 123456-12"
          - "Let's try again..."
        action:
          next: 1
      valid:
        messages:
          - "Thank you."
        action:
          next: 2
      skip:
        action:
          next: 2

# Phone number required
2:
  input:
    message: "What's your phone number?"
    type: regex
    format: "\\+49[0-9]{3,5}[0-9]{7,10}"
    key: phone_number
    optional: false
    when:
      not-valid:
        messages:
          - "The format is not valid, please use +4917212345678"
          - "Let's try again."
        action:
          next: 2
      valid:
        action:
          next: 3

javascript
0:
  input:
    message: "Select an option"
    type: bubbles
    fallback: "Please enter a number"
    any_message:
      messages:
        - "That's not right, try again."
      action:
        next: 0
    options:
      - option: "Option One"
        action:
          next: 1
      - option: "Option Two"
        action:
          next: 2

javascript
0:
  input:
    message: "Which car are you interested in?"
    type: carousel
    fallback: "Please enter a number"
    any_message:
      messages:
        - "Enter a number"
      action:
        next: 0
    options:
      - option:
        media: "https://url-to-picture..."  # Provide the URL to the media you want to link, such as a .png file
        headline: "Truck"  # The headline or title of the item
        subheadline: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras ultricies blandit magna, nec convallis leo eleifend quis."  # The description of your item
        action:  # What should happen when the user clicks on this item
          next: 1
      - option:
        media: "https://..."
        headline: "SUV"
        subheadline: "Lorem ipsum..."
        action:
          next: 2

javascript
0:
  input:
    message: "This is a list template. Please select something"
    type: list_template
    key: select
    fallback: "Please enter a number"
    header: "Header"
    list_header: "List header"
    footer: "Footer"
    button_text: "Click"
    any_message:
      messages:
        - "That's not right, try again."
      action:
        next: 0
    options:
      - option:
        label: "Option One"
        description: "first option"
        action:
          next: 1
      - option:
        label: "Option Two"
        description: "second option"
        action:
          next: 2
      - option:
        label: "Option Three"
        description: "third option"
        action:
          next: 3
      - option:
        label: "Option Four"
        description: "fourth option"
        action:
          next: 4

javascript
0:
  input:
    message: "This is a button template"
    type: button_template
    key: select
    fallback: "Please enter a number"
    header_type: "text"
    header_text: "Header"
    footer: "footer"
    body: "body"
    any_message:
      messages:
        - "That's not right, try again."
      action:
        next: 0
    options:
      - option:
        label: "Option One"
        action:
          next: 1
      - option:
        label: "Option Two"
        action:
          next: 2

javascript
# Making a GET request and handling the resulting JSON response

1:
  input:
    message: "Looking it up!"
    api:
      request:
        url: "https://mydomain/api/users/5"  # The URL that should be called
        method: "get"  # The method to use
        data:
          values: {}
      response:  # Define a variable the reponse is saved to
        key: result
      when:
        failure:  # Define what should happen when the request is not successful
          messages:
            - "Something went wrong"
          action:
            next: 0
        success:
          messages:
            - "{{#result}}Your name is {{name}}, you work for {{#company}}{{name}}{{/company}} and your number is {{phone}}{{/result}}."
          action:
            next: 2

# Assuming the request we are making in the above example returns the following JSON object:
{
  "id": 7,
  "name": "Kurtis Weissnat",
  "username": "Elwyn.Skiles",
  "email": "Telly.Hoeger@billy.biz",
  "address": {
    "street": "Rex Trail",
    "suite": "Suite 280",
    "city": "Howemouth",
    "zipcode": "58804-1099",
    "geo": {
      "lat": "24.8918",
      "lng": "21.8984"
    }
  },
  "phone": "210.067.6132",
  "website": "elvis.io",
  "company": {
    "name": "Johns Group",
    "catchPhrase": "Configurable multimedia task-force",
    "bs": "generate enterprise e-tailers"
  }

# After a successful request the message output would look like this: "Your name is Kurtis Weissnat, you work for Johns Group and your number is 210.067.6132."

javascript
1:
  input:
    message: "Sending data"
    api:
      request:
        url: "https://your-url/endpoint"
        method: "post"
        headers:  # Define the headers of the request as key-value pairs
          User-Agent: 'Userlike Bot'
          Authorization: 'xxx-xxx-xxx-xxx'
        data:  # Data is the request body of the POST request
          values:  # Provide key-value pairs of data you want to send in the request body
              job: "Engineer"
              visits: 25
          context:  # Include data from the session context by providing the key you've saved it to
            - tracking_id
      response:
        key: result
      when:
        failure:
          messages:
            - "Something went wrong"
          action:
            next: 0
        success:
          messages:
            - "Thank you for your submission."
          action:
            next: 2

javascript
# Setting and clearing contact name:
0:
  messages:
    - "I need some information."
  input:
    message: "What's your name?"
    type: text
    key: name
    optional: false
    when:
      valid:
        action:
          contact:  # If the input is valid, save the name to the contact
            set_name: "{{name}}"
          next: 1
      exists:
        where: contact
        action:
          next: 1

1:
  input:
    message: "Is the name {{name}} correct?"
    type: bubbles
    key: select
    fallback: "Please enter a number"
    any_message:
      action:
        next: 1
    options:
      - option: "Yes"
        action:
          next: 2
      - option: "No"
        action:
          contact:  # Clear the contact name and ask again
            clear_name: True
          next: 1

2:
  messages:
    - "Nice to meet you, {{name}}"
  action:
    end: true


# Forwarding to operators
0:
  input:
    message: "How may I help?"
    type: bubbles
    key: select
    fallback: "Please enter a number"
    any_message:
      action:
        next: 0
    options:
      - option: "I have a technical issue"
        messages:
          - "I see, let me forward you to our Technical Support department"
        action:
          forward_group: "Technical Support Group"
      - option: "I have questions about your pricing"
        messages:
          - "I'll forward your inquiry to our Sales team"
        action:
          forward_group: "Sales Group"
      - option: "I just want to speak to an agent"
        messages:
          - "I'll forward you to the next available operator"
        action:
          forward_any: true
      - option: "I have no further questions"
        messages:
          - "Have a nice day!"
        action:
          end: true

# Forwarding to operators with fallback
0:
  input:
    message: "How may I help?"
    type: bubbles
    key: select
    fallback: "Please enter a number"
    any_message:
      action:
        next: 0
    options:
      - option: "I have a technical issue"
        messages:
          - "I see, let me forward you to our Technical Support department"
        action:
          forward_group: "Technical Support Group"
          fallback:
            messages:
              - "Nope, its not possible"
            action:
              next: 0
      - option: "I have no further questions"
        messages:
          - "Have a nice day!"
        action:
          end: true

# Using the navigate command:
0:
  messages:
    - "Navigating"
  action:
    navigate: "https://www.userlike.com"
    fallback: "Click here {{link}}"
    text: "Go to Userlike.com"


# Using fallback in contact update
0:
  input:
    message: "Whats your mobile number?"
    type: regex
    format: "\\+49[0-9]{3,5}[0-9]{7,10}"
    key: mobile_number
    optional: false
    when:
      not-valid:
        messages:
          - "The format is not valid, please use +4917212345678"
          - "Let's try again.."
        action:
          next: 0
      valid:
        action:
          contact:
            set_mobile_number: "{{mobile_number}}"
          fallback:
            messages:
              - "Nope, its not possible"
            action:
              next: 0
          next: 1
      exists:
        where: contact
        action:
          next: 1

1:
  input:
    message: "Is the mobile {{mobile_number}} correct?"
    type: bubbles
    key: select
    fallback: "Please enter a number"
    any_message:
      action:
        next: 1 
    options:
      - option: "Yes"
        action:
          next: 2
      - option: "No"
        action:
          contact:
            clear_mobile_number: True
          next: 0

# Creating a note for a contact
0:
  input:
    message: "To process your request, I need the order number."
    type: text
    key: order_number
    optional: false
    when:
      valid:
        action:
          contact: # Create a note within the contact’s context
            note_create: "Contact was unsatisfied with items ordered in {{order_number}}."
          next: 1
      exists:
        where: contact
        action:
          next: 1

# Creating a note for the current conversation
0:
  input:
    message: "To process your request, I need the order number."
    type: text
    key: order_number
    optional: false
    when:
      valid:
        action:
          conversation: # Create a note within the conversation’s context
            note_create: "Customer requested a refund for the order {{order_number}}."
          next: 1
      exists:
        where: contact
        action:
          next: 1

javascript
config:
abort:
keywords:
- stop
skip:
keywords:
- skip
0:
messages:
- "Welcome to our chat!"
- "I'm happy to assist you."
action:
next: 1

javascript
1:
messages:
- "I need some information about you first."
input:
message: "What's your name?"
type: text
key: name
optional: false
when:
valid:
action:
contact:
set_name: "{{name}}"
next: 2
exists:
where: contact
action:
next: 2

javascript
2:
input:
message: "Is the name {{name}} correct?"
type: bubbles
key: select
fallback: "Please enter a number"
any_message:
action:
next: 2
options:
- option: "Yes"
action:
next: 3
- option: "No"
action:
contact:
clear_name: True
next: 1

javascript
3:
messages:
- "Nice to meet you, {{name}}"
action:
next: 4

javascript
4:
input:
message: "What's your email address?"
type: email
key: email
optional: true
when:
not-valid:
messages:
- "This doesn't seem to be a valid email address."
- "Let's try again!"
action:
next: 4
valid:
action:
contact:
set_email: "{{email}}"
next: 5
skip:
action:
next: 6
exists:
where: contact
action:
next: 5

javascript
5:
input:
message: "Is the email {{email}} correct?"
type: bubbles
key: select
fallback: "Please enter a number"
any_message:
action:
next: 5
options:
- option: "Yes"
action:
next: 6
- option: "No"
action:
contact:
clear_email: True
next: 4
6:
input:
message: "Hello {{name}}! How may I help?"
type: bubbles
key: select
fallback: "Please enter a number"
any_message:
action:
next: 6
options:
- option: "I have questions about your product."
messages:
- "I'll forward you to our Sales department."
- "They will happily answer any questions you might have!"
action:
forward_group: "Sales"
- option: "I have questions about the integration on my website."
action:
next: 7
- option: "I have no further questions"
messages:
- "Have a nice day"
action:
end: true

javascript
7:
input:
message: "Which website integration are you interested in?"
type: carousel
key: select
fallback: "Please enter a number"
any_message:
action:
next: 7
options:
- option:
media: "https://d3upe020n1uosc.cloudfront.net/static/web/images/tutorial_logo_shopware.png"
headline: "Shopware"
subheadline: "Shopware is the ideal solution for meeting the changing demands of ecommerce, giving you the freedom to quickly and easily leverage your growth potential"
action:
navigate: "https://www.userlike.com/en/public/tutorial/um/website/shopware"
fallback: "Click here {{link}}"
text: "Go to the Shopware integration"
next: 8
- option:
media: "https://d3upe020n1uosc.cloudfront.net/static/web/images/tutorial_logo_squarespace.png"
headline: "Squarespace"
subheadline: "Create a website with an award-winning template. Get your unique domain today. No Plugins Necessary."
action:
navigate: "https://www.userlike.com/en/public/tutorial/um/website/squarespace"
fallback: "Click here {{link}}"
text: "Go to the Squarespace integration"
next: 8
- option:
media: "https://d3upe020n1uosc.cloudfront.net/static/web/images/tutorial_logo_plain_website.png"
headline: "HTML"
subheadline: "Paste the code into the bottom of your website"
action:
navigate: "https://www.userlike.com/en/public/tutorial/um/website/plain"
fallback: "Click here {{link}}"
text: "Go the the HTML website integration"
next: 8
- option:
headline: "None of these"
subheadline: "Go back to the previous step"
media: "https://d3upe020n1uosc.cloudfront.net/static/web/svg/icon_support_help.svg"
action:
next: 6

javascript
8:
input:
message: "Did this answer your question?"
type: bubbles
key: select
fallback: "Please enter a number"
any_message:
action:
next: 8
options:
- option: "Yes"
action:
next: 9
- option: "No"
action:
next: 6

javascript
9:
messages:
- "Glad I could help!"
- "Have a great day!"
action:
end: true