STEP

An object containing information defining a step in a chat flow

Common Attributes

Strings are encoded using 4-Byte UTF-8 Unicode Encoding.

Every type of step must include the following attributes:

group

REQUIRED - String
Validation: Value is one of the pre-defined enumerated values

Each type of step has a pre-defined group value that must be included in the step definition. Group values are described below for each type of step.

id

REQUIRED - String
Validation: Value is a unique identifier within the chat flow

The step identifier DOES NOT have to be universally unique, ONLY unique within the chat flow itself. For example, you may have a step with identifier n0 in one chat flow and another step with identifier n0 in another chat flow. You may not have two steps with identifier n0 in the same chat flow.

If you are creating a new custom flow, you must supply your own set of identifiers in the request.

They can be any value, so long as they are unique for each step within the request. Once the flow is created, the values you provide will be replaced by internal system identifiers.

Root Node Step

The root node step is the entry point into a chat flow and the first step processed and rendered for end users in chat.

Connection Rules

Must be a TEXT step
Must be the first element of the step array (array index = 0)
No other steps may connect to the root node step
For Facebook platforms:
- Cannot be the last step in a flow
For other platforms:
- Can be the last step in a flow

User Experience Steps

The steps in this section render visual components for end users in chat. They may also include server-side or client-side elements that are not rendered to the end user, such as reporting a button click using a server-side track event.

TEXT

A message that is sent to end users in chat. This is how it can appears to end users:

{
    "group": "text",
    "id":    "STRING IDENTIFIER",
    "label": "STRING"
}

group

The group value must be text.

label

REQUIRED - String
Validation: For Facebook platforms, 2000 character limit

The label is the text message that is displayed to end users.

Connection Rules

Any type of step can connect to it except a LIVE CHAT TRANSFER
Multiple steps can connect to it
Can connect to any type of step
Can connect to up to 6 BUTTONS
For other types of steps, can only connect to one other step
Can be the last step in a flow

BUTTONS

A widget with a label that is sent to end users in chat and is clickable by them. When clicked, buttons can represent three types of actions:

Phone call
- Triggers the phone dialer of the end user client to launch with the phone number assigned to the button
URL
- Opens the URL assigned to the button in a new browser window
Message
- Jumps to a message in the chat flow and can be used to create branches in the chat flow tree

A button includes a pause in the chat flow until the end user takes an action and is also the last step for a turn. It appears like this to end users:

{
    "group": "buttons",
    "id":    "STRING IDENTIFIER",
    "label": "STRING",
    "meta": {
        "type":  "ENUMERATED STRING",
        "value": "STRING"
    }
}

group

The group value must be buttons.

label

REQUIRED - String
Validation: For Facebook platforms, 20 character limit For other platforms, 30 character limit

The label is the title that is displayed to end users for the button.

meta.type

OPTIONAL - String
Validation: Value is one of the pre-defined enumerated values

The type of action taken when the button is clicked by an end user. The value must be one of:

phone - opens and pre-populates the end user's phone dialer with the value provided in meta.value
url - opens and loads the URL provided in meta.value in a new tab or browser window

If meta.type is not provided in the request, the button is defined as a click-to-next-message type by default.

meta.value

OPTIONAL - String
Validation: Value is a valid URL or phone number, depending on meta.type Required if meta.type is included in the request

The phone number or URL that is loaded when the button is clicked. If meta.type is included in the request, meta.value becomes a required parameter.

If the meta.type is url, the protocol, http(s), must be included with the URL.

If the meta.type is phone, the phone number must include area code.

Connection Rules

Only a TEXT step can connect to it
If meta.type is click-to-next-message:
- - Can connect to any type of step except BUTTONS
  - Can only connect to one other step
  - Cannot be the last step in a flow
If meta.type is phone or url:
- Cannot connect to any other step
  - Is the last step in a flow

USER INPUT

A widget with a text message that precedes it, prompting end users to enter a text input. There are four types of user inputs:

Email
- Includes basic validation for all marketing channels except Facebook platforms
- Includes a pre-populated button for Facebook platforms
Phone Number
- Includes basic validation for all marketing channels except Facebook platforms
- Includes a pre-populated button for Facebook platforms
Name
- Includes basic validation for all marketing channels except Facebook platforms
- Not necessary on Facebook platforms as the name is provided by Facebook
Custom
- No validation

A user input includes a pause in the chat flow until the end user takes an action and is also the last step for a turn. If the end user enters an invalid value, the turn is repeated.

User inputs appear as labelled form boxes to end users:

{
    "group": "input",
    "id":    "STRING IDENTIFIER",
    "label": "STRING",
    "meta": {
        "attribute": "STRING"
    }
}

group

The group value must be input.

label

REQUIRED - String
Validation: For Facebook platforms, 2000 character limit For other platforms, 30 character limit

On Facebook platforms, the label is the text message prompting the user to enter an input. For other platforms, the label is the title that is displayed in the input box.

meta.attribute

OPTIONAL - String

The attribute name that will be associated with the user input. If meta.attribute is one of the following values, validation will also be applied to the input:

email
name
phone

On Facebook platforms, user inputs with meta.attribute values of email and phone include a clickable, pre-populated button with the email or phone number associated with the end user's Facebook profile.

If meta.attribute is not provided in the request or the value is not one of the three types above, the input is assumed to be custom.

Connection Rules

Any type of step can connect to it except a LIVE CHAT TRANSFER
Multiple steps can connect to it
Can only connect to a TEXT step
Can only connect to one other step
Cannot be the last step in a flow

IMAGE

An image card that is sent to end users in chat. jpgs, pngs and and gifs are valid image formats.

A valid image or gif appears as a message to end users:

{
    "group":    "image",
    "id":       "STRING IDENTIFIER",
    "imageUrl": "URL"
}

group

The group value must be image.‌

imageUrl

REQUIRED - String
Validation: A valid URL including protocol http(s)

The URL for the hosted image.

Connection Rules

Any type of step can connect to it except a LIVE CHAT TRANSFER
Multiple steps can connect to it
Can connect to any type of step
Can only connect to one other step
Can be the last step in a flow

VIDEO

A video card that is sent to end users in chat. If the video is hosted on YouTube, the video card includes an embedded YouTube video player. Otherwise, the card consists of a button labelled "Play Video".

YouTube hosted video as it appears to the end user:

Any other video:

{
    "group": "image",
    "id":    "STRING IDENTIFIER",
    "label": "URL"
}

group

The group value must be video.‌

label

REQUIRED - String
Validation: A valid URL including protocol http(s)

The URL for the hosted video.

Connection Rules

Any type of step can connect to it except a LIVE CHAT TRANSFER
Multiple steps can connect to it
Can connect to any type of step
Can only connect to one other step
Can be the last step in a flow

CARD CAROUSELS

A card or a swipe-able carousel of cards sent to end users in chat. A carousel consists of 2-6 cards. The carousel can also consist of a single card with swipe actions disabled. Each card in the carousel includes a title, description, and at least 1 button (up to a maximum of 3 buttons). Each card can also optionally include a 1:1 aspect ratio image. To add a card or carousel, the user chooses "card" from the menu.

This is how it will appear to the end user:

Process Steps

The steps in this section do not render any visual components for end users in chat. They are steps that execute without the end user being aware that they happened.

USER TAGS

An action the EyeLevel platform takes to store a key-value for the end user. Common uses include assigning key-values to an end user based on their choices in the chat flow. These tags are automatically exported with Track Events. It is not rendered in the end user chat experience.

{
    "group": "label",
    "id":    "STRING IDENTIFIER",
    "meta": {
        "userTag": {
            "key":   "STRING",
            "value": "STRING"
        }
    }
}

group

The group value must be label.‌

meta.userTag.key

REQUIRED - String
Validation: 128 character limit

The name of the attribute that will be associated with the value.

meta.userTag.value

REQUIRED - String
Validation: 128 character limit

The value of the attribute, functionally equivalent to the value in a key-value.

Connection Rules

Any type of step can connect to it except a LIVE CHAT TRANSFER
Multiple steps can connect to it
Can connect to any type of step
Can only connect to one other step
Can be the last step in a flow

ACTION ALERT

An action the EyeLevel platform takes to notify EyeLevel customers of actions taken in chat. When this step executes, a configurable alert is pushed to the EyeLevel customer. It is not rendered in the end user chat experience.

{
    "group": "alert",
    "id":    "STRING IDENTIFIER",
    "meta": {
        "alert": {
            "alert":       "STRING",
            "platform":    "ENUMERATED STRING",
            "teamId":      "STRING IDENTIFIER",
            "workspaceId": "STRING IDENTIFIER"
        }
    }
}

group

The group value must be alert.‌

meta.alert.alert

REQUIRED - String

The alert message that will be sent to the EyeLevel customer.

meta.alert.platform

REQUIRED - String
Validation: Value is one of the pre-defined enumerated values

The type of live chat platform where the alert message will be sent. The value must be one of:

slack - will send a message to a Slack channel
msteams - will send a message to a Microsoft Teams channel
sms - will send an SMS text message to a single number or group of numbers

meta.alert.teamId

REQUIRED - String
Validation: Value is an existing EyeLevel live chat integration identifier

One of two unique EyeLevel identifiers for the live chat integration where the alert message will be sent. You can query for valid live chat integration identifiers using the GET ALL INTEGRATIONS query.

meta.alert.workspaceId

REQUIRED - String
Validation: Value is an existing EyeLevel live chat integration identifier

Connection Rules

Any type of step can connect to it except a LIVE CHAT TRANSFER
Multiple steps can connect to it
Can connect to any type of step
Can only connect to one other step
Can be the last step in a flow

LIVE CHAT TRANSFER

An action the EyeLevel platform takes to transfer control of the chat to an EyeLevel customer. When this step executes, an alert is pushed to the EyeLevel customer with a copy of the automated chat transcript.

The automated chat is permanently disabled for the end user so that the live chat with the EyeLevel customer is not disrupted. Automated chat can be re-enabled by the end user by typing "clear all" or "reset chat" in chat. The automated chat can also be re-enabled (except on Facebook platforms) by including "eyreset=true" in the chat URL.

Live Chat is also the last step for a turn and the end of the chat flow (represented in analytics as a chat completion).

This step is described in greater detail in the LIVE CHAT section.

{
    "group": "transfer",
    "id":    "STRING IDENTIFIER",
    "label": "STRING IDENTIFIER"
}

group

The group value must be transfer.‌

label

REQUIRED - String
Value is an existing EyeLevel live chat integration identifier

A hash of the unique EyeLevel identifiers for the live chat integration. You can query for valid live chat integration identifiers using the GET ALL INTEGRATIONS query.

The format of the hash is as follows:

platform:workspaceId:teamId

Connection Rules

Any type of step can connect to it except a LIVE CHAT TRANSFER
Multiple steps can connect to it
Cannot connect to any other step
- Is the last step in a flow

SERVER-SIDE TRACK EVENT

An action the EyeLevel platform takes to export chat data to third party systems. This step is described in greater detail in the TRACK EVENT section. It is not rendered in the end user chat experience.

{
    "group": "submit",
    "id":    "STRING IDENTIFIER",
    "meta": {
        "server": {
            "integration": "ENUMERATED STRING",
            "headers": [
                {
                    "key":   "STRING",
                    "value": "STRING"
                }
            ],
            "method":      "ENUMERATED STRING",
            "name":        "STRING IDENTIFIER",
            "payload":     "JSON STRINGIFIED STRING",
            "url":         "URL"
        }
    }
}

group

The group value must be submit.‌

meta.server.integration

REQUIRED - String
Validation: Value is one of the pre-defined enumerated values

The type of track event integration. The value must be one of:

custom - a configurable HTTP request
email - will send data to a given set of emails
mailchimp - will export data to Mailchimp
zapier - will export data to the EyeLevel Zap

meta.server.headers

OPTIONAL - Array of key-values

This attribute only applies to the following integration types:

custom

The key-values defined in headers will be applied to the track event request.

meta.server.method

OPTIONAL - String
Validation: Value is one of the pre-defined enumerated values

This attribute is required for the following integration types:

custom - must be set to "POST" or "GET"
mailchimp - must be set to "POST"
zapier - must be set to "POST"

meta.server.method does not apply to other integration types.

meta.server.name

OPTIONAL - String
Validation: Value is an existing EyeLevel track event integration identifier

This attribute is required for the following integration types:

mailchimp - the unique Mailchimp audience ID (can be queried for using the GET ALL INTEGRATIONS query)
zapier - a name that will be referenced when setting up Zaps in Zapier

meta.server.name does not apply to other integration types.

meta.server.payload

OPTIONAL - JSON stringified String
Validation: Value parses into valid JSON

This attribute is required for the following integration types:

email

For email integrations, the structure of the payload must follow this format:

{
    "recipients":[
        "EMAIL"
    ]
}

The JSON object must be converted into a string prior to making the request. Any emails included in the recipients array will receive track event data.

This attribute is optional for the following integration types:

custom

For custom integrations, the structure of the payload must follow this format:

{
    "KEY": "VALUE"
}

The values must be provided as key-values where values can only be strings. Any key-values provided in meta.server.payload will be included in the custom track event request.

meta.server.payload does not apply to other integration types.

meta.server.url

OPTIONAL - String
Validation: A valid URL including protocol http(s)

This attribute is required for the following integration types:

custom - the URL for the custom request
mailchimp - the unique Mailchimp API request URL (can be queried for using the GET ALL INTEGRATIONS query)

meta.server.url does not apply to other integration types.

Connection Rules

Any type of step can connect to it except a LIVE CHAT TRANSFER
Multiple steps can connect to it
Can connect to any type of step
Can only connect to one other step
Can be the last step in a flow

CLIENT-SIDE TRACK EVENT

Local client side events can be configured to:

Broadcast an event to the client browser window
Execute custom javascript

In the case of broadcasting an event, the JSON provided with the LOCAL integration is broadcast by invoking "window.dispatchEvent".

In the case of executing custom javascript, javascript provided with the LOCAL integration is executed in the client browser window without validation.

{
    "group": "setattr",
    "id":    "STRING IDENTIFIER",
    "meta": {
        "local": {
            "key":   "STRING",
            "value": "STRING"
        }
    }
}