The ChatShipper Developer Hub

Welcome to the ChatShipper developer hub. You'll find comprehensive guides and documentation to help you start working with ChatShipper as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

5. Commands

Messages typed command are used by agents to give commands to ChatShipper 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. ChatShipper 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.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "command",
    "text": "/assign",
    "meta": {
        "users": [
            "59179631c63934459825deea",
            "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.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "command",
    "text": "/join",
    "user": "bbb000000000000000444444"
}

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

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "command",
    "text": "/accept",
    "user": "bbb000000000000000444444"
}

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. 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, the conversation will be closed. Otherwise, by running any workflows and finding available channels for the conversation's queued state, new channel notifications are sent out.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

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

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

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

/block

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

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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
  • category
  • touchpoint
  • language

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

/set @name <string>

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.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

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

/set @category <string or integer>

This command changes the active category of the conversation.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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):

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

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

/set @touchpoint <value>

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.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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 <value>

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

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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:

Request: GET /v2/messages/5d4af42a529b5549737d5574

{
    "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:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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:

Request: GET /v2/messages/5d4af42a529b5549737d5574

{
    "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 result-type 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:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "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 ChatShipper 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 ChatShipper.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

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

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


5. Commands


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.