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

7. Meta Properties

Attaching metadata to resource objects is a great way to pass information from backend automations to ChatShipper, 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": "[email protected]",
        "name": "Jannie",
        "title": "ChatShipper | SmartSupp Widget #1",
        "page_views": "1",
        "visits": "2",
        "chats": "1",
        "using": "Chrome",
        "online": "a few seconds",
        "variables": {
            "chatShipperId": "123",
            "chatShipperTarget": "128 000"
        "ip": "",
        "url": "http://localhost:3102/smartsupp1"
    ... other message properties ...

For service integration like XMPP or web widget services, ChatShipper 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 ChatShipper 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": "",
    "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.

Property Type Description
title string Displayed short title. Set by the agent.
fileName string Original name of uploaded file.
fileType string MIME type of the file. Image or PDF.
fileId string ID of the Attachment that was created on upload.

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"
Property Type Description
form string Form ID.
field string ID of the field that was added.

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 ...
Property Type Description
targetUser string Receiving user.
targetOrganization string Receiving organization.
targetName string Name of target user or organization.

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": ""
    ... other message properties ...
Property Type Description
meta.url string Widget URL from conversation.meta, if available.

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
Property Type Description
title string Card panel heading.
_noCopy boolean Server-set var indicating the card will not be copied when conversations are merged.


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": [
        "trigger": "channel",
        "isTask": false
Property Type Description
channels array One or more channels this conversation was accepted from.
trigger string Method of acceptance by the agent.
isTask boolean Accepted from a bot-notified channel.

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.

Summary: Message Metadata

Variable Description
message.meta.targetName Set on type=comment
message.meta.targetUser Set on type=comment
message.meta.targetOrganization Set on type=comment
message.meta.users Set on command /assign
message.meta.channels Set on command /notify
message.meta.form Set on command /send
message.meta.url Set on type=results
message.meta.form Set on type=form or type=field]
message.meta.categoryIndex Set on type=form or type=field]
message.meta.category Set on type=field
message.meta.field Set on type=field; form field
message.meta.key Set on type=field; profile field
message.meta._noCopy Set for injected messages at source and target (conversation merge)
message.meta._source Set for target, imported messages (conversation merge)
message.meta._target Set for source messages (conversation merge)
message.version Incremented for target message copies (conversation merge)

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

Variable Description
contact._contextSent Flag indicating that first-outbound email context has been sent
conversation.meta._title Last seen widget page title, if available
conversation.meta._url Widget URL as last seen in the conversation
conversation.meta._agent Agent alias; fake agent name for anonymizing users towards consumers
conversation.meta._agentAvatar Stock profile picture for agent alias
conversation.meta._target Target conversation ID that this archived conversation was merged into (conversation merge)

Updated 6 months ago

7. Meta Properties

Suggested Edits are limited on API Reference Pages

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