System activities - Text Documentation

The Text ecosystem generates two types of native system activities sent to users as events:

System events containing complex data structures (in a serialized JSON string).
System messages containing simple text.

System events are an extension and a future replacement for system messages.

System events

The payload of the system event is a serialized JSON string stored in the details property, and its format depends on the source, subtype, and version. The sources send the newest available version, but existing chat documents may contain older versions. Later version numbers indicate more recent versions.

Sample system event body

{
  "id": "17f5ac89-e578-4d3f-9ab9-675be6209b00",
  "custom_id": "shopify_1744119867",
  "source": "cdp",
  "type": "system",
  "subtype": "store_order_was_created",
  "version": 1,
  "details": "{\"store\":{\"id\":\"my-store\",\"platform\":\"shopify\",\"uuid\":\"70cb9e59-b639-41c5-81cf-71db11972cff\",\"url\":\"https://my-store.myshopify.com\",\"name\":\"My Store\"},\"order\":{\"id\":\"gid://shopify/Order/1234567890\",\"order_number\":\"#1001\",\"currency\":\"USD\",\"total_price\":123.45,\"line_items\":[{\"title\":\"Product Name\",\"quantity\":2,\"price\":49.99,\"sku\":\"SKU123\",\"variant_id\":\"gid://shopify/ProductVariant/12345678901234\"}]}}",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "visibility": "all"
}

The list of system event subtypes grouped by source:

Source	Subtypes
`cdp`	`store_order_was_created` `store_product_added_to_cart` `store_product_removed_from_cart`
`messaging`	`summary`

cdp

CDP stands for Customer Data Platform. It collects customers’ data and emits events related to their interactions with the Text ecosystem.

store_order_was_created

Generated when a customer creates an order in an organization’s store.

Version 2
Version 1

Changes from Version 1: The title property in order’s line items became mandatory. A mandatory product_id property in order’s line items was added.

Parameter	Required	Data type	Notes
`store`	Yes	`object`
`store.id`	Yes	`string`	The store ID provided by the platform
`store.platform`	Yes	`string`	The platform the store is hosted on
`store.uuid`	Yes	`string`	The store’s unique identifier in Text system
`store.url`	No	`string`	The store’s URL
`store.name`	No	`string`	The store’s name
`order`	Yes	`object`
`order.id`	Yes	`string`	The order ID provided by the platform
`order.order_number`	Yes	`string`	Visual representation of the order ID provided by the platform
`order.currency`	Yes	`string`	The currency code in ISO 4217 format
`order.total_price`	Yes	`number`	The total price of the order
`order.sales_channel`	No	`object`
`order.sales_channel.id`	Yes	`string`	The unique identifier of the sales channel
`order.sales_channel.name`	Yes	`string`	Human-readable sales channel name
`order.discounts`	No	`array`
`order.discounts.code`	Yes	`string`	The discount code
`order.line_items`	Yes	`array`
`order.line_items.quantity`	Yes	`number`	The quantity of the line item
`order.line_items.price`	Yes	`number`	The price of the line item
`order.line_items.title`	Yes	`string`	The title of the line item
`order.line_items.product_id`	Yes	`string`	The variant ID of the line item
`order.line_items.sku`	No	`string`	The SKU of the line item
`order.line_items.variant_id`	No	`string`	The variant ID of the line item

Sample store_order_was_created payload

{
  "store": {
    "id": "my-store",
    "platform": "shopify",
    "uuid": "70cb9e59-b639-41c5-81cf-71db11972cff",
    "url": "https://my-store.myshopify.com",
    "name": "My Store"
  },
  "order": {
    "id": "gid://shopify/Order/1234567890",
    "order_number": "#1001",
    "sales_channel": {
      "id": "social-media-sales-channel",
      "name": "Social Media App"
    },
    "currency": "USD",
    "total_price": 123.45,
    "discounts": [{ "code": "2FOR1" }],
    "line_items": [
      {
        "title": "Product Name",
        "quantity": 2,
        "price": 49.99,
        "sku": "SKU123",
        "variant_id": "gid://shopify/ProductVariant/12345678901234",
        "product_id": "123"
      }
    ]
  }
}

Parameter	Required	Data type	Notes
`store`	Yes	`object`
`store.id`	Yes	`string`	The store ID provided by the platform
`store.platform`	Yes	`string`	The platform the store is hosted on
`store.uuid`	Yes	`string`	The store’s unique identifier in Text system
`store.url`	No	`string`	The store’s URL
`store.name`	No	`string`	The store’s name
`order`	Yes	`object`
`order.id`	Yes	`string`	The order ID provided by the platform
`order.order_number`	Yes	`string`	Visual representation of the order ID provided by the platform
`order.currency`	Yes	`string`	The currency code in ISO 4217 format
`order.total_price`	Yes	`number`	The total price of the order
`order.sales_channel`	No	`object`
`order.sales_channel.id`	Yes	`string`	The unique identifier of the sales channel
`order.sales_channel.name`	Yes	`string`	Human-readable sales channel name
`order.discounts`	No	`array`
`order.discounts.code`	Yes	`string`	The discount code
`order.line_items`	Yes	`array`
`order.line_items.quantity`	Yes	`number`	The quantity of the line item
`order.line_items.price`	Yes	`number`	The price of the line item
`order.line_items.title`	No	`string`	The title of the line item
`order.line_items.sku`	No	`string`	The SKU of the line item
`order.line_items.variant_id`	No	`string`	The variant ID of the line item

Sample store_order_was_created payload

{
  "store": {
    "id": "my-store",
    "platform": "shopify",
    "uuid": "70cb9e59-b639-41c5-81cf-71db11972cff",
    "url": "https://my-store.myshopify.com",
    "name": "My Store"
  },
  "order": {
    "id": "gid://shopify/Order/1234567890",
    "order_number": "#1001",
    "sales_channel": {
      "id": "social-media-sales-channel",
      "name": "Social Media App"
    },
    "currency": "USD",
    "total_price": 123.45,
    "discounts": [{ "code": "2FOR1" }],
    "line_items": [
      {
        "title": "Product Name",
        "quantity": 2,
        "price": 49.99,
        "sku": "SKU123",
        "variant_id": "gid://shopify/ProductVariant/12345678901234"
      }
    ]
  }
}

store_product_added_to_cart

Generated when a customer adds one or more products to their cart in an organization’s store.

Parameter	Required	Data type	Notes
`store`	Yes	`object`
`store.id`	Yes	`string`	The store ID provided by the platform
`store.platform`	Yes	`string`	The platform the store is hosted on
`store.uuid`	Yes	`string`	The store’s unique identifier in Text system
`store.url`	No	`string`	The store’s URL
`store.name`	No	`string`	The store’s name
`cart_lines`	Yes	`array`
`cart_lines.total_price`	Yes	`string`	Total price for item accounting for its quantity
`cart_lines.currency`	Yes	`string`	The currency code in ISO 4217 format
`cart_lines.quantity`	Yes	`string`	The quantity of the item
`cart_lines.product`	Yes	`object`
`cart_lines.product.id`	Yes	`string`	The ID of the product
`cart_lines.product.title`	No	`string`	The title of the item
`cart_lines.product.sku`	No	`string`	The SKU of the item
`cart_lines.product.variant_id`	No	`string`	The variant ID of the item

Sample store_product_added_to_cart payload

{
  "store": {
    "id": "my-store",
    "platform": "shopify",
    "uuid": "70cb9e59-b639-41c5-81cf-71db11972cff",
    "url": "https://my-store.myshopify.com",
    "name": "My Store"
  },
  "cart_lines": [
    {
      "total_price": 45.99,
      "currency": "USD",
      "quantity": 5,
      "product": {
        "id": "gid://shopify/Product/123456789",
        "title": "Product Name",
        "sku": "SKU123",
        "variant_id": "gid://shopify/ProductVariant/12345678901234"
      }
    }
  ]
}

store_product_removed_from_cart

Generated when a customer removes one or more products from their cart in an organization’s store.

Parameter	Required	Data type	Notes
`store`	Yes	`object`
`store.id`	Yes	`string`	The store ID provided by the platform
`store.platform`	Yes	`string`	The platform the store is hosted on
`store.uuid`	Yes	`string`	The store’s unique identifier in Text system
`store.url`	No	`string`	The store’s URL
`store.name`	No	`string`	The store’s name
`cart_lines`	Yes	`array`
`cart_lines.total_price`	Yes	`string`	Total price for item accounting for its quantity
`cart_lines.currency`	Yes	`string`	The currency code in ISO 4217 format
`cart_lines.quantity`	Yes	`string`	The quantity of the item
`cart_lines.product`	Yes	`object`
`cart_lines.product.id`	Yes	`string`	The ID of the product
`cart_lines.product.title`	No	`string`	The title of the item
`cart_lines.product.sku`	No	`string`	The SKU of the item
`cart_lines.product.variant_id`	No	`string`	The variant ID of the item

Sample store_product_removed_from_cart payload

{
  "store": {
    "id": "my-store",
    "platform": "shopify",
    "uuid": "70cb9e59-b639-41c5-81cf-71db11972cff",
    "url": "https://my-store.myshopify.com",
    "name": "My Store"
  },
  "cart_lines": [
    {
      "total_price": 45.99,
      "currency": "USD",
      "quantity": 5,
      "product": {
        "id": "gid://shopify/Product/123456789",
        "title": "Product Name",
        "sku": "SKU123",
        "variant_id": "gid://shopify/ProductVariant/12345678901234"
      }
    }
  ]
}

messaging

Messaging source includes system events related to messaging activities, such as information about the generation of thread summaries.

summary

Sent when requesting a thread summary in active threads.

Parameter	Required	Data type	Notes
`summary`	Yes	`object`
`summary.text`	Yes	`string`	The generated text summary of the thread
`summary.status`	Yes	`string`	The status of the summary generation process. Possible values: `ok`, `error`.
`requested_by`	Yes	`string`	The ID of the user who requested the thread summary

Sample summary payload

{
  "summary": {
    "text": "• Customer requested pricing details  \n• Support shared relevant information ",
    "status": "ok"
  },
  "requested_by": "019d04f7-8a56-7436-90bd-fb3e5c74170b"
}

System messages

This section lists the system message types generated in the Text ecosystem. In addition to system messages generated by Text, applications can define their own system messages. The content of the system message event is a string stored in the text property, and its format depends on the system_message_type. The variables used to generate the text are specified in the text_vars property. The list of system message types, sorted alphabetically:

Agent

Event	Message	Generated when
`agent_added`	`%initiator% added %agent% to the chat`	An agent is added to the chat via Add User to Chat and is not the first agent in that chat.
`agent_joined`	`%agent% joined the chat`	An agent adds themselves to the chat via Add User to Chat and is not the first agent in the chat.
`agent_left`	`%agent% left the chat`	An agent removes themselves from the chat via Remove User from Chat.
`agent_removed`	`%initiator% removed %agent% from the chat`	An agent is removed from the chat via Remove User from Chat.

Customer

Event	Message	Generated when
`archived_customer_disconnected`	`%customer% left the chat`	The chat ends after a customer leaves the website.
`customer_added`	`%initiator% added %customer% to the chat`	A customer is added to the chat via Add User to Chat.
`customer_banned`	`Chat archived because customer was banned by %agent% for %duration% day(s)`	The chat ends because a customer is banned via Ban Customer.
`customer_removed`	`%initiator% removed %customer% from the chat`	A customer is removed from the chat via Remove User from Chat.
`customer_updated`	`%initiator% has changed customer's name to %customer_name%`	A customer’s name is updated by an agent via Update Customer while the chat is active.
`customer_updated`	`Customer's name has been changed to %customer_name%`	Same as above, but the change was made by an integration.
`customer_updated`	`%initiator% has changed customer's email to %customer_email%`	A customer’s email is updated by an agent via Update Customer while the chat is active.
`customer_updated`	`Customer's email has been changed to %customer_email%`	Same as above, but the change was made by an integration.
`customer_updated`	`%initiator% has changed customer's name and email to %customer_name%, %customer_email%`	A customer’s name and email are updated by an agent in a single Update Customer request while the chat is active.
`customer_updated`	`Customer's name and email has been changed to %customer_name%, %customer_email%`	Same as above, but the change was made by an integration.

Chat

Event	Message	Generated when
`chat_transferred`	`%initiator% transferred the chat to %targets%`	A chat is transferred via Transfer Chat.
`manual_archived_agent`	`%agent% archived the chat`	An agent closes the chat via Deactivate Chat.
`manual_archived_customer`	`%customer% archived the chat`	A customer closes the chat via Deactivate Chat.
`system_archived`	`Chat archived`	The license is moved to another server instance while chats are still active.

Rating

Event	Message	Generated when
`rating.chat_commented`	`%customer% left the following comment: %comment%`	A customer leaves a comment on the chat.
`rating.chat_rated`	`%customer% rated the chat as %score%`	A customer rates the chat.
`rating.chat_rating_canceled`	`%customer% canceled the chat rating`	A customer cancels their chat rating.

Routing

routing.archived

Event	Message	Generated when
`routing.archived_deleted`	`The chat was closed because %agent% account had been deleted`	A chat is archived after an agent is removed from the license, with no other agent available and queues disabled.
`routing.archived_disconnected`	`The chat was closed because %agent% had lost internet connection`	A chat is archived after an agent unexpectedly loses connection, with no other agent available and queues disabled.
`routing.archived_inactive`	`Chat archived due to %duration% minutes of inactivity`	No new messages are posted for an extended amount of time.
`routing.archived_offline`	`Chat archived due to no available agents`	No agent could be selected after the chat was placed in the queue.
`routing.archived_other`	`The chat was closed`	A chat is archived after an agent is removed for other reasons, with no other agent available and queues disabled.
`routing.archived_remotely_signed_out`	`The chat was closed because %agent% had been remotely signed out`	A chat is archived after an agent is remotely logged out, with no other agent available and queues disabled.
`routing.archived_signed_out`	`The chat was closed because %agent% had signed out`	A chat is archived after an agent signs out, with no other agent available and queues disabled.

routing.assigned

Event	Message	Generated when
`routing.assigned_deleted`	`Chat assigned to %agent_added% because %agent_removed% account had been deleted`	A chat is assigned to a new agent after the previous one is removed from the license.
`routing.assigned_disconnected`	`Chat assigned to %agent_added% because %agent_removed% had lost internet connection`	A chat is assigned to a new agent after the previous one unexpectedly loses connection.
`routing.assigned_inactive`	`Chat assigned to %agent_added% because %agent_removed% hasn't replied in %duration% minutes`	A chat is assigned to a new agent after the previous one fails to respond in time.
`routing.assigned_other`	`The chat was closed`	A chat is archived after an agent is removed for other reasons, with no other agent available and queues disabled.
`routing.assigned_remotely_signed_out`	`Chat assigned to %agent_added% because %agent_removed% had been remotely signed out`	A chat is assigned to a new agent after the previous one is remotely logged out.
`routing.assigned_signed_out`	`Chat assigned to %agent_added% because %agent_removed% had signed out`	A chat is assigned to a new agent after the previous one signs out.

routing.idle

Event	Message	Generated when
`routing.idle`	`Chat is idle due to %duration% minutes of inactivity`	No new messages are posted for an extended amount of time.

routing.unassigned

Event	Message	Generated when
`routing.unassigned_deleted`	`Customer was queued because %agent% account has been deleted`	A chat is queued after an agent is removed from the license.
`routing.unassigned_disconnected`	`Customer was queued because %agent% had lost internet connection`	A chat is queued after an agent unexpectedly loses connection.
`routing.unassigned_other`	`Chat is unassigned`	A chat is queued after an agent is removed for other reasons.
`routing.unassigned_remotely_signed_out`	`Customer was queued because %agent% had been remotely signed out`	A chat is queued after an agent is remotely logged out.
`routing.unassigned_signed_out`	`Customer was queued because %agent% had signed out`	A chat is queued after an agent signs out.

Transcript

Event	Message	Generated when
`transcript_requested`	`%customer% requested the chat transcript to be sent to %email%`	A customer enables the chat transcript.
`transcript_sent`	`%customer% sent the chat transcript to %email%`	The chat ends with the transcript enabled by the customer.

​System events

​cdp

​store_order_was_created

​store_product_added_to_cart

​store_product_removed_from_cart

​messaging

​summary

​System messages

​Agent

​Customer

​Chat

​Rating

​Routing

​routing.archived

​routing.assigned

​routing.idle

​routing.unassigned

​Transcript