Meta Properties

Attaching metadata to resource objects is a great way to pass information from backend automations to Web1on1, and back to other automation instances. Metadata can be included when first creating resources, or by updating them during runtime from automations.

Any metadata attached to any resources will (when relevant) be passed on to all backend automations through webhooks and is available through the API.

Resources with metadata

The following resource types have metadata attached:

• Organization
• User
• Service
• Form
• Contact
• Conversation
• Message

Creating and updating metadata

A resource's metadata object can be provided on creation, or set when updating the resource.

Metadata for the first four resources are typically configured from the UI, when the organization account is provisioned. They can, however, be modified during the lifetime of the resource.

For example, an automation might keep track of an agent's accomplishments by using attaching a score meta property:

Request: PATCH /v2/users/591789e5c63934459825dede

{
    "meta": {
        "score": 12
    }
}

NOTE: that when updating a resource's meta object, a PATCH request will replace any nested objects in your request data, not merge it. To update just one meta property, the full updated meta object needs to be provided.

Message metadata

Service-Inbound Messages

Messages coming from service integrations have their metadata is set on message creation. It is typically provided by the automation or service integration that created the message. For example, a message coming from SmartSupp might look like this:

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

{
    "id": "599c1622bb40181d93123e2a"
    "meta": {
        "status": "CLICKED",
        "email": "sitetechie@gmail.com",
        "name": "Jannie",
        "title": "Web1on1 | SmartSupp Widget #1",
        "page_views": "1",
        "visits": "2",
        "chats": "1",
        "using": "Chrome",
        "online": "a few seconds",
        "variables": {
            "id": "123",
            "target": "128 000"
        },
        "ip": "95.97.247.46",
        "url": "http://localhost:3102/smartsupp1"
    },
    ... other message properties ...
}

For service integration like XMPP or web widget services, Web1on1 will try to copy any meta.title and/or meta.url properties of the message into the conversation's metadata, and produce a system message when this data has changed.

File Uploads

When uploading files from the agent console, the Web1on1 UI sets a few basic file properties as meta data, when creating a message for a specific contentType. Here's an example:

Request: GET /v2/messages/5c5d7b78f6594b1ff072f052

{
    "id": "5c5d7b78f6594b1ff072f052"
    "contentType": "image/png",
    "text": "https://storage.googleapis.com/cs2-uploads/attachments/aaa111111111111111111111/aaa000000000000000000111/5c81d1bc2af7a35fa98a292b/1552056818802-companylogo.png",
    "meta": {
        "title": "Our company logo",
        "fileName": "companylogo.png",
        "fileType": "image/png",
        "fileId": "5c8281f3973d3c306a9b250d"
    },
    ... other message properties ...
}

In this message, meta.title is provided by the agent, and meta.fileName, meta.fileType and meta.fileId are copied by the frontend app after having uploaded a file to the attachments endpoint.

Form and Field messages

As we have seen in the previous chapter, message meta data is interpreted for form and field -typed messages.

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

{
    "type": "field",
    "text": ".rating 7.3",
    "meta": {
      "form": "590c76bdde1b762f2113e81c",
      "field": "590c76bdde1b762f2113e81d"
    }
}

Comments (mentions)

Comments are always targeting either a single organization or a single user. In addition, the system sets the target's name.

Request: GET /v2/conversations/590bd49f458b716046347f47/messages/5c8599bd56f730752e926dc6

{
    "type": "mention",
    "text": "Check this out",
    "meta": {
        "targetOrganization": "5c8599bd56f730752e926dc6",
        "targetName": "Skynet"
    },
    ... other message properties ...
}

Results messages

Messages typed results are typically generated by the system on receiving /send commands, and may have the last-known widget URL set as its meta.url property.

Request: GET /v2/messages/5c75ee15c1bc6b5a7d1ea293

{

    "type": "results",
    "text": "/send success - forms processed",
    "results": [
        { ... },
        { ... }
    ],
    "meta": {
        "url": "https://www.example.com/products"
    },
    ... other message properties ...
}

Card Panels

As detailed in the chapter on Chat Messages, the card type optionally uses the meta.title property to show a panel title, or the meta.backgroundColor to customize the background. Here's an example:

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

{
    "type": "card",
    "text": "Here is some information",
    "meta": {
        "title": "Additional Info",
        "backgroundColor": "#fffae7"
    }
}

A meta._noCopy flag is set in system messages that are to be discarded before merges. Here's an example of what the system may create on detecting shared contact identifiers:

Request: GET /v2/messages/5c8599bd56f730752e926dc6

{
    "type": "card",
    "isBackchannel": true,
    "role": "system",
    "contentType": "text/html"
    "text": "Another conversation also has this contact's telephone or email address. You may want to <strong>merge</strong> the conversations into a single contact record.",
    "meta": {
        "title": "Multiple overlapping contact profiles",
        "_noCopy": true
    }
}

Commands

As seen in the chapter on Commands and Bot Triggers, some commands may use one or more optional meta properties:

• /assign may optionally specify an array of meta.users;
• /notify may optionally specify an array of meta.channels;
• /accept may have an array of meta.channels set by the frontend;
• /set will have its meta properties copied to the conversation;
• /send may have a meta.form specified.
• /import will set meta._mergeTarget set for source messages, and meta._mergeSource on copied messages. The system also posts merge suggestions in the conversation, these have meta._noCopy set to true and will be removed when conversations are merged.

/accept meta data

Request: GET /v2/messages/5c6eafdfe3ba841eddf1c1ac

{
    "type": "command",
    "text": "/accept",
    "meta": {
        "channels": [
            "5b2bf9dd9f3c885eb7ad7a63"
        ],
        "trigger": "channel",
        "isTask": false
    }
}

The isTask flag is set by the server when any channel is a task channel for this conversation.

The trigger property is set by the frontend app, based on the method that was used to accept the conversation. Possible values are:

• inbox: the agent clicked the inbox button;
• channel: the agent clicked a channel button;
• notification: the agent clicked a desktop notification;
• shortkey: the agent used the CTRL+\ CTRL+backslash shortkey
• command: the agent typed the /accept command
• open:: the agent typed the /open command
• link: the agent visited a conversation URL directly.

The last option, link, is a special case. When an agent visist a conversation URL, he/she joins the conversation without accepting it. When a conversation is joined:

• the text is set to "/join", not "/accept";
• the participant's isAccepted flag is set to false;
• the conversation is not dequeued from any channels;
• no meta.channels are set by the frontend.

Status

Notifications Delivered

A Notifications Delivered status message is inserted in the conversation stream each time channels or users were notified.

Each time a set of workflows are executed, as a result of an inbound message or a /notify or /assign command, users may be notified through their inbox or through channels subscriptions. This status message shows the delivery results.

Request: GET /v2/messages?type=status&text=~delivered

[
    {
        "type": "status",
        "text": "Notifications Delivered",
        "meta": {
            "stateChannels": [
                "5b2bf9dd9f3c885eb7ad7a63"
            ],
            "stateChannelsOffline": [],
            "channels": [
                "5b2bf9dd9f3c885eb7ad7a63"
            ],
            "channelsOffline": [],
            "users": [],
            "usersOffline": [],
            "isTask": true,
            "hidden": true
        }
    }
]

Summary: Message Metadata

Conversation Metadata

Conversation metadata represents the state of the conversation, and changes over time. It can be used to attach custom properties to a conversation, to be shared by backend automations and API consumers, for example when running bots or processing webhook requests.

The /set command sets meta data for the conversation. As explained in the Commands and Bot Triggers chapter, it may receive a key/value pair in the text:

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

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

To specify multiple key/value pairs, set a message.meta object to be merged into the conversation metadata:

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

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

System-provided Metadata

To not get in your way, system-provided conversation, message and contact meta variables start with an underscore.

The Web1on1 system will try to set the url and/or title based on message metadata coming from service integrations, and may specify an agent alias and an agentAvatar URL to anonymize users.