Commands

Messages typed command are used by agents to give commands to Web1on1 or backend automations. We distinguish between System Commands and Bot Commands

System Commands change the state of the conversation by inviting and assigning participants, adding messages, processing results and sending notifications. Web1on1 system commands start with a slash (/). The following commands can be used:

Channel Notifications

/notify

/notify using routing rules

The notify command queues any closed conversation, by running any workflows and finding available channels for the conversation's queued state.

{
    "type": "command",
    "text": "/notify"
}

/notify using other organizations' routing rules

By default, /notify triggers all workflows of the conversation's organization and its ancestors. To target a subset of organizations only, provide a list of target meta.organizations

{
    "type": "command",
    "text": "/notify",
    "meta": {
        "organizations": [
            "5b979647a61b336ec33f201a"
        ]
    }
}

This will trigger channel notifications based only on the routing rules of the specified organizations.

/notify specific channels

To notify a predetermined set of channels (and completely bypass any organization workflows), include a list of channel IDs in the message's meta.channels property:

{
    "type": "command",
    "text": "/notify",
    "meta": {
        "channels": [
            "59179631c63934459825deea",
            "59b007b7667e2132d4ac1b51"
        ]
    }
}

Inbox Notifications

/assign

This command assigns the conversation to one or more users. The user is added as a participant in the conversation, and will have the inbox flag set. This flag will be removed the when the user accepts the conversation.

{
    "type": "command",
    "text": "/assign",
    "meta": {
        "users": [
            "59179631c63934459825deea",
            "59b007b7667e2132d4ac1b51"
        ]
    }
}

/follow

This command lets a user follow the conversation, by receiving an inbox notification whenever a new consumer message comes in. The user is added as a participant in the conversation (if not already), and will have the follow flag set. From that moment forward, any new consumer message will set the inbox notification flag for the user, notifying him/her of new conversation activity (if the user does not have the conversation open already). The inbox flag will be removed the when the user accepts the conversation.

{
    "type": "command",
    "text": "/follow",
    "user": "59b007b7667e2132d4ac1b51"
}

/unfollow

This command lets a user unfollow the conversation, by canceling any future inbox notifications on new consumer messages. The user should be a participant in the conversation, and will have the follow flag removed.

{
    "type": "command",
    "text": "/unfollow",
    "user": "59b007b7667e2132d4ac1b51"
}

Participants

/join

The agent joins the conversation. The purpose of this command, is to add the user to the conversation as a passive participant - like an administrator or reviewer viewing the conversation, a bot monitoring the conversation, or similar. The conversation status is not changed - so channel notifications for new inbound messages will still be send if the status stays 'queued', for example.

{
    "type": "command",
    "text": "/join",
    "user": "59b007b7667e2132d4ac1b51"
}

The **active' flag is set for this participant in the conversation. Without specifying a user explicitly, the current API user will be assigned to the conversation.

/accept

The agent accepts the conversation. In addition to joining the conversation as a participant, the agent accepts responsibility for handling and closing the conversation. This command:

sets the conversation.status to active
sets the active and accepted flags for the conversation participant (the user);
sends out channel dequeue notifications and clears conversation.channels and conversation.channelsOffline

{
    "type": "command",
    "text": "/accept",
    "user": "59b007b7667e2132d4ac1b51"
}

Without specifying a user explicitly, the current API user will be assigned to the conversation. After accepting, the conversation stays active (exempt from channel notifications) until the last of the accepting agent leaves.

/leave

The agent leaves the conversation. First, the conversation will be closed in the UI. Then this command unassigns the current user from the conversation, and sets the conversation status to queued (or closed if the consumer's last message was replied to by an agent and the conversation was accepted with /accept before). Otherwise, by running any workflows and finding available channels for the conversation's queued state, new channel notifications are sent out.

{
    "type": "command",
    "text": "/leave"
}

Aliases: close

To forward a conversation, use a combination of leave and join for the user property, use the ID of the leaving user in the /leave request, and the ID of the newly assigned user in the second (/join) request. Note that in practice, the order of these two request doesn't matter.

{
    "type": "command",
    "text": "/leave",
    "user": "599e1fcd9da1c72645c95886"
}

{
    "type": "command",
    "text": "/join",
    "user": "590e67fa4eae6757b914658a"
}

/block

This command blocks the contact (by IP address) from sending further messages, and closes the conversation.

{
    "type": "command",
    "text": "/block"
}

Conversation properties

/set

The /set command is used to manage conversation state, by setting:

conversation properties, and
meta (metadata) for the conversation. Conversation metadata may be used by backend automations when processing webhook requests.

Conversation Properties

These /set properties change basic conversation state:

name
context
category
touchpoint
language

How to set Forms and Form Fields is explained in the next chapter.

Set commands that change conversation properties should have the property prefixed by a '@'.

/set @name

This command changes the name of the conversation, as shown in the UI as a default identifier. The name field is initialized with a random fantasy name when a conversation is created.

{
    "type": "command",
    "text": "/set @name Account Review"
}

/set @context

This command changes the context of the conversation. The context is set automatically set on bot and form activity, but can be overruled by bots.

{
    "type": "command",
    "text": "/set @context Account Review"
}

See the Getting Started guide for more information.

/set @category

This command changes the active category of the conversation.

{
    "type": "command",
    "text": "/set @category Used Car"
}

However, it may be better (category names may change) to specify the (zero-based) index of the category slot (as configured for the organization):

{
    "type": "command",
    "text": "/set @category 1"
}

/set @touchpoint

This command changes the target touchpoint for the contact of the conversation. Valid touchpoints may be web email sms or facebook depending on conversation.touchpoints properties.

{
    "type": "command",
    "text": "/set @touchpoint email"
}

After changing the target touchpoint for the conversation, any messages with role agent will be routed to the new consumer touchpoint. If unavailable, message routing will be tried for one of the other channels, in the following order: [web, facebook, email, sms]

/set @language

This command changes the language of the conversation - a two-letter lowercase code (as returned by Google's Translation API).

{
    "type": "command",
    "text": "/set @language de"
}

The perceived conversation language is typically set by a language detection automation, or by the system itself (based on language detection of message texts).

Conversation Metadata

Any /set variable that is not prefixed with '@' will set conversation.meta properties. The simplest invocation is simply including a key/value pair in the text:

{
    "type": "command",
    "text": "/set engagement high"
}

Any message metadata provided with the /set command will be merged into the conversation meta data; to merge multiple key/value pairs into conversation.meta, provide a meta object:

{
    "type": "command",
    "text": "/set",
    "meta": {
        "engagement": "high",
        "scores": [8, 7, 6.5]
    }
}

The system may set some conversation metadata prefixed by an underscore, such as meta._title meta._url meta._agent and meta._agentAvatar See the Meta Properties chapter for details.

Message Actions

Existing messages may be acted upon, and edited, by messages actions. The action command comes with a subcommand to denote the message action, and a required meta.message specifies the message that is acted on.

The following actions and subcommands are available:

/action like

This action makes the requestor like a message. Here's an example:

{
    "type": "command",
    "text": "/action like",
    "meta": {
        "message": "5d4af42a529b5549737d5574"
    }
}

After liking a message, the message has been edited to contain the user in the likes list, like this:

{
    "type": "chat",
    "text": "No need, I could easily find it on your website",
    "likes": [
        "5d554542fe7730001185fb22"
    ]
    ...
}

A message can contain up to 100 likes.

/action comment

The action comment command adds a comment to a message. Here's an example:

{
    "type": "command",
    "text": "/action comment Our website redesign really works out!",
    "meta": {
        "message": "5d4af42a529b5549737d5574"
    }
}

The comment is added to the comments message attribute, with a reference to the just created action command message ID:

{
    "type": "chat",
    "text": "No need, I could easily find it on your website",
    "comments": [
        {
            "user": "5d554542fe7730001185fb22",
            "message": "5d60a7b7949e381ffa0ef481",
            "text": "Our website redesign really works out!"
        }
    ]
    ...
}

A message can contain up to 10 comments.

Result Processing

/send

This command sends and clears any completed form results in the conversation, and adds a resulttype message into the conversation. It moves any completed forms from the *conversation.forms into conversation.results and may send out email notifications for form results.

By specifying the form ID of a single completed form within the currently active category, just that one form will be processed into the conversation results. Example:

{
    "type": "command",
    "text": "/send",
    "meta": {
        "form": "590bcf50458b716046347f36"
    }
}

Without meta.forms specified, all completed conversation forms across all categories will be processed.

Contact Merging

/import

The /import command merges two conversations into one. Imports are triggered by the system automatically when contacts are merged at remote endpoints, and can also be triggered by agents following up on merge suggestions. When multiple contact profiles with identical identifiers (email or telephone) are encountered by the system, a call-to-action button will be added to the conversations, to have an agent review and merge both conversations.

{
    "type": "command",
    "text": "/import 590bcf50458b716046347f36"
}

This merges the origin conversation (here:..7f36) into a destination conversation (being posted to, here:..7f47).

After importing, the origin conversation will have changed:

the name is set to "TRANSFERRED"
the status is set to "archived"
messages that were copied into the target will have meta._target set to the destination message id.

The target conversation will have the imported messages interwoven with its originals, reindexed and reordered by creation date/time. The imported message copies have meta._source set to the id of the source message, and the version incremented.

Bot Commands

In addition to internal Web1on1 commands, other automations listening to conversations (such as bots) may want to be triggered by agents. These bot commands should start with the greater-than sign (>) and have no special meaning to Web1on1.

{
    "type": "command",
    "text": ">onboard"
}

Web1on1 ignores these commands. Presumably some automation would pick this up as a trigger to start interacting with the agent and/or the consumer.

Comments, Tags and Search Statuses

On this page