Upcoming Release: Migration of the Text step to Message step

Introducing the new Message step

We're excited to announce a significant update coming in July: the introduction of new Message step and CMS and in Webchat projects. This update will unlock the ability to users to have manage all their agent text responses in a central location, re-use the same message across multiple steps in your agent, and add conditions directly to your response variants. As part of this update, we will be automatically migrating all Text steps to the new Message step.

Key Changes

Introduction of Message Steps:
We are introducing a new type of step called Message along with a new Messages CMS page in webchat projects to manage all your agent text messages. All webchat and voice projects will contain a new property called responseMessages that will replace existing responseVariants.

Automatic Conversion:
All existing Text steps will be automatically converted into Message steps when a project is opened in-app. This migration ensures that all existing functionalities are preserved while providing the benefits of the new system.

Technical Overview

The new Message step structure is outlined below:

Webchat Projects - Properties Affected:

Fields Added: responseMessages
Fields Modified: response now has a new field called type
Fields Removed: responseVariants, responseAttachments, and nodes with type text

Voice Projects - Properties Affected:

Fields Added: responseMessages
Fields Modified: response now has a new field called type
Fields Removed: responseVariants and responseAttachments

Additional Notes:

On webchat projects, all text steps are now messages. Text steps will have a few new features, and all text data will no longer be stored in the node itself but in a new field called response/responseMessages.
On both webchat and voice projects, requiredEntities re-prompts will be attached to response/messages instead of response/variants (variants will be sunset as well).

Example of Message Node Definition

{
  "type": "message",
  "data": {
    "name": "",
    "draft": false,
    "portsV2": {
      "byKey": {
        "next": {
          "type": "next",
          "target": null,
          "id": "unique-port-id"
        }
      },
      "builtIn": {},
      "dynamic": []
    },
    "messageID": "unique-message-id"
  },
  "nodeID": "unique-node-id"
}

Updated Response Structure

{
  "responses": [
    {
      "id": "unique-response-id",
      "name": "Required entity reprompt",
      "createdByID": 22,
      "folderID": null,
      "type": "message",
      "draft": false,
      "createdAt": "2024-07-03T02:29:25.000Z",
      "updatedAt": "2024-07-03T02:29:25.000Z",
      "updatedByID": 22
    }
  ],
  "responseMessages": [
    {
      "id": "unique-message-id-1",
      "discriminatorID": "unique-discriminator-id-1",
      "text": [
        {
          "text": [
            "my reprompt"
          ]
        }
      ],
      "condition": null,
      "delay": null,
      "createdAt": "2024-07-03T01:30:53.000Z"
    },
    {
      "id": "unique-message-id-2",
      "discriminatorID": "unique-discriminator-id-2",
      "text": [
        {
          "text": [""]
        }
      ],
      "condition": {
        "type": "expression",
        "assertions": [...]
      },
      "delay": 10000,
      "createdAt": "2024-07-03T01:19:22.000Z"
    }
  ],
  "responseDiscriminators": [
    {
      "id": "unique-discriminator-id-1",
      "channel": "default",
      "language": "en-us",
      "responseID": "unique-response-id",
      "variantOrder": [
        "unique-variant-id"
      ],
      "createdAt": "2024-07-03T02:29:25.000Z"
    }
  ]
}

Migration Example

To illustrate how the migration transforms Text nodes into Message nodes, here are examples before and after the migration:

Webchat Example

Before Migration:

{
  "type": "text",
  "data": {
    "name": "Text",
    "texts": [
      {
        "id": "text-id-1",
        "content": [{ "children": [{ "text": "My root message " }] }],
        "messageDelayMilliseconds": 10000
      },
      {
        "id": "text-id-2",
        "content": [{ "children": [{ "text": "My first variant" }] }]
      }
    ],
    "canvasVisibility": "preview",
    "portsV2": {
      "byKey": {},
      "builtIn": {
        "next": {
          "type": "next",
          "target": null,
          "id": "unique-port-id"
        }
      },
      "dynamic": []
    }
  },
  "nodeID": "unique-node-id"
}

After Migration:

{
  "type": "message",
  "data": {
    "name": "",
    "draft": false,
    "portsV2": {
      "byKey": {
        "next": {
          "type": "next",
          "target": null,
          "id": "unique-port-id"
        }
      },
      "builtIn": {},
      "dynamic": []
    },
    "messageID": "unique-message-id"
  },
  "nodeID": "unique-node-id"
}

All text data will be saved into responses (responses/discriminator/messages) instead of node data. In message node data, there will only be messageID which references response.id.
repromptID in required entities is a reference to response.id, and its text data is now saved under responseMessages instead of responseVariants.
draft in the message node data means that your message step has no content and will not display the response on the CMS until you have content, so draft is false.

Voice Example

Before Migration

{
	...
  "requiredEntities": [
    {
      "id": "6684b7854986c834e67ee772",
      "entityID": "6642a6fee94258e65e603fdd",
      "intentID": "6642aa05e94258e65e603fe0",
      "repromptID": "6684b7854986c834e67ee76f",
      "createdAt": "2024-07-03T02:29:25.000Z"
    }
  ],
  "responses": [
    {
      "id": "6684b7854986c834e67ee76f",
      "name": "Required entity reprompt",
      "createdByID": 22,
      "folderID": null,
      "type": "message",
      "draft": false,
      "createdAt": "2024-07-03T02:29:25.000Z",
      "updatedAt": "2024-07-03T02:29:25.000Z",
      "updatedByID": 22
    }
  ],
  "responseDiscriminators": [
    {
      "id": "6684b7854986c834e67ee770",
      "channel": "default",
      "language": "en-us",
      "responseID": "6684b7854986c834e67ee76f",
      "variantOrder": [
        "6684b7854986c834e67ee771"
      ],
      "createdAt": "2024-07-03T02:29:25.000Z"
    }
  ],
  "responseVariants": [
    {
      "id": "6684b7854986c834e67ee771",
      "conditionID": null,
      "discriminatorID": "6684b7854986c834e67ee770",
      "attachmentOrder": [],
      "text": [
        {
          "text": [
            "my reprompt"
          ]
        }
      ],
      "speed": null,
      "cardLayout": "carousel",
      "createdAt": "2024-07-03T02:29:25.000Z",
      "type": "text"
    }
  ],
  "responseAttachments": [...],
}

After Migration

{
	...
  "requiredEntities": [
    {
      "id": "6684b7854986c834e67ee772",
      "entityID": "6642a6fee94258e65e603fdd",
      "intentID": "6642aa05e94258e65e603fe0",
      "repromptID": "6684b7854986c834e67ee76f",
      "createdAt": "2024-07-03T02:29:25.000Z"
    }
  ],
  "responses": [
    {
      "id": "6684b7854986c834e67ee76f",
      "name": "Required entity reprompt",
      "createdByID": 22,
      "folderID": null,
      "type": "message",
      "draft": false,
      "createdAt": "2024-07-03T02:29:25.000Z",
      "updatedAt": "2024-07-03T02:29:25.000Z",
      "updatedByID": 22
    }
  ],
  "responseMessages": [
    {
      "id": "6684a9cc3ad70f045227d820",
      "discriminatorID": "6684a9cc3ad70f045227d81f",
      "text": [
        {
          "text": [
            "my reprompt"
          ]
        }
      ],
      "condition": null,
      "delay": null,
      "createdAt": "2024-07-03T01:30:53.000Z"
    },
     {
      "id": "6684a71a3ad70f045227d810",
      "discriminatorID": "6684a7173ad70f045227d807",
      "text": [
        {
          "text": [
            ""
          ]
        }
      ],
      "condition": {
	      "type": "expression",
	      "assertions": [...]
      },
      "delay": 10000,
      "createdAt": "2024-07-03T01:19:22.000Z"
    },
  ],
  "responseDiscriminators": [
    {
      "id": "6684a9cc3ad70f045227d81f",
      "channel": "default",
      "language": "en-us",
      "responseID": "6684b7854986c834e67ee76f",
      "variantOrder": [
        "6684b7854986c834e67ee771"
      ],
      "createdAt": "2024-07-03T02:29:25.000Z"
    }
  ],
}

repromptID in required entities is a reference to response.id, and its text data is now saved under responseMessages instead of responseVariants.
draft in the message node data means that your message step has no content and will not display the response on the CMS until you have content, so draft is false.

Next Steps

As we approach the completion date of this project, we will announce the exact release date for this migration. We encourage all users who rely on the Voiceflow project export file to familiarize themselves with these changes to leverage the improved functionality and design flexibility in their agents. As always, our support team is available to assist with any questions or issues related to this migration.