Bot builder variables let you customize a messaging bot's answers based on data related to a conversation. Messaging metadata variables are a type of variable used in the bot builder that contain information about the current customer's identity and authentication status.
Messaging metadata variables get their values from the signed JSON Web Tokens (JWTs) used for messaging authentication. During a conversation, a messaging bot can use this data to customize its responses, display information specific to the customer, or branch the conversation's flow.
For a broader overview of the bot variables and how you can use them in an answer, see Using variables to personalize bot answers.
Enabling messaging metadata variables
Messaging metadata variables aren't enabled by default. To enable messaging metadata variables, an admin must create a signing key used to generate JWTs for messaging authentication. Messaging authentication and messaging metadata variables are only available for the Web Widget and mobile SDK channels.
For more information about setting up messaging authentication, see Authenticating end users in messaging for the Web Widget and mobile SDK.
Supported messaging metadata variables
|Messaging metadata variable name||Description|
|Provided email||Email address of the customer. This email address is pulled from the JWT used for messaging authentication.|
|Provided name||Name of the customer. This name is pulled from the JWT used for messaging authentication.|
|Authenticated external ID||Unique alphanumeric string that identifies the customer. This ID is pulled from the JWT used for messaging authentication.|
|Authenticated status||If true, the customer is authenticated. Otherwise, false. This
variable is always true or false, never empty.
When using the Authenticated status variable in a Branch by condition step, only the Is operator is supported.
Using the Provided name and Provided email variables
Keep the following considerations in mind when using the Provided name and Provided email variables:
- Messaging bots automatically skip the collection of the Name and
Email variables for authenticated customers in an Ask for
details step. For authenticated customers, these variables are empty
and are skipped in later steps of the conversation. Instead, use the
Provided name and Provided email variables.
Skipped Name and Email variable collection the from Ask for details step Provided name and Provided email variables
- The JWTs used for messaging authentication don't require a customer's name
or email address. If your organization doesn't include a name or email
address in its JWTs, the respective Provided name and
Provided email variable are empty and skipped during a
In such cases, we recommend updating your JWTs to include a name and email address.
- The Provided name and Provided email variables are empty for unauthenticated customers. Avoid using these variables in answer steps for unauthenticated customers.
Using messaging metadata variables with unauthenticated customers
If a customer isn't authenticated, the Authenticated status variable's value is false. Other messaging metadata variables are empty for unauthenticated customers and are skipped during a conversation.
Best practices for using messaging metadata variables
When creating an answer that uses messaging metadata variables, keep the following best practices in mind:
- If you don’t include the customer's name or email address in the JWTs used for messaging authentication, don’t use the Provided name and Provided email variables.
- To build an answer flow that’s available to both authenticated and unauthenticated customers, use a Branch by condition step to check the customer's Authenticated Status variables. Only include messaging metadata variables in branches where Authenticated Status is true.
- If you’re building an answer that’s only available to authenticated customers and your organization's JWTs include a name and email address, use the Provided name and Provided email variables for the customer's name and email address. In such cases, you don’t need to collect this information again using an Ask for details step.