# Welcome! Welcome to the official Xenioo 1.0 documentation website. The aim of this website is to document and illustrate as clearly as possible each and every action, operation, variable and option you may encounter during your journey into chatbot building. Please use the menu you can see on the left of this page to pick a topic and navigate to to what interest you. The Xenioo team is also regularly publishing [new videos](https://www.youtube.com/channel/UCW5D9M1vSKrTuenVR0whOVA), [articles](https://www.xenioo.com/en/articles/) and [tutorials](https://www.xenioo.com/en/tutorials/) on very specific topics. Often giving away full examples and complete chatbots. You are more than welcome to join our [growing Facebook group](https://www.facebook.com/groups/xenioo) to share your ideas, doubts and issues and, of course, your feedback. For any inquiry, information or support service you can reach our customer support service by contacting . # Your Account Xenioo offers a number of upgrade paths that will allow your chatbot to grow together with your business requirements. Not just pre-made plans but fine-tuned solutions for all your needs. # The Free plan Your first signup to Xenioo will be as a free account, by default. **We strongly believe in the power of trying and testing** each and every feature and we are sure that after trying and understanding the power of Xenioo you will choose the [upgrade path that suits you most](https://www.xenioo.com/en/pricing/). ### **Duration of the Free Account** The free account **never expires**. You're welcome to try and use Xenioo with your free account for as long as you wish. If your requirements fall within the limitations of our free account offer, you're welcome to use Xenioo for as much as you want. {% hint style="danger" %} Please note that we may, from time to time, decide to delete old accounts that are not active and are not using live chatbots. If your account will fall into this group you will receive an email alert and you will be able to reset your account state by simply logging on. {% endhint %} ### Testing premium chatbot features Each and every Xenioo chatbot action is free to be tested and tried with your free account. Sometimes, while designing your chatbot, you will encounter some actions marked as premium: **these actions can be used and previewed at will** from a free account but will require a paid plan to be used in a live chatbot. ![](/files/-LdYzKL9aRcOgeTyVLB7) {% hint style="info" %} Simply put: **you're free to use these advanced actions and integrations for as much as you want but not in a live, published chatbot**. {% endhint %} To use these premium features in a live chatbot (published on Facebook, for example), you [will need to upgrade](/basic-concepts/your-account/upgrading-from-free). # Upgrading to a paid plan Whenever you want you are welcome to[ upgrade to a paid plan](https://www.xenioo.com/en/pricing/) to unlock additional features, chatbots and messages. ![](/files/-MJCNjUcJ-8gUqiOvyGq) All you need to do to upgrade to a paid plan is to select the one that best suits your business and proceed to payment. {% hint style="info" %} **Payment is not processed at the moment of your upgrade**. You will be charged next month accordingly to our [billing cycle](/basic-concepts/your-account/payment-and-invoicing). {% endhint %} Xenioo uses [Stripe](https://stripe.com/) as a unique payment gateway as we believe it offers the most secure and best payment experience for our customers. **All of the major credit cards are supported and accepted**. You can [cancel your paid plan or any additional package whenever you want](/basic-concepts/your-account/cancelling-your-subscription). Just pay attention to our [payment cycles](/basic-concepts/your-account/payment-and-invoicing) and keep in mind that some of your chatbots may stop working correctly after downgrade if any premium feature is being used. ## Updating your payment information If your credit card changes or expires you will need to update your payment information inside Xenioo. If by the end of the month your payment processing fails we may proceed to unpublish your bot and, eventually, to fully lock your account. To update your payment information: * Log in to your Xenioo account * Click on you Avatar icon, on the top left corner of the page * Click on "Account" * Click on "Active Subscription" on the left menu * Below your current active plan value, click on "Update your Billing and Payment Information" ![](/files/-LpX_Et7IjIIZq2P-pY8) * On the dialog that appears you can change your billing information. Clicking on "Update Card Details" you can change your credit card information # Canceling your subscription You can cancel your subscription with any Xenioo paid plan anytime you want. Just follow the steps below: * Login to your Xenioo account * Click on your avatar icon, on the upper right corner of the page * Select "Account" * Click on "Active Subscription" on the left menù * You should now see your active paid plan and packages. * Cancel your plan or remove the package you don't need anymore. ![](/files/-LpXY_kY4KgLibFtoVSp) You can cancel your full plan or remove single packages. {% hint style="warning" %} Please note that your canceled paid plan or package will be removed immediately. **If you cancel a paid plan, you will be downgraded to the Free plan**. {% endhint %} At the end of the month, you will **receive one last invoice for the current month's usage**. So for example, if you cancel your Starter plan on November 15, you will be charged for the 15 days the plan was still active. Seeing you go is a sad moment for us but if you've found something better or anything you don't like we're sure we can improve! If you've decided to cancel your account please [let us know why](mailto:team@xenioo.com) and maybe we can help each other! # Deleting your account It is possible to fully delete your Xenioo account. Canceling your account means that all your account information as well as chatbots, conversations and any other data associated with your account, will be deleted forever. {% hint style="danger" %} It is NOT possible to delete an account that has yet any active paid subscription. Any account that still has an unpaid subscription fee must wait until the end of the billing cycle before attempting to delete. **This action cannot be undone! Once your account is deleted there is no way to get it back.** {% endhint %} In order to delete your account, just follow the steps below: * Login to your Xenioo account * Click on your avatar icon, on the upper right corner of the page * Select "Account" * Click on "Delete Account" on the left menu ![](/files/-M5SNDcrGY2VabKoPibU) Once your account is canceled, you should still manually unsubscribe from the Xenioo mailing list to stop any further communication coming from Xenioo. # Additional Packages Xenioo can grow together with your business needs without forcing you to scale on things you don’t use. As you progress, you can further expand your Starter or Professional plan by adding additional upgrade packages that can increase just about anything from the number of bots to your monthly message limit. ![](/files/-Ld_mptAacEP1J3nWesN) Every additional package you add is immediately effective on your account and available to all your chatbots. If you later change your mind you can cancel any package whenever you want. Just pay attention to our [payment cycles](/basic-concepts/your-account/payment-and-invoicing) and keep in mind that some of your chatbots may stop working correctly after downgrade if any premium feature is being used. # Support Xenioo offers continuous support through our customer care service. If you have any questions or facing any issues you're welcome to contact us at . Our systems are automatically queuing every request by account type. Please note that, while we try to reply to every request in the fastest possible way, **free account requests that are not related to critical software or platform issues are automatically queued after paid accounts**. Depending on the current queue size and active paid account requests, a free account inquiry can take up to 5 working days. {% hint style="info" %} Premium account issues are taken into consideration within the next working day and contact with you will be carried on immediately. Premium support is available in any [paid account](/basic-concepts/your-account/upgrading-from-free). Paid accounts support is carried on during the standard working week and standard daily shift. {% endhint %} If your chatbot requires additional, continuous support or oversee please contact us to arrange a specific quote for your required service levels. ### Private Chatbot Support and Counseling The Xenioo team is also offering direct counseling and direct design support through dedicated, personalized Slack channels or Skype. If you may need this type of service please feel free to reach us at the email address above for a quote tailored for your needs. If you need a full chatbot project from the ground up don't hesitate to get in touch with us. Be sure to provide a rough flow diagram of your desired chatbot and our development team can follow up with a full project estimate. We will follow your project from the creation to the deployment and maintenance. # Payment & Invoicing Active paid account **payments are always processed on the 1st day of every month**. Xenioo will generate automatically a billing request on the card you've used to upgrade your account and will forward an invoice notification to your account email. {% hint style="warning" %} **As you upgrade your account, no payment is processed until the 1st day of the following month**. **The same applies if you cancel a paid plan or remove an upgrade package**. {% endhint %} For example, if you upgrade your account or add a new package on the 20th of November, you will not pay for the upgrade until the 1st of December and you will be charged for the days your plan or package was active in November. If on the 10th of December you change your mind and cancel your plan or remove a package, you will not pay until the 1st of January and you will be charged for the days your plan or packages was active in December. All paid invoices are listed inside your account section, under the invoices page. From there you will be able to download the full invoice for your monthly payment. If you are the owner or represent an Italian based company, we will also automatically generate and forward to [SDI ](https://www.fatturapa.gov.it/)a full electronic invoice instance targeted to your invoice unique code or to your certified email address(PEC). If you have any doubt or need any further information related to payment & invoicing please feel free to contact [our support service](/basic-concepts/your-account/support) anytime. ### Missing a payment If for any reason your payment method is declined by our gateway your account will be immediately notified on the email address you've configured as your billing contact. After the first notification you have **5 days** to login and update your billing details so that Xenioo can reprocess any pending payment. After the first fail, Xenioo will automatically retry to process your account payment again the next day. If after 5 days the payment is still pending, Xenioo will automatically lock your account and take offline any active channel. You can still login freely and change your billing details so that your pending payment is successful. After 90 days of inactivity of a pending account like this, Xenioo will automatically delete any data related to chatbots and conversations. # Messages Count One of the main counters of your account is the Messages Count. As you move upward from [free to professional or agency plan](/basic-concepts/your-account) you will see the available messages pool greatly increased. Xenioo messages are used as a means of counting how much your chatbot is used and are, most of the time, directly determining the cost of your chatbot. In the following paragraph, we will explore how this counter is affected by messages, operations, and integrations. ### Standard Messages Very simply: every time your chatbot replies to any of your users, we count one message. A single bot reply may be comprised of multiple elements: for example, it could be made of two text lines and three quick buttons: all the block is still counted as one message by Xenioo. In the image below, your chatbot is displaying a single line of text. **This is counted as one message**. ![](/files/-Ld_rlnIfshItjX0MjtW) In the image below instead, your chatbot is displaying 2 bubbles and 4 buttons. **Still, this is counted as one message**. ![](/files/-Ld_rjg19G_wCQc-tvQC) **For both cases, Xenioo will count just one message**. After you publish your bot, pay close attention to its real-time statistical dashboard and follow closely its success verifying how many messages are used daily. **Message count has no impact on how you build your** [**Interaction**](/basic-concepts/the-chatbot-designer/interactions_concepts) **(**Interactions define a group of actions but do not affect how messages are counted). {% hint style="info" %} **Any message sent or received inside the preview section, where you test and try your chatbot before publishing, DOES NOT count toward your paid account messages.** {% endhint %} ### Action Messages Any action that requires integration with external sources to retrieve or synchronize data will increase your messages counter by 1 upon execution. Any external web service or API call, any [Firebase ](https://www.xenioo.com/en/using-firebase-cloud-data-with-your-chatbot/)or [DialogFlow or IBM Watson ](https://www.xenioo.com/en/integrating-ibm-watson-assistant-nlp-with-xenioo/)integration will increase your message counter as well. A chatbot that retrieves data from an API REST endpoint and displays the result to the user will, at least, consume 2 messages from your account quota. Please note that the message is counted as the action executes and not if any result is produced. For example, a broadcast sending news to multiple users based on the results of an [API call](/actions-and-operations/integration/xenioo.bots.actions.base.callapiserviceaction) or [RSS feed](/basic-concepts/publishing/channels/facebook/feed-integration) may not send any message until there's an actual news but still be executed by Xenioo multiple times each day. All of these executions will add to your premium counter. All of these actions stated below will generate an additional message during chatbot execution. | Action | Mode | | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | [IBM Watson Input and Detection](/basic-concepts/the-chatbot-designer/actions_and_operations) | One additional message for each message evaluation, regardless of number of actions | | [Dialogflow Input and Detection](/basic-concepts/the-chatbot-designer/actions_and_operations) | One additional message for each message evaluation, regardless of number of actions | | [API Service Action](/actions-and-operations/integration/xenioo.bots.actions.base.callapiserviceaction) | One additional message per action. | | [Cloud Script Action](/actions-and-operations/integration/xenioo.bots.actions.base.executescriptaction) | One additional message per action. | | [Zapier Webhook Action](/actions-and-operations/integration/xenioo.bots.actions.base.integrations.zapierwebhookaction) | One additional message per action. | | [Firebase Document Action](/actions-and-operations/integration/firebase-database-action) | One additional message per action. | | [Mailchimp List Action](/actions-and-operations/integration/xenioo.bots.actions.base.integrations.mailchimplistaction) | One additional message per action. | | [ActiveCampaign Action](/actions-and-operations/integration/xenioo.bots.actions.base.integrations.activecampaigncontactaction) | One additional message per action. | | [Post To Facebook Action](/actions-and-operations/integration/xenioo.bots.actions.base.integrations.facebookposttopageaction) | One additional message per action. | | [Sendgrid Mail Action](/actions-and-operations/integration/xenioo.bots.actions.base.integrations.sendgridmailaction) | One additional message per action. | | [Wordpress Search API Action](/actions-and-operations/integration/xenioo.bots.actions.base.integrations.wordpresssearchaction) | One additional message per action. | | [Send Mail Message](/actions-and-operations/integration/xenioo.bots.actions.base.sendmailmessageaction) | One additional message per action. | | [Send Custom Mail Message](/actions-and-operations/integration/xenioo.bots.actions.base.sendcustommailmessageaction) | One additional message per action. | | [RSS & Podcast Feed Action](/actions-and-operations/integration/xenioo.bots.actions.base.rssfeedreaderaction) | One additional message for each analyzed feed source. | | [Database Actions](/actions-and-operations/database) | One additional message for each action that changes a database collection(save, delete) | {% hint style="warning" %} **Time Out** Xenioo API Actions have by default a 10 seconds timeout. If you require a higher timeout please make sure to get in touch with us at . When the timeout is increased, any call using more than 30 seconds will *count for an additional premium message*. {% endhint %} ### Events Webhook The [Events Webhook](/basic-concepts/chatbot-details/chatbot-settings/integration#conversation-webhook-url) will automatically transfer to a provided hook URL multiple events happening on Xenioo backend for a specific chatbot. [Calls to this hook](/basic-concepts/chatbot-details/chatbot-settings/integration#conversation-webhook-url) count as messages outgoing and will be summed to your account messages count. ### Ending your monthly messages Message counters are reset on the 1st day of every month. Xenioo will automatically send you the first message whenever your messages usage will rise above 80% and a second one when it reaches 90%. If you finish the number of available messages before the end of the month, your chatbots will stop replying to your users as they don't have any more messages to use. You can add more messages to your account by simply adding additional packages or switching to an unlimited message model by adding the [no-limits](https://www.xenioo.com/en/pricing/) package that can bill every message outside your standard messages count separately. The no-limits option can prove very useful if you have chatbots that can have high traffic only in specific months during the year. # Designing your Chatbot Designing is one the core steps of your chatbot creation. Take your time to grasp the concepts of the advanced Xenioo approach and get the most of our design flow. # Introduction When you build a chatbot using Xenioo, there are some basic concepts that you will see repeated multiple times and that need to be understood to navigate your flow design. Your chatbot is basically split into multiple layers. Each layer details more and more specifically a unique functionality. The highest layer is the *behavior*. A Behavior is, generally speaking, how your chatbot handles a specific situation. A behavior of your chatbot for example, may be called "Feedback Management" and handle everything related to receiving feedback from a user. Inside each behavior, we find one or more *Interactions*. Interactions define the steps of your chatbot behavior and contain information of how exchanges with your users happens. Each interaction will then contain one or more action. Each action defines a minimal unit containing a single step of a greater interaction. A single action can be, as an example, a speech bubble or a button or an image. Lastly, each action may have one or more operations attached. As the user interacts with your chatbot actions certain events can be fired such as the redirections of the flow to another behavior: all of these additional events are operations. {% embed url="" %} # Behaviors The highest abstraction layer of your chatbot flow is the behavior. A Behavior is, generally speaking, how your chatbot handles a specific situation. A behavior of your chatbot for example, may be called "Feedback Management" and handle everything related to receiving feedback from a user. You are not force to create multiple behaviors in your chatbot as much as you are not forced to create your chatbot using only one: it is up to you to choose how to organize your flow and your conversation parts. You can also change your mind later on and group all interactions into a single one or split them into multiple behaviors using the move command. When you create a new chatbot, Xenioo will automatically create for you your very first and basic Behavior. ![](/files/-LdPJUSKKbIGXrHXiogB) Looking at the default behavior image above, we can see all of the main fields and functionalities by number: 1. This is the behavior name. You can change the name to anything you want anytime. This selection list will also, in time, hold the full list of all your chatbot behaviors. 2. Using this button you can anytime add a new behavior to your chatbot. New behaviors will always be created with the two empty interactions you see. 3. This cog icon button will slide in the right panel and display the current behavior details. In the picture you already see the right panel displayed. 4. These are name and description of the selected behavior. You can change them anytime to anything that help you organize or better remember your chatbot functionalities 5. This flag makes the current behavior the start behavior. The start behavior is the entry point of your chatbot and it is where the conversation will start. Only one behavior per chatbot can be marked as the start one. 6. This code is your chatbot API Token. Behavior API tokens can be used by external integrations and other utilities to refer to your chatbot and to this specific behavior. 7. The Add Interaction button let you add a new interaction to the current behavior. 8. The Add Operation button lets you add a [global behavior operation](/actions-and-operations/execution) to the current behavior. Refer to the actions and operations information to know which operations can be added and how. There is no limit to the number of behaviors a single chatbot can contain. # Interactions Interactions define the steps of your chatbot behavior and contain information of how exchanges with your users happens. Each interaction will then contain one or more action. Each action defines a minimal unit containing a single step in of a greater interaction. A single action can be, as an example, a speech bubble or a button or an image. We can add a new Interaction to our design by using the Add Interaction button on the behavior detail panel. Clicking on any interaction or on the small cog button on the top right of the Interaction box will reveal a number of options and details. ![](/files/-LdPJkWP_Avm3y6rftw_) 1. This is the Interaction name. You can change it anytime to anything you like. 2. This flag marks the interaction as the start one. The start interaction in a behavior is the default interaction of the behavior if no interaction is specified for a specific operation. 3. The Fallback Interaction flag marks the selected interaction as the fallback for the selected behavior. The fallback interaction is engaged every time your chatbot encounters an error or something it cannot manage. Although an interaction can be both Start and Fallback we strongly advise to keep these two types separated. 4. The Enable User Chat flag is marked by default and specifies if the user can write something while the chatbot is in the selected interaction. Not all channels support disabling the message area: those channels will just ignore the flag. 5. Use the "Add Action" button To add a new action to the selected interaction. Actions can have different effects and display different informations to the user. 6. You can completely duplicate the selected interaction with all included actions and operations using the "Clone" button 7. Using the "Move To..." button you can choose to move the selected interaction to a another behavior or even to a new behavior. All dependent interactions will be moved and all attached or referenced "Go To" actions will automatically adjusted for you. There is no limit to the number of interactions a single behavior can contain. {% hint style="warning" %} The enable user chat flag may have no effect on a particular channel. Please make sure that your target channel supports this kind of feature before relying on it for your flow. {% endhint %} ### The Start Interaction The start interaction is the very first interaction that gets executed by the chatbot when no specific interaction is selected. In the chatbot default [Behaviour ](/basic-concepts/the-chatbot-designer/behaviours_concepts)it will be the very first thing that your chatbot will do for the user. You can change the default interaction anytime by clicking on another interaction and selecting the Start Interaction toggle in the Interaction details on the right panel. A behaviour must have one and only one start interaction. if you remove the Start Interaction flag from an Interaction, Xenioo will randomly pick another Interaction to be the start one. ### The Fallback Interaction The Fallback Interaction is executed every time your chatbot cannot process and input or an user event. For example if the user says "hello" and [no input](/actions-and-operations/input) or [global detection](/actions-and-operations/input/global-detection) catches the text, Xenioo will redirect the output to this Interaction. {% hint style="info" %} After the Actions contained inside the Fallback Interaction are executed, Xenioo will automatically redirect the flow to the Interaction where the Fallback was triggered. You can of course change this behaviour by adding a [Go To](/actions-and-operations/flow/xenioo.bots.actions.base.gotointeractionaction) action inside the Fallback Interaction that redirects where you want. {% endhint %} A behaviour must have one and only one fallback interaction. if you remove the Fallback Interaction flat from an Interaction, Xenioo will randomly pick another Interaction to be the fallback one. To force your chatbot to restart whenever something unexpected happens you may want to have an interaction to be both Start and Fallback. Although possible, this is not recommended as it may lead to odd flow redirection patterns during execution.\ A better approach is to redirect the user to a more dedicated handler or to manually [Go To](/actions-and-operations/flow/xenioo.bots.actions.base.gotointeractionaction) the designated Start Interaction. # Actions and Operations Each of your chatbot [interactions ](/basic-concepts/the-chatbot-designer/interactions_concepts)can contain one or more action. Each action defines a minimal unit containing a single step in of a greater interaction. A single action can be, as an example, a speech bubble or a button or an image. Generally speaking instead, an operation is an action that results from the triggering of the parent one. For example a button action can trigger a Go To operation or a Switch action can trigger variable change operation. Since there's no virtually limit to the type of actions and operations your can mix and match there's also no limits to the complexity of the chatbot you are going to build. You are not limited by a complex set of pre-defined options but you are instead building the execution of your flow using smaller and more configurable parts. As you click on an action inside an operation you'll be presented with a detail panel that may look like the one in the picture below. ![](/files/-LdPJpr-swv0NjQHgMxh) 1. These arrows display flow direction. If the action redirects to another interaction you will see arrows describing visually the conversation flow. 2. In this area you will find all fields and options required to configure the selected action. Different actions will have, of course, different fields. 3. This small box will display the event that the action may fire. A button for example (or Quick Reply as it is called) may have a "On User Click" while an input action may have "On User Input". As the action activates the trigger all child operations are evaluated and executed. Not all actions have a trigger so not all actions may contain child operations. 4. This button will display the operations selection dialog. Not all actions can trigger operations so not all action will have this button available. 5. This is the operation header. Clicking on the operation header will shrink it: this is particularly useful when an action has many attached operations. Each operation can be shrunk or expanded independently. 6. This is the operation delete button. Use this button to remove the operation from the action. All operations that are child of this operation will be removed. If your operation is lower in the operations list, an Up or Down button can be used to move the operation up or down the queue. 7. These small icons will display a warning related to specific channel limitations. Using Xenioo you can create a chatbot that lives simultaneously on multiple platforms but some of them may not support some specific actions. If an action as a red icon for a channel it means that it is not supported while an orange icon indicate some kind of limitation. You can hover the specific icon to visualize an additional tooltip. Each action and operation has, of course, its own defining fields: refer to our complete actions & operations guide for all the details. # Chatbot Details Your chatbot has multiple default settings that can be changed as well as a full team and operators management section you can oversee directly as a standard team or pro team user. # Chatbot Settings The settings page of your chatbot allows you to change or review many global aspects of your chatbot. You can find in the following pages a full reference of all the fields and configurations. ### # General Chatbot Settings The settings page of your chatbot allows you to change or review many global aspects of your chatbot. ### Bot Name This is the name of your bot inside Xenioo. Your chatbot may actually have a completely different name on other platforms depending for example on the page name for Facebook or on the bot name for telegram. The name you choose here is just for your reference inside Xenioo. You can, however, retrieve the the value specified here at runtime by accessing the bot\_name variable. ### Bot Description This is a general description of the chatbot. It can be whatever you like. ### Enable Type Speed This flag will either turn on or off type speed simulation for your chatbot. If this flag is enabled, Xenioo will automatically add idle indicators to your chatbot text bubbles to simulate someone typing instead of immediately send all data to the chat window. ### Words Per Minute This is the amount of words per minute that your chatbot will be able to write if the *Enable Type Speed* flag is enabled. We recommend to use a number much higher than standard, human capable typing speed as the final user can easily move away while waiting for content to appear. ### Avatar You can upload your chatbot avatar here. This image will be used in the global chatbot list page and as default avatar in the Web Channel configuration. Other channels will still be using the avatar image that is chosen on the specific channel configuration (e.g. Facebook will still use your page avatar).\ *Please note that free accounts cannot upload a customized avatar image.* # Chatbot Conversation Settings The settings page of your chatbot allows you to change or review many global aspects of your chatbot. ### Enable Automatic Read This flag will automatically set a conversation as read whenever you click on it. If you set it to false, you will need to mark it manually as read whenever you wan to do so. ### Hidden Variables This area contains all the names of the variables you would like to hide from the [Conversations Variable Panel](/conversations/general). Variable names can be separated on multiple lines or by commas or semicolon.\ Basic wildcard notation is accepted: to hide all variables starting by ***test*** you can specify **test\*** in the list. ## Shared Conversation ### Share Logo This image will be shown on the top left corner of every [shared conversation](/actions-and-operations/flow/create-conversation-url-action) url your chatbot is using. ### Share View Style This style sheet will be applied to the shared conversation layout when the conversation is in **view mode**. If left empty, the default Xenioo style will be applied. ### Share Take Over Style This style sheet will be applied to the shared conversation layout when the conversation is in **take over mode**. If left empty, the default Xenioo style will be applied. {% hint style="info" %} When personalized, style sheets will fully overwrite the default Xenioo styles. Make sure to include all of the classes and subclasses required. {% endhint %} ### Extended Conversation Variables Panel Using these custom fields you can add a new custom tab inside the [conversation variables panel](/conversations/filtering). The custom tab will display a custom url of your choice. The custom url can reference any conversation variable that your chatbot may have collected. # Chatbot Integration Settings The integration settings page of your chatbot allows you to change or review many global aspects of your chatbot. Additional integrations are available as actions on your chatbot flow. ### API Token This code represent your chatbot API Token. Depending on the different outside integrations you will use you may need it to call specific Xenioo API related to your chatbot. ### API Secret This code is the API Secret used in various real time integrations meant to directly access data of your Account or Chatbot. ### Events Webhook URL In the Events Webhook field you can specify a webhook url that will receive all of the messages that are sent and received by Xenioo for the current chatbot as well as different events you can enable or disable at will. ![](/files/-MKp-IVtMwSWMs_6sq-y) When the Webhook is activated, Xenioo will automatically send any of the selected events generated by your chatbot **every 20 seconds**. {% hint style="warning" %} The Events Webhook is **not** intended as a real-time communication API relay as the average interval for events signal is 20 seconds. This means that all events happened in a conversation will be grouped and sent to your hook **with a 20 seconds delay**.\ If you are looking to build an alternate view based on real-time conversation events please refer to our [Custom Channel](/basic-concepts/publishing/channels/customchannel) solution {% endhint %} The Webhook payload is always an array of items similar to the example below: ``` [ { "Type": 0, "ItemType": "Text", "Data": "Hey you, I'm your chatbot!", "Date": "2019-07-10T15:47:58.580873+00:00", "BotToken": "...", "AccountName": "Matelab Srl", "ConversationId": "...", "UserName":"conversation user name", "Channel": "TelegramChannel" }, { "Type": 1, "Data": "Hello there!", "Date": "2019-07-10T15:47:58.5750058+00:00", "BotToken": "...", "AccountName": "Matelab Srl", "ConversationId": "...", "UserName":"conversation user name", "Channel": "TelegramChannel" }, { "Type":3, "BotToken": "...", "AccountName": "Matelab Srl", "Name":"Intent Name", "Key":"Intent Key" }, { "Type":7, "BotToken": "...", "AccountName": "Matelab Srl", "Text":"Missed AI Text" }, ] ``` Each array entry can have the following fields: | Field | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Type | The type of entry, according to the table below. | | ItemType | The item specific [visual type](/actions-and-operations/integration/xenioo.bots.actions.base.dynamicreplyaction). | | ItemSubType | The subtype of the item specific [visual type](/actions-and-operations/integration/xenioo.bots.actions.base.dynamicreplyaction). | | Data | The content of the message. It can be either the text sent by the user or the message sent by the chatbot. If the user clicks a button this field will contain both its text and its payload. | | Date | The exact date of the message | | BotToken | The unique bot token associated to the chatbot generating the item | | AccountName | The full name of the account generating the item | | ConversationId | The Id of the conversation associated to this item | | Channel | The name of the channel that generated the item | | Text | The text that was not detected by Xenioo AI | | Name | The name of the Intent or Entity related to the event | | Key | The key of the Intent or Entity related to the event | Message type can have one of the following values: | Value | Type | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | Chatbot chat message | | 1 | User chat message | | 2 | A conversation error has occurred | | 3 | An intent was updated | | 4 | An intent was deleted | | 5 | An entity was updated | | 6 | An entity was deleted | | 7 | A user chat message was not detected by Xenioo [Automatic Intent Redirection](/ai/intents#activation) | | 8 | New user connected to the chatbot. The user has never contacted the chatbot before (or has been [forgotten](/actions-and-operations/privacy/xenioo.bots.actions.privacy.privacyforgetuseraction)). | | 9 | A user returned to talk with the chatbot. This event is fired only once every 24 hours even if the user comes back multiple times during the day. | | 10 | Take Over happened | | 11 | Hand Over happened | | 12 | The conversation hit a fallback interaction | | 13 | The conversation hit a wrong question reply | The expected Webhook reply must be a standard HTTP 200 OK. The reply body can be empty.\ If your Webhook fails to correctly reply or is unreachable for more than 10 times Xenioo will stop any further call and alert your account. To re-enable the Webhook simply save again the chatbot settings.\ A failing Webhook will also trigger an alert email to the account email directly related to the chatbot.\ \ Each message sent to your chatbot by a user or delivered by your chatbot to any user will be queued and delivered to your hook at a latency of maximum 20 seconds. This feature is used on your bots as long as you have an [active paid subscription](/basic-concepts/your-account/upgrading-from-free). Each call to your hook will [count as an additional outgoing message](/basic-concepts/your-account/messages-count). Xenioo will consider one single outgoing message regardless of the amount of in and out messages sent to the hook in each single push. So for example if a hook call contains 30 messages that will still count as only one additional outgoing message. The specified Webhook is ignored if your bot is running under a free plan. # Teams The Team section is an incredibly powerful feature of Xenioo that puts you in charge of who and how any additional user may access your chatbot design or features. Using the Team section you can invite new user to work on your chatbot. Multiple users can simultaneously work on different areas of your chatbot like conversations and AI. A user may work on testing the AI NLP section while multiple team members may access the conversation section giving support to directly controlled users. {% hint style="warning" %} While multiple users can access and work on different sections of your chatbot only one user can work on chatbot design at any given time. \ Multiple team members simultaneously working on the very same chatbot at the very same time may lead to unwanted loss of data. {% endhint %} Chatbots that are shared to you are not seen together with your account chatbots. You will be able to switch to different workspaces depending on the different number of accounts sharing chatbots with you.\ \ The number of team members that your account can invite on each chatbot depends on your current account active plan and can be changed by either [subscribe to a paid plan or by adding an additional team oriented package](https://www.xenioo.com/en/pricing/). ### Adding a new Team Member To add a new team member simply specify the member email and press confirm. The team member will be automatically created and an invitation e-mail will be sent. The team member will not be active until the invitation letter is accepted or the member logs in to a valid Xenioo account. As the invited member accepts your invitation he/she will be able to fully access your chatbots conversations, design, AI, reports and publishing capabilities. If available for your subscription plan, team members creation and management can also be customized directly using [Global Platform API](/xenioo-api/globa-platform-api) interface. ### Offline and Online Operators Xenioo automatically updates users login and logout to maintain, for every live chatbot, a full list of online operators. ### Further Reading The following article from the official Xenioo blog details additional use cases for the Teams section. {% embed url="" %} ### # Team Permissions The [Pro Team package](/basic-concepts/your-account/additional-packages) can enable a number of permissions for each and very member of your team allowing you to fine-tune you chatbot access. Right after [adding the Pro Team package](/basic-concepts/your-account/additional-packages) to your account every chatbot teams section will expand to reveal a number of possible permission you can apply to each member. These settings can be added or removed from existing members anytime, even if the members were created using a standard team package.\ \ The table below gives you a full description of all the possible settings | Permission | Description | | :----------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | View Chatbot Design | The user can access the general chatbot design flow. A user with only this permission will not be able to change any of the chatbot flow, actions and settings and will not be able of publishing the current version of the chatbot. | | Edit Chatbot | This permission includes the previous adding also the ability to change by adding, moving or deleting any part of your chatbot flow. | | Publish Chatbot | The user can publish the current version of the chatbot and push it online on the selected channels. Some channels may still require an additional login with the target platform account | | Backup Chatbot | The user can create a backup of your chatbot and download it on its own system. The chatbot can then later be used to restore a previous version or be restored in a different account and modified. | | View AI | The team member can access the AI section and overview each and every intent, expression and entity. The user can also view the AI detection logs and check the correctness of the current configuration in the Test & Train section. | | Edit AI | The user can edit, update and remove any intent, expression or entity. Using automatic redirection the user can may also slightly change the chatbot dialog results or flow. | | View Broadcasts | This permission allow access to the broadcasts section. The user can view and check broadcasts scheduling and delivery but cannot send or change anything. OnDemand broadcast can stil be invoked trough URL as no contextual user is applied to the REST call. | | Run Broadcasts | The user with this permission can run any broadcast at any time independently from scheduling. This flag enables the global broadcast play button available in the global broadcasts list. | | Edit Broadcasts | With this permission enabled, a user can change any broadcast. Both activation and scheduling and general conversation flow can be changed at will. | | View Conversations | A user with this flag enabled can access the conversation section and read any user conversation that happened with the chatbot. | | View Group Conversations | With this flag enabled, a user will be able to view **only** the conversations that are associated with his/her group. If the user is not part of any group, **no conversation will be visible**. | | Assign Conversations | This user can assign conversation to other operators (users that can access the conversation and take control). This flag is typically associated with a support manager profile. | | Control Conversation | This flag will allow the team member to take over any visible conversation. When a conversation is take over, Xenioo will stop processing any incoming message and the taking over operator will be able to talk to the user, regardless of **the channel the user is using.** The operator is then capable of giving back control to Xenioo and even redirect the user to a specific chatbot section. | | Forget Conversation |

Any team member with this flag can initiate the conversation deletion procedure. This procedure will tell Xenioo to delete and forget anything related to the user. This includes any variable, tag or conversation part that has happened inside Xenioo. Any third party channel may still have saved information about the user: these information must be deleted on each platform manually.

After the user has requested deletion of its data a 60 minutes average chat ban is applied: during this period Xenioo will not reply to the user or record any of this user activities.

| | View Conversation Variables | The user is allowed to see each and every conversation variable collected by Xenioo during chatbot runtime. If disabled, the full [conversation variables](/conversations/general) panel will be inaccessible. | | View Contact Details | The user is allowed to access the global contact details panel. The global contact detail contains global variables as well as team wide notes | | View Custom Conversation Panel | The user can access the custom conversation panel configured in the [current chatbot settings](/basic-concepts/chatbot-details/chatbot-settings/conversation#extended-conversation-variables-panel). | | Share Conversation | If enabled, the user will be able to [generate a unique URL](/conversations/take-over#share) that allows any user to view a very specific conversation for up to 48 hours. | | Edit Audience | Every team member with this flag will be capable of updating, creating or deleting any existing audience. This flag simultaneously affects both Conversation Audience and Broadcast Audience filters. | | View Dashboard | Enable this flag to allow team member access to each chatbot dashboard information detailing average users and conversation for period as well as more, in depth information. Users with this flag can also access the chatbot publishing logs to inspect errors and issues with your chatbot channels. | | Export Data | This flag allows your team member to export detailed information on each and every conversation happened during a specific time filter. Scheduling and availability may be subject to account limitations. | ![](/files/-MM55CW3AitBDOF9dHY4) ### Member Group Name This new field will appear beside the email as soon as the [Pro-Team package is activated](https://www.xenioo.com/en/managing-a-chatbot-customer-service-team-with-xenioo/) and allows you to specify a group name for each of your team members.\ Group names can later be used in your chatbot to select an operators team for your support flows as well as to automatically filter conversations based on the members teams. Multiple group names can be specified by separating each entry with a semicolon (;). A team member part of multiple groups can be picked by the [operator action](/actions-and-operations/flow/xenioo.bots.actions.base.requestoperatoraction) for any group and can also see any conversation assigned to any group specified. ### Further Reading The following article from the official Xenioo blog details additional use cases for the Teams section. {% embed url="" %} ### # Team Message Templates Team Message Templates are chat messages you can create for each and every chatbot in your account once you enable the [Pro Team package](/basic-concepts/your-account/additional-packages). Message Templates are useful precompiled messages you can assign to your operators (to all of them or just to a selected few). Your operators will then be able to use them to quickly reply to your customers during support. A shared messages pool helps unifying your business communication by making sure that all of your operators use the same wording on specific topics. ![](/files/-MM542janogUi3ZoM96H) All the message templates you create are visible in the lower commands section of the conversation area. Your operators will be able to see only the messages that are assigned to them. Template messages are [dynamic](/actions-and-operations/dynamic-parsing): the can contain variables based on the current contact flow. Enabling the "Visible to shared conversations" flag will automatically make the message template visible to every [shared take-over conversation url](/actions-and-operations/flow/create-conversation-url-action). # Team Member Access For all intent and purpose, a team member is a fully functional Xenioo account. A team member has its own email and password access (after signup) and, by default, a free account. Each team member can access its own account and build private chatbots and even upgrade its own account to any premium type. A team member may be managing other team in his own chatbots seamlessly. When a user who is part of a team logs in, Xenioo will automatically execute one of the following actions: * If the user is part of a team of only one account, he will be redirected to that account by default; * If the user is part of more than one team, an account selection window will be presented. ![](/files/ys1ZMDgiJXV6X1bFubfC) If the user is in any of the above scenario but has already chosen an active account previously, he will be redirected to that automatically. As a team member, a user can always change the active account by using the Switch Account command on the account avatar context menu. ![](/files/DYQFKtcLlriucCDzZn6f) # Backup & Restore The Backup & Restore features of Xenioo let you backup your chatbot anytime and how many times you want to later restore it, overwriting your current chatbot or creating a new one. The Xenioo backup format **is self contained** and can be even restored to another account completely different from the one that have created the chatbot originally. Free and premium account can both backup and share their chatbots with other accounts and publish them as their own (provided the features used are [inside their respective plans](/basic-concepts/your-account/the-free-plan)). Xenioo automatically keeps a version number for all your chatbots. This internal number is updated whenever your change, even slightly, your chatbot and is reflected automatically on your default backup filename. Use this number to quickly check which of your backups are more recent. {% hint style="warning" %} If you chose to restore your bot as a new bot, both API Token and API Secret will be changed. The new restore bot will have both these values reset. This also happens automatically if the bot is restored into another account. {% endhint %} The following table details all information contained in each Xenioo backup file. | Information | Backup | | -------------------------------------- | ---------------------- | | Chatbot flow and Design | Full | | NLP, Intents, Expressions and Entities | Full | | Publishing Information and settings | No | | Scripts, Integrations and automations | Full | | Broadcasts | Full | | Audiences | Filter Definition Only | | Conversations and Users | No | | Reports and Statistics | No | ## Automatic Backup By adding to your account the [Automatic Backup additional package](/basic-concepts/your-account/additional-packages) you will enable additional backup and restore options. Automatic Backup will allow Xenioo to automatically create a backup of your chatbot on specific events such as * Before Publishing * Before deleting a behaviour * Before deleting an interaction * Before moving an interaction to another behaviour These backups can then later be restored in case you wish to revert to a previous version of your chatbot. Backups are kept for definite amount of time, according to [standard retention](/conversations/data-retention). {% hint style="info" %} Automatic backup will only store information related to the current bot design, broadcasts, campaigns and NLP training. Database, conversations and any other information is not included in the backup. {% endhint %} # Clone and Reference Clone Any chatbot inside you account can be quickly cloned by using the supplied "Clone" button. Each chatbot clone is, by default, a full clone of the original chatbot and becomes completely detached from it. Any change you make to the original chatbot is of course *not reflected* on the cloned chatbots. ![](/files/-MUP2Ym2-kj_uVaN4gft) An optional [Xenioo package,](/basic-concepts/your-account/additional-packages) called "Clone Master" can enable an additional way of cloning chatbot named "referenced clones". ## Referenced Clones A referenced clone is a chatbot that remains attached in all content and features to its original source. As soon as you create a referenced clone, the original bot will become the "Master Clone" bot and all of the clones will be considered childs of the master.\ Visually, you'll notice a crown near any Master Bot you have in your account and a link symbol to any child. Hovering over the symbols will let you know how many childs the master has or who is the master of a child. ![](/files/-MUP6pu64L2qo2WZUu9X) ### Working with a Master Bot A master bot is a bot that has at least one referenced clone. It can be modified and changed exactly like any other chatbot. You can build your flow, train AI or add broadcasts freely both before and after creating your referenced clones. A Master bot can be online on any given channel and carry on its own conversations like any other chatbot. The only difference between a master bot and a standard bot is the ability to update all the referenced clones with any update made at any given time. A master bot has an additional button just for that on the main design toolbar. ![](/files/-MUP7kyohTqqAmFjA-eS) The update and publish button will automatically update all of the referenced clones propagating any change you've made to the master bot. Each child chatbot will also be automatically published to any configured channel. ### Working with a Child Bot A child bot is a bot created from a Master Bot, as a referenced clone. By default, each behaviour, intent, broadcast and audience will be locked: they cannot be changed as they are referenced by the Master Bot and will be updated automatically. ![](/files/-MUP8s2LkDDN80TIPbfm) You can change the status of each content by selecting the "Detach" button. If you detach a part of the chatbot from the Master Bot, it will not be automatically updated by the Master Bot and will become local to the child bot. You could, for example, create a Child Bot that has just one detached behaviour, where you put all the chatbot local configuration. ### Master Bot And NLP Master Master Bots can be using [NLP Master](/ai/nlp-master) intents. NLP Master intents will be inherited by child bots. # Publishing Xenioo publishing process is meant to be fast and straightforward. Each channel has its own configuration and powerful settings. # Live & Draft Chatbots Xenioo uses a unique Live & Draft approach for all of your chatbot data that allows you to work on your chatbot without harming your live services. Every update you do (with the single exception of specific broadcast settings) are reflected to your chatbot only when you press the publish button on the main designer page. While you edit your chatbot you never stop, change or in any way alter the contents or the setting of your live chatbot. As your press publish, your current draft is transformed into a full live instance and all your channels are updated. # Publish Your Bot When publishing your bot you are sending online your current flow. Your chatbot will start to reply and interact with users on each [channel ](/basic-concepts/publishing/channels)you've selected. Each [channel ](/basic-concepts/publishing/channels)has multiple specific configurations that can managed from the publishing dialog you can open by clicking on the blue "PUBLISH" button. ![](/files/-M6hrMi_gKkAkk7A4CjJ) The publish dialog shows all of the channels that are available for publishing and highlights them with different colors: | Color | Meaning | | ------- | -------------------------------------------------------------------------------------------------------------------- | | Default | The chatbot is not online on the channel and it is not yet configured to go online there. | | Green | The chatbot is published and online on this channel. | | Blue | The channel is correctly configured but the chatbot is not online. The channel may be disabled or not yet published. | ### Taking Offline the chatbot If you wish to take offline your chatbot on one or more channel all you need to do is to open the publish dialog and, for each channel you wish to take offline, click on the "Enabled" checkbox you can see on the top right corner. If all channels are disabled your chatbot will go completely offline and stop accepting any kind of interaction on any channel. {% hint style="warning" %} After disabling the channel remember to save and **publish** your chatbot to confirm all changes.\ If you do not confirm your changes using the publish button no changes will be made to your live chatbot. {% endhint %}
# Channels Xenioo channels are an ever growing collection of chat and voice platforms where you chatbot can live and communicate with users. # Web The Xenioo Web plugin can integrate your chatbot in any web page regardless of the underlying technology. By leveraging all the different functions and methods offered by our default integration script you can [drastically change both appearance and behavior of your Xenioo chatbot](https://github.com/xenioo/Snippets/tree/master/Web%20Chat). {% embed url="" %} ## Embedding Xenioo into your web site To embed Xenioo chat widget after publishing, you can just copy and paste the embed example you can find in the "How To Embed" tab of the publishing page. There are three ways to embed the chatbot in your web site. ### Chat Widget This is the standard way to insert the chabot in your page as a chat widget. ![](/files/-M4E_1FlEFrmsWfUZ-xm) The position of the embed code inside the page is not relevant: the Xenioo web widget will automatically and quickly create all the required components as child of your page body, without arming your existing page layout. ### Embed You can embed the full chatbot conversation area in any point of your web page. ![](/files/-M4EZtBYw378Brgj_oC8) ### Full Page You can host your entire chatbot conversation area full page in your web site. ![](/files/-M4EaI7xIH6PdT3EjjcV) ### Web channel and conversations Conversations happened inside the Web Channel are saved by Xenioo **only** if the user has interacted with the chatbot at least once. This is done automatically by Xenioo to avoid cluttering your conversation are with potentially thousands of conversations that never had any interaction beside the chatbot initial greeting. For this reason, your [messages count](/basic-concepts/your-account/messages-count) **may differ** from the one you could infer from checking the actual conversations list. ## General Channel Settings ### Domains In this field you **must specify** the list of domains that will implement the Xenioo chat widget. You must use the full domain name (e.g. [www.mysite.com](http://www.mysite.com)). Multiple domains can be specified by dividing each entry with a semicolon (;). *Your chatbot script will fail to initialize until the hosting domain is specified in this this field.* If, after publishing don't see the chatbot widget visible on your page try opening your browser console and check for the following message: **`This Xenioo chatbot is not correctly configured. The chatbot is not published or the current domain is not whitelisted. Please review your settings or contact Xenioo support.`** If you see this message, please make sure that the full name of the domain hosting the Xenioo web widget is specified in this field. ### Display History Each user is automatically identified by a unique id and Xenioo chat widget is capable of recalling the original conversation on each subsequent visit. Enabling this flag will force Xenioo to load any previous conversation inside the web widget. If this flag is disabled the conversation will always restart from the beginning at each web page visit. ### Enable Sounds Enable this flag to enable small chat sounds alerting for new messages when the chat widget is minimized. ## Voice ### Language Set the voice language to be used when initializing the browser text-to-speech and speech-to-text engines. Additional voices can be set using [scripting](/basic-concepts/publishing/channels/web/widget-customization/scripting). ### Enable User Voice Enabling this flag will enable speech-to-text on supported browsers. Your users will be prompted to allow microphone use by your web page. When enabled, this flag will display a small microphone near the send button of the chat area: the user can use that button to talk to the chatbot and send commands directly using his own voice. ### Enable Text Reader This flag will enable a small speaker icon on the top right corner of the chat widget and will enable the browser text-to-speech engine. If the speaker is turned on by the user, every text bubble will be read using the browser default voice or one of the configured voices. ### Reader Specific Voice In this area you can specify one or more voices you would like to be used by your chatbot. Different browsers may support different voices. Xenioo will try to configure a preferred voice starting from the first one to the bottom one, picking the first one existing.\ Please not that event when having the same name, different browsers and platforms may choose different pitch, intonation or general tone altogether. {% hint style="info" %} All of the voice options are not available to [free accounts](/basic-concepts/your-account/the-free-plan). {% endhint %} ## Behavior Settings ### Chat Widget Appear Delay Use this setting to choose after how many seconds the chat avatar icon will appear on your web page. Setting a value of 0 (zero) means the avatar icon will appear as soon as the chat widget is initialized. ### Wait for Widget Click Enabling this setting will force Xenioo to start the chatbot only when the user actually clicks on the widget avatar icon. Enabling this setting may help you *save some monthly messages on high traffic websites* since no interaction is really fired until the user actually clicks on your chatbot. {% hint style="info" %} The Wait for Widget Click option is not available to [free accounts](/basic-concepts/your-account/the-free-plan). {% endhint %} ### Auto Display Chat Delay This value sets the amount of seconds after which the chat area will automatically open without the user interacting. The default is zero seconds that translates to no automatic display. ### Disable Auto Display On Mobile Devices Enabling this flag will disable chat area opening on mobile devices if configured through the Auto Display Chat Delay option. ### Disable Auto Display For Returning User This flag will prevent the web chatbot from automatically opening if the user has already visited your web page. ### Disable Auto Display After First Conversation This flag will prevent the web chatbot from automatically opening if the user has already had a conversation with it. ### Display Callout Message Bubble This feature will display a bubble outside of the avatar area containing the same text you've configured in the start [interaction ](/basic-concepts/the-chatbot-designer/interactions_concepts)and with the same delays. If you select "Display First Message", only the first interaction message will appear in the callout bubble.
![](/files/-LdssM8WBqn0V2qDRzlu) ### Context Menu Mode This setting changes the way context menus are displayed by the web plugin. By default context menus are displayed as a 3 lines button near the chat text area. Choosing "Floating Dialog Window" instead will display the menu as an external window similar to the "Floating Card" content. The floating menu content is managed by adding [Nested](/actions-and-operations/cards/additional-buttons/xenioo.bots.actions.base.operations.buttonnestedoperation), [Text ](/actions-and-operations/cards/additional-buttons/xenioo.bots.actions.base.operations.buttonpostbackoperation)or [URL ](/actions-and-operations/cards/additional-buttons/xenioo.bots.actions.base.operations.buttonurloperation)buttons at bot level inside your chatbot design. No context menu will be displayed on your chat area until the context menu has been configured. #### Open Automatically Enable or disable automatic display of the context menu. This setting applies to both context menu visualization modes. #### Floating Dialog Title And Text Use these boxes to change the text that is displayed by the Floating Dialog Window context menu. Since the floating menu is built as the chatbot starts, only runtime, pre-defined variables are available for [automatic parsing](/actions-and-operations/variables-and-tags). {% embed url="" %} ## Chat Area Settings ### Send Button Text Enable or disable the standard send button on the right of the user chat text area. This setting is off by default. ### Message Time Text This is the default text used under each Xenioo reply part to display the time of the message. You can change the text to anything you like using these pre-defined format placeholders: | Format | Value | | ------ | -------------------------------------------------------- | | HH | 24H format hours value (eg. 14, 18 etc) | | hh | 12H format hours value (eg. 11, 12 etc) | | mm | Minutes | | ss | Seconds | | AMPM | Will become AM or PM depending on actual time of message | ### Input Text Placeholder This is the text that Xenioo will display as a placeholder for the user chat area ### Description This is the text that will appear right below your chatbot title inside the chatbot widget area. ### Display Mode Here you can choose if the chat area will be displayed as a box at the bottom right of the page or as a full height panel on the right side of the page. ### Message Start Position This is how new messages will be displayed in the chat area. Setting Top will make the chat start from the top of the area while choosing bottom will make the chat flow from the bottom to the top. {% embed url="" %} ### Hide Message Area when Interaction User Chat is disabled If enabled, this flag will automatically hide the bottom chat area, where the user inputs all replies whenever the current interaction is set to disable user chat. ## Avatar ### Icon This is the image that will be used by your chatbot as web page icon and inline avatar during chat. If you already set the [global chatbot avatar](/basic-concepts/chatbot-details/chatbot-settings/general#avatar) in your chatbot settings you do not need to specify it again here.\ \ Please note that **you cannot upload an avatar** unless your account has available storage space. [Free accounts](/basic-concepts/your-account) are not allowed to personalize their chatbot avatar. ### Avatar Display Choose if the avatar is displayed only on the title section of the chat area or beside each message. ### Display User Avatar Image Enable this flag if you wish to see the user avatar image beside each user reply text. The avatar image is automatically retrieved from the [profile\_pic variable](/actions-and-operations/variables-and-tags). ### Bubble Position Choose if the avatar is displayed beside the first bubble of each interaction or beside the last one. ## Style ### Background Color This is the main chatbot background color for the web widget. The default value is Xenioo Green. ### Foreground Color This is the chatbot main foreground color. The default value is white. ### Style Sheet Here you can upload a customized css file that will override (or be added to) the standard Xenioo styles. Please note that you cannot upload a customized css file unless your account has available storage space. ### Style Sheet Mode Using this field you can choose how your custom style sheet will be used. You can choose to completely overwrite the existing default Xenioo style or to load your custom style sheet together with the Xenioo one. Depending on the amount of customization you're going to do it may be faster to simply fully replace the Xenioo style sheet or load an additional style sheet to override just some of the classes. ## Variables In this free text area you can specify every variable you would like to be forwarded to your client widget by Xenioo. Forwarded variables are made available at client level so that your [client scripts action](/actions-and-operations/integration/xenioo.bots.actions.base.executescriptaction) or any other client script can use them at run-time.\ Forwarded variables are sent to the client *at every Xenioo reply* and thus are updated in real-time. {% hint style="info" %} Variables forwarded to the client **are not encrypted**. We *strongly advise against* forwarding any variable value that contains sensitive data as it may be accessed by a debugging console. Variable forwarding is not available to [free accounts](/basic-concepts/your-account/the-free-plan). {% endhint %} ## Further Reading Just about all of the [articles](https://www.xenioo.com/en/articles/) and [tutorials](https://www.xenioo.com/en/tutorials/) by Xenioo can be applied to our web chat plugin. Additionally, these chatbot examples can be used as basic starting points for more advanced integrations. Web Chat Widget supports **text formatting**. See [here ](https://github.com/xenioo/Snippets/blob/master/Web%20Chat/Formatting%20text.md)to learn more. {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} # Web Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | bot\_channel | Set to "WebChannel" | | web\_channel\_url | The full URL of the page currently hosting the Xenioo web plugin | | web\_channel\_referral | The full referral (if available) of the current page. Usually contains the URL of the page that redirected to the current web\_channel\_url. | # WordPress Xenioo Web Chat fully supports WordPress websites. You can insert your chatbot in a WordPress page manually, by adding the code you can copy from the Web Publishing dialog or by installing our dedicated WordPress plugin. To enable the Xenioo plugin please download it from [WordPress.org](https://wordpress.org/plugins/xenioo-web-chat/) and follow basic installation instructions. Once installed and activated, under "Settings" you should find a Xenioo menu voice. Clicking on the Xenioo menu entry will open the Xenioo Web Chat settings. ![](/files/-MOCIZT8PkTyl5ZIV0c1) The values required by the plugin can be found on the Web publishing dialog inside your Xenioo chatbot: ![](/files/-MOCOpNvx2YZG-q9R8VF) # Widget Customization # Initialization The standard initialization script for your web chatbot can be copied directly from the "How To Embed" tab inside the [Web Channel publishing](/basic-concepts/publishing/channels/web) dialog. The script is already configured for your chatbot and will look like this one below: ```markup ``` This is the barebone initialization process: all the configuration will be read from your publish settings and nothing else is needed. ## Advanced Initialization The following sections will show how you can go much further with Xenioo initialization to significantly manipulate how the chatbot is initialized and settings are used. ### Changing initialization settings The initialization call can be modified to supply one or more initialization parameter that will override the settings you've specified in the [Web Publishing Dialog](/basic-concepts/publishing/channels/web). As an example, you could change the chatbot widget appearance delay like this: ```markup ``` The above script will make the chat widget appear after 5 seconds. This parameter will automatically override the delay parameter you've specified in the [Web Publishing Dialog](/basic-concepts/publishing/channels/web) settings. You can of course add multiple settings like in the script below: ```markup ``` Use the table below as a general reference for all the initialization parameters you can override: | Parameter | Type | Effect | | -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | The title of the chat area | | subtitle | string | The subtitle of the chat area | | style | string | The full url of your custom chat style sheet | | appeardelay | number | The amount of seconds the widget will wait before appearing on the page. | | avatarinline | boolean | If enabled will display your chatbot avatar beside each message bubble | | nocounter | boolean | Set to true if the small messages counter displayed on the widget is hidden, otherwise false. | | enablesounds | boolean | Choose to enable or disable the messages sounds of the widget | | startopen | boolean | If true, the widget will automatically open as you enter the page | | backcolor | string | The background color of the chat area | | forecolor | string | The foreground color of the chat area | | autoopenchatdelay | number | The number of seconds after which the chat area will automatically open | | autoopenchatmobiledisabled | boolean | Enables or disables the automatica opening of the chat on mobile devices | | waitforwidgetclick | boolean | If enabled, the widget will not retrieve any message from the server unless the user clicks on the widget | | hidetimepart | boolean | If true, the time of each message from the chatbot will be hidden | | displayuseravatar | boolean | Set to true if you want to display the user avatar beside each user message | | showbubble | boolean | If true, displays the message callout bubble near the chat widget. | | enabletextreader | boolean | If true, displays a speaker button on the top right corner of the chat widget, enabling text-to-speech | | enablevoicerecording | boolean | if true, displays a small microphone near the user send button, enabling speech-to-text | | readerperson | string | The list of preferred voices that Xenioo will try to use | | readerlanguage | string | The code of the language you would like to set for the text-to-speech and speech-to-text engines. The value must be set in the code\_CODE format (e.g. it\_IT, en\_US etc). | | speakerenabled | boolean | If true, the bot will start using text-to-speech right away, without waiting for the user to turn it on. | | cookiedomain | string | Set the cookie domain name for the Xenioo chatbot cookie. The Xenioo chatbot cookie contains the current user-id for chat tracking. Use this setting to set an higher level domain for the cookie. | ### Initializing with Variables and Tags Different pages on your website may need different variables or tags to be supplied to your chatbot. As an example, you could have your chatbot receive specific campaign parameters so that it can track users coming from specific ad. To do so, you supply variables or tags directly inside the initialization script.\ In the following example, we're sending the variable test: ```markup ``` In a very similar way, you can supply one or more tags: ```markup ``` Both variables and tags will be made available to your chatbot from the very start and can be used immediately in your flow. ## Starting from a specific behavior If you want your chatbot to start from a specific behavior you can set the corresponding API token directly in the initialization script: ```markup ``` This setting will override the default start behavior and change the default flow. This setting is particularly useful if you have multiple pages on your website and want your chatbot to start addressing the user differently depending on the location. # Scripting The Xenioo widget script supports multiple functions you can use to interact with the chat from an external script or to alter chat rendering during execution.[ You can find here](https://www.xenioo.com/showcase/events-log/) an interactive example of the most widely used functions. ## Events Events are fired as the user or the bot execute specific operations. Your script can implement these events by simply supplying your own function inside the initialization script. In the following example, the initialization script is attaching to the onChatShow event: ```markup ``` Below you can find the full list of the supported events: | Event | Description | Parameters | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | onInit | Fired as soon as chatbot initializations is started | None | | onReady | Fired when initialization ends and the chatbot is ready | None | | onChatClose | Happens every time the user closes the chat window | None | | onChatShow | Happens every time the user or a script opens the chat window | None | | onChatHide | Happens every time the user or a script closes the chat window | None | | onWidgetClick | Fired as the user clicks on the chat widget on the bottom right | calloutclicked = true if the user opened the chat by clicking on the callout bubble, false otherwise. | | onDataConnection | Fired whenever the chatbot is retrieving data from the Xenioo servers | None | | onItemRender | Fired every time a single item is rendered in the chat window | obj = the instance of the chat part to be rendered | | onElementRender | Fired after the chat element to be rendered is ready to be added to the DOM |

element = DOM node instance

obj = the instance of the chat part to be rendered

| | onButtonClick | Fired as a button is clicked in the chat window | say = The text of the button, command = the id of the button | | onUserSays | Happens as soon as the user types something in the chat | say = the text sent by the user. | | onChatInteractionStarted | Fired as soon as Xenioo starts rendering the first interaction chat element | None | | onChatInteractionCompleted | Fired as soon as interaction rendering is done and control is given back to the user | None | | onVoiceConfigured | Fired as soon as Xenioo completes the initialization of languages and voices for text-to-speech | speechutterance = a SpeechSynthesisUtterance object that will be used to for speech-to-text | | onDestroy | Fired as soon as the whole Xenioo widget is destroyed and removed from the page contents | None | | onCalloutDisplay | Fired when the [callout bubble](/basic-concepts/publishing/channels/web#display-callout-message-bubble) of the widget is displayed | text = the text to be displayed in the callout bubble. | The following script implements all of the above events: ```markup ``` ## Functions To use Xenioo web widget functions all you need to do is refer to the global *xenioowebchat* JavaScript variable that is created automatically by the Web Widget script. #### isChatOpened() Returns true if the chat area is visible, otherwise false. #### openChat() Open the chat area if closed. If the chat area is already visible, nothing happens. #### closeChat() Close the chat area if open. If the chat area is already hidden, nothing happens. #### toggleChat() This function will open the chat area if closed or close it if opened. #### resetChat() This function will reset the chat area, removing all message bubbles and clearing the current user id. Using this function will create a new conversation on Xenioo but will not reset the chat layout and personalization. #### scrollCarousel( speed, id, indexmove ) This function will make the carousel specified by **id** move by **speed**. If **speed** is negative, the carousel will scroll to the left otherwise to the right. The active index of the carousel will be the result of the current index value plus **indexmove**. #### say( text, command ) The say function will send a **text** or **command** to the chatbot. This is exactly as the user writes something or click on a specific button. **showBubble( text )** Display the chat widget [callout bubble](/basic-concepts/publishing/channels/web#display-callout-message-bubble) with the message specified in text. The bubble is displayed only if the chat area is closed. **hideBubble()** Hides the currently displayed [callout bubble](/basic-concepts/publishing/channels/web#display-callout-message-bubble). If no bubble is displayed the command is ignored. **getVariable( name )** Returns the value of a conversation variable sent to the client by[ Web Publishing configuration](/basic-concepts/publishing/channels/web). Only variables selected for forwarding are available here.\ If the variable is not found, null is returned. #### goTo( behavior, interaction, params ) This function will redirect the conversation the the specified **behaviour** and **interaction**. Additionally, one or more **parameters** can be specified. These parameters will be translated to variables sent to the chatbot runtime. The script below shows an example of a goTo call: ```javascript xenioowebchat.goTo( "My Bot Behaviour", "Bot Interaction Name", { mycustomvariable : "sometest", myothervariable : "moretest" } ); ``` #### closeFloatContent() Close the floating content area if open. If the floating content area is already hidden, nothing happens. #### openFloatContent(); Open the floating content area if closed. If the floating content area is already visible, nothing happens. #### toggleFloatContent(); This function will open the floating content area if closed or close it if opened. **showFloatingUrl( { Text, Command } );** This function will open the floating content area and display the Url set in *Command*. The floating area will have the title set in *Text*. The floating area can be seen only if the chat area is opened. ```javascript xenioowebchat..showFloatingUrl( { Text:"Xenioo Home!!!", //title Command: "https://www.xenioo.com" //target url } ); ``` #### setVoiceLanguage( language, voice ); This function will change the current voice configuration setting by applying a new language or a new voice to the current utterance instance.\ The following example will change the current language to Italian: ```javascript xenioowebchat.setVoiceLanguage( "it-IT" ); ``` In the following example instead, we're switching to the first available voice on the current browser: ```javascript xenioowebchat.setVoiceLanguage( null, window.speechSynthesis.getVoices()[0] ); ``` Voice changes will take effect starting from the next sentence to be said by the text-to-speech engine. **destroy();** This function will stop the Xenioo chat widget and remove any content generated from the page. # WhatsApp The Xenioo WhatsApp channel can make your chatbot active on any mobile phone number and allow you to reach millions of WhatsApp users. WhatsApp integration is done through professional providers selected by our team among the most reliable and cost effective. You're free to choose the provider that best suits your needs depending on your budget, expected traffic, and mobile availability. While all of the providers integrate with WhatsApp in an autonomous, cloud based way, your WhatsApp account still needs to be constantly connected. If the designated phone is unreachable, so will be your chatbot. ## General Channel Settings ### Service Provider You can choose here the provider you want to use as a gateway for WhatsApp messaging. Different providers offer different advantages at different costs. The table below is a brief recap of the currently offered **provider integrations**. [LINK Mobility](https://linkmobility.com/) is a native provider of Xenioo and all of the features offered on WhatsApp are fully supported. **WhatsApp Business API Providers** WhatsApp Business providers will integrate with the official WhatsApp API and are all bound to Facebook approval of your business. In most cases, a brand new number (SIM) will be required for activating the WhatsApp Business API integration.
ProviderMobileIntegrationExpected Traffic
ProviderMobileIntegrationExpected Traffic
LINK MobilitySIM supplied by the user.

None required.

No actual mobile phone required.

Medium/Very High
Kaleyra EnterpriseSIM supplied by the user.

None required.

No actual mobile phone required.

Medium/High
Kaleyra CloudNumber bought online from Kaleyra Cloud portal.

None required.

No actual mobile phone required.

Medium/High
SinchNumber bought online from Sinch portal.

None required.

No actual mobile phone required.

Medium/High
InfoBipSIM supplied by the user.

None required.

No actual mobile phone required.

Medium/High
ZOKOSIM supplied by the user.

Non required.

No actual mobile phone required.

Medium/High
MessengerPeopleSIM supplied by the user.

None required.

No mobile phone required.

Medium/High
TwilioSIM supplied by user or number bought from Twilio

None required.

No mobile phone required.

Medium/High
**Unofficial WhatsApp API Providers** Unofficial providers support WhatsApp by integrating with the default WhatsApp. No new number is required and the chatbot can be attached to basically any mobile number with WhatsApp.\ These providers usually require that you do not disconnect any WhatsApp web connection while the chatbot is active. | Provider | Mobile | Integration | Expected Traffic | | ------------------------------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------- | | [**Chat-API**](https://chat-api.com/en/?lang=EN) |

User-supplied.
Attached to user's mobile number.

|

Through WhatsApp Desktop.
Integrates with standard QR scan from a mobile phone.

| Medium/Low | | [**Maytapi**](https://maytapi.com/) |

User-supplied.

Attached to user's mobile number.

|

Through WhatsApp Desktop.

Integrates with standard QR scan from a mobile phone.

| Medium/Low | | [**Wassenger**](https://wassenger.com/) |

User-supplied.
Attached to user's mobile number.

|

Through WhatsApp Desktop.
Integrates with standard QR scan from a mobile phone.

| Medium/low | | [**Waboxapp**](https://www.waboxapp.com/) |

User-supplied.
Attached to user's mobile number.

|

Through WhatsApp Desktop.
Requires Chrome Plugin.

| Low | The table below is a brief recap of the currently offered **providers capabilities**: | Provider | Receive Position | Receive Video | | ---------------------- | ---------------- | ------------- | | **Kaleyra Enterprise** | Yes | Yes | | **Kaleyra Cloud** | No | Yes | | LinkMobility | Yes | Yes | | **Sinch** | Yes | Yes | | **InfoBip** | Yes | Yes | | **Zoko** | No | Yes | | **MessengerPeople** | Yes | Yes | | **Twilio** | No | No | | **Chat-API** | Yes | Yes | | **Maytapi** | Yes | Yes | | **Wassenger** | Yes | Yes | | **Waboxapp** | Yes | No | ### Process First User Message The first message sent by the user is considered by WhatsApp as the "opt-in" message. It's the message that the user sends you to activate your chatbot. This setting will enable or disable the processing of this first message.\ If enabled, your chatbot will [receive the first user text](/basic-concepts/publishing/channels/whatsapp/the-opt-in-message) as a standard user text input, otherwise as a simple variable. ### Sender Phone Number This is the phone number that will be used for the WhatsApp integration. Typically this is your own phone number for all the providers that require a physical mobile phone or the phone number provided by the gateway. ### API Key This value must be filled with the provider integration API Key. Each provider account will have its own API Key that you will need to copy here before publishing. ### Account SID This information is used only for Twilio integration and is the Account SID value you can see on your Twilio account dashboard. Copy and paste the value here. ### Auth Token As for Account SID, this information is used only for Twilio integration. The Auth Token is visible on your account dashboard or in the integration settings page of your Twilio account. Copy and paste the value here. ### Hook Url This value will be automatically filled by Xenioo and is the URL of the hook that the selected provider will call whenever a message is received by WhatsApp. Copy this value from Xenioo to the equivalent integration field you see on your provider integration dashboard. ### Contact Filters In these two boxes, you can specify the numbers that will activate the Xenioo chatbot. By default, all incoming messages will be treated as user contacts and will activate Xenioo. Using these boxes you can specify which numbers will be accepted as contacts and which will be rejected.\ You are free to use multiple wildcards to create complex filters to handle prefixes or area codes. ## Further Reading The following Xenioo resources can help you set up, configure and manage your WhatsApp chatbot flow and publication. {% embed url="" %} {% embed url="" %} {% embed url="" %} # WhatsApp Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | **Variable** | **Description** | | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | | bot\_channel | Set to "WhatsAppChannel" | | user\_name | The contact name of the current user, if available. | | user\_id | The contact phone number | | user\_phone\_number | The contact phone number | | wa\_id | The unique id of the contact based on the provider registration database. This value may vary depending on the provider. | # First Message Processing The WhatsApp channel is activated by a first user message. Typically is the target user that will start the conversation either by directly typing something or by following a typical [WhatsApp chat url.](https://faq.whatsapp.com/en/android/26000030/) Using Xenioo you have the choice to decide how to handle this first message. ### Not processing the first message This is the default setting. Xenioo will receive the very first user message but will not redirect it to the chatbot. The conversation will start from the very [first start interaction](/basic-concepts/the-chatbot-designer/interactions_concepts) normally.\ The text sent by the user can still be accessed anytime by your chatbot from the *optin\_message* [runtime variable](/actions-and-operations/variables-and-tags). In this case **do not use** an input action as the very first step of your chatbot as the chatbot will stay silent until the user writes again. ### Processing the first message If you decide to receive the first message like normal text, your chatbot can react to the message received like [with a standard global detection action](/actions-and-operations/input/xenioo.bots.actions.base.textdetectionaction). The global detection can trigger a flow change caused by different options in the control expression. If you use [automatic redirection NLP](/ai/intents#activation) intents or [bot or behavior level triggers](/actions-and-operations/input/global-detection), the first message may trigger automatically any of them. Assuming you're giving away links to your WhatsApp with different starting links, your start interaction may look like this: ![](/files/-MK1NxbVXjPB0Lknt1-I) The very first [Global Detection Action](/actions-and-operations/input/xenioo.bots.actions.base.textdetectionaction) will receive the text and trigger a flow change based on the incoming value (menu or product in our example). The last Go To is instead used to handle different inputs that can show an help for your user. # Configuring Providers # Infobip {% hint style="info" %} Infobip is a Whatsapp Business solution. Please make sure to follow the [necessary steps](https://www.infobip.com/products/whatsapp-business) to enable a Whatsapp business phone number. {% endhint %} To configure the [Infobip ](https://www.infobip.com/)WhatsApp provider follow the steps detailed below: * Login to your infobip account * On the left side, click on the [Apps ](https://portal.infobip.com/apps/)menu icon * On the Apps page, choose "numbers" ![](/files/-MB9ukvyIqp26tUGPJi8) * In the target page you should see your current Whatsapp business number * Copy the number into the Xenioo Phone Number field, then click on the number in the Infobip page. * On the right side of the page a keyword configuration should appear * You should have no active keywords. If you have, make sure that the one you're adding is related to **"ANY OTHER KEYWORD".** * Edit the new keyword endpoint by simply adding the Xenioo Hook Url in the Url box then press Save. ![](/files/-MB9yu0gE0XxbmPWjAkK) * After the hook as been saved, head to your account configuration and look for the API Keys Management section. From there, click on the Manage API Keys link. * Click on the NEW API KEY button to create a new api key then copy it and paste it in the API Key field on the Xenioo publishing page. * While being logged in infobip, head to the [API pages here](https://dev.infobip.com/#programmable-communications/omni-failover/list-all-omni-failover-scenarios). Copy the very first Url you see into the Personalized Base Url field of Xenioo. * Click on publish * Congratulations! Your Xenioo chatbot is online! # ZOKO {% hint style="info" %} ZOKO is a Whatsapp Business solution. Please make sure to check the [necessary steps](https://www.zoko.io/pricing) to enable a Whatsapp business phone number. {% endhint %} To configure your [ZOKO ](https://www.zoko.io/)WhatsApp provider follow the steps detailed below: * Login to your [ZOKO account](https://app.zoko.io/login) * On the top right section, click on your account avatar * From the dropdown menu, choose settings. ![](/files/-MQBcK0RvhcoZ1WmYTdX) * A page with multiple information buttons will appear * Click on the button "API & Webhooks" * On the API Keys page, copy the Public Key value * Inside Xenioo, open the WhatsApp publish dialog and choose ZOKO as your WhatsApp provider * Paste the API Key value in the API Key field of the dialog ![](/files/-MQBdS8vUfYMAzaXEw5d) * Save and Publish * Congratulations! Your chatbot is online! # MessengerPeople {% hint style="info" %} MessengerPeople is a WhatsApp Business enabled provider. Please make sure to follow the [required steps](https://api.messengerpeople.dev/docs/whatsappbusiness) to make sure to have your account correctly enabled. {% endhint %} To configure the [MessengerPeople](https://www.messengerpeople.dev/) WhatsApp provider follow the steps detailed below: * Signup for a [MessengerPeople ](https://www.messengerpeople.dev/)API account * After registering, you'll be redirected to your account dashboard * Click on the OAuth Apps menu on the left and the click on the Add button on the bottom right of the page. ![](/files/-M-q-FERya6mw8fe-eEc) * Set any name you like as Client Name and any description you like as Description. * Set [https://\.xenioo.com](https://app.xenioo.com) as Redirect URI and click on Save. The \ value is the root name of your Xenioo instance. Check your current account Xenioo url to get the root node name. ![](/files/-M-q-fjQ6oCaHfnmZq8E) * Your client credentials are created. You can see them in the overview box of the OAuth Apps page. * Copy the generated Client-ID and Client-Secret in the same fields of your Xenioo publish dialog. ![](/files/-M-q0SqiqgFXMObMU0Ls) * Go to the WhatsApp channel section of your account * Copy the Channel UUID you see on the page and paste it in the Channel UUID field you see on the Xenioo publish dialog * Click on publish * Xenioo will automatically create the correct Webhook configuration for you. * If you move to your MessengerPeople account, you should be able to see the Webhook in your Webhook list. If the page is empty, try a refresh or just wait a minute for MessengerPeople to update. ![](/files/quAeLx4Pz49BrHA4zPp0) * Click on the WhatsApp menu of your MessengerPeople account. You should be able to see your current Business Account details. * Click on the small pencil on the top right corner to start editing this data * Under the "Webhook Subscriptions", add the Xenioo Webhook entry, subscribing only to "messages:in" events and click the save button on the bottom ![](/files/bNz33LgIQ9G5sIdghvF3) * Enjoy! # Twilio Before configuring your own phone number, you can configure Twilio Sandbox environment to test your chatbot directly on WhatsApp as follows: * Create your chatbot and, when ready to publish, open the WhatsApp channel settings * Select Twilio as provider * Create a standard [Twilio ](https://www.twilio.com)account. It is fully free as long as you are using the sandbox * Go to the [Twilio Sandbox for WhatsApp](https://www.twilio.com/console/sms/whatsapp/sandbox) page * Copy the Xenioo hook url from the publish page ![](/files/-LkhD5zo9kO2NVWFOjIV) * Paste the hook url in both the Message and Status url of the Twilio sandbox ![](/files/-LkhDT2RYl7Zku9QFQWt) * Scroll down the page and click on the "Save" button. * The page will reload. Make sure that both the hooks are correctly saved. * Copy, without removing the + symbol, the sandbox phone number you see on the page into the Sender Phone Number in the Xenioo publish dialog * Go to the [Twilio Dashboard](https://www.twilio.com/console) * Copy the Account SID value your see on the very first box under "Project Info" in the same field you see on the Xenioo dialog * Do the same for the Auth Token field you see right below after clicking on the "View" link ![](/files/-LkhEIgIj_SHegkv_mbK) * When all fields are filled, click on the "Save" button to confirm data on the Xenioo dialog and the click on Publish. * Your chatbot is now online and ready to chat * Open your WhatsApp desktop or mobile and send the join message to the number specified in the [Twilio Sandbox page](https://www.twilio.com/console/sms/whatsapp/sandbox) ![](/files/-LkhF9X-pX4X30YAlNA0) * You will receive an automatic message from Twilio telling you you've joined the sandbox. * Now you can freely test your chatbot for as long as you like. {% hint style="info" %} **Please note that Twilio Sandbox forces at least a 2 seconds additional delay on every message. You chatbot will be slower when used in the sandbox.** {% endhint %} When you upgrade to your real phone number, just update the phone number setting in the Xenioo publishing dialog and publish again your chatbot. # Chat-API {% hint style="warning" %} Chat API is a WhatsApp Web based solution. Once you've configured your phone remember to do not use WhatsApp web or your account may become disconnected and your chatbot may stop responding correctly. {% endhint %} To configure the [Chat API](https://chat-api.com/en/?lang=EN) WhatsApp provider follow the steps detailed below: * Signup for a [Chat API](https://chat-api.com/en/demo.html) demo Account * After registering, you'll be redirected to your account dashboard * Click on the "Add New Instance" button you see on the left menu. This will start the pairing procedure with your phone. * The pairing procedure is identical to a typical WhatsApp web pairing. Use your WhatsApp QR scan to associate your phone to the instance * Once the pairing procedure has ended, copy the Token value from the dashboard to the Xenioo publish dialog. ![](/files/-LpXSErVPBHnbFzTAUMo) * Next, copy the API URL value you see near the Token and pasteit to the API Url field in the Xenioo publish dialog ![](/files/-LpXSTO7Y3Of2k4Ewi9H) * Click on publish * Enjoy! # Maytapi {% hint style="warning" %} Maytapi is a WhatsApp Web based solution. Once you've configured your phone remember to do not use WhatsApp web or your account may become disconnected and your chatbot may stop responding correctly. {% endhint %} To configure the [Maytapi](https://maytapi.com/) WhatsApp provider follow the steps detailed below: * Signup for a [Maytapi ](https://console.maytapi.com/register)free trial account. * After registering, you'll be redirected to your account dashboard. * Click on the "Add New Phone" button you see in the Registered Phones section. This will start the pairing procedure with your phone. * The pairing procedure is identical to a typical WhatsApp web pairing. Use your WhatsApp QR scan to associate your phone to the instance. * Once the pairing procedure has ended, copy the **Phone Id** value from the dashboard to the Xenioo publish dialog. ![](/files/-M6d00sHSs7sSYGYdh4E) * Next, go to Settings page from Maytapi dashboard and click on the Token tab * Copy the **ProductId** and **Token** values into the correspondent field in Xenioo publish dialog. ![](/files/-M6d0dRY5xHkgwU7yz14) * Click on publish * Enjoy! # Wassenger {% hint style="warning" %} Wassenger is a WhatsApp Web based solution. Once you've configured your phone remember to do not use WhatsApp web or your account may become disconnected and your chatbot may stop responding correctly. {% endhint %} To configure [Wassenger ](https://www.wassenger.com)as your WhatsApp Xenioo provider, follow the steps detailed below. * Signup for a [Wassenger](https://www.wassenger.com) account. * Pick a I/O plan type suitable for your business. * Once inside the console, click on the "Create Device" button to add your device. ![](/files/-Lhj95W_LhBmLgskZMFY) * Enter free device informations and move on to the authorization phase. * When the **QR code** appears, use your mobile phone to attach your device to Wassenger. **Great! Your Whasapp phone number is succesfully attached to Wassenger**. Now Let's configure Xenioo following the steps below. * Click on the Devices button on the Wassenger page header. * Select your newly added device. * From the details page, copy the **ID field** and paste it in the **Device Id** field in Xenioo. ![](/files/-Lhj9ziLcVCpxzNBK_wK) * Click on the **API Keys** header button in the Wassenger page. * Copy the default **API Key** you find in the **API Key field** in Xenioo. * In Xenioo, confirm all data and publish your chatbot. * Congratulations! Your chatbot is now online on Wassenger. # Waboxapp {% hint style="warning" %} Waboxapp is a WhatsApp Web based solution. Once you've configured your phone remember to do not use WhatsApp web or your account may become disconnected and your chatbot may stop responding correctly. {% endhint %} To configure the [Waboxapp ](https://www.waboxapp.com/)WhatsApp provider follow the steps detailed below: * Signup for a [Waboxapp ](https://www.waboxapp.com/signup)Account * After registering, you'll be redirected to your account dashboard * From there, click on the [My Phones](https://www.waboxapp.com/manager/accounts) menu item on the left * Click on the Add new WhatsApp account on the bottom of the page * Follow the initial setup instructions requiring to install a simple [Google Chrome Extension](https://chrome.google.com/webstore/detail/waboxapp/mgaecjklgnbkkdfnfpncgnogplnjjcdh) * Using the extension, pair your WhatsApp account with Waboxapp * Once your phone is connected, you should see something like this: ![](/files/-LpXO8hpPLdscVu3eq1t) * Make sure that both your Chrome Extension and you phone number inside the Waboxapp page are green and on connected state * Copy the phone number you see on the Waboxapp page and paste it on the same field inside the Xenioo publish dialog. Make sure that the numbers are exactly the same otherwise Xenioo will refuse incoming messages. ![](/files/-LpXPKQba_53dElBezF4) * Next, copy the API Token you see on the top of the Waboxapp page inside the same field of the Xenioo publishing dialog. ![](/files/-LpXPgaHj-20ZnJeeBxt) * Lastly, copy the Hook Url from the Xenioo publish dialog and paste it inside the Hook Url of the associated phone entry. Do not copy the hook url on the Hook url field you see on the top of the page as this will associate the same hook to all your account numbers. ![](/files/-LpXQEA4xUDypbusEBvo) * Publish the bot * Enjoy! # RCS Rich Communication Services (RCS) Channel will publish your chatbot to an RCS supported provider. RCS has rich messages capabilities that can surpass those of current SMS and MMS. RCS integration is done through professional providers selected by our team among the most reliable and cost effective. You're free to choose the provider that best suits your needs depending on your budget, expected traffic, and mobile availability. | Provider | Configuration | | ------------- | -------------------------------------------------------------------------------------------- | | LINK Mobility | [Configuration](/basic-concepts/publishing/channels/sms/configuring-providers/link-mobility) | # RCS Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | **Variable** | **Description** | | ------------------- | --------------------------------------------- | | bot\_channel | Set to "RCSChannel" | | user\_id | The contact phone number | | user\_phone\_number | The contact phone number | | rcs\_capabilities | The capabilities list of the current contact. | ### RCS Capabilities The rcs\_capabilities variable mentioned above will be automatically filled for every new (or returning) contact that is targeted by a push or initiates a conversation with your bot. The variable is automatically filled **before the flow starts** and can be used to change the flow according to your content requirements. The variable will contain the joined list of all the current device capabilities: | Value | Capability | | -------------------- | --------------------------------- | | CHAT | Standard text message | | FILETRANSFER | File Transfer | | GEOLOCATIONPUSH | Information about geo location | | CHATBOTCOMMUNICATION | Rich card and suggested chip list | | RICHCARD\_STANDALONE | Single card | | RICHCARD\_CAROUSEL | Multi-card carousel | | ACTION\_DIAL | Dial phone button | | *ACTION\_OPEN*\_URL | Open external Url. | # Configuring Providers # LINK Mobility LINK mobility is Xenioo preferred RCS channel partner. To setup your LINK Mobility RCS channel follow the easy steps below: * Setup an RCS Channel account on [LINK Mobility](https://linkmobility.com/products/sms/) * Upon activation you will receive your service credentials. * Fill the required data in the RCS Publishing Dialog on Xenioo ![](/files/-MlAXx4EGmj5K0MI8DPc) * Click on Save and then Publish to go live! # Google Business Messages The Google Business Messages channel will publish your chatbot on the Google brands messaging platform. Xenioo is a registered provider and can register, maintain and publish your brand agent. If you wish to register a brand agent please get in touch with Xenioo at . Alternatively, Xenioo can also support external, existing providers, by simply accepting incoming messages on a specific endpoint. If you already have a brand agent registered with another provider and would like to use Xenioo capabilities, please get in touch with and we'll be glad to help you setting up your integration. ## General Channel Settings ### Integration #### Agent Id The Agent Id, as supplied by Xenioo or by your provider. #### Brand Id The Brand Id associated to your Agent, as supplied by Xenioo or by your provider. ### Chat Details #### Avatar This is the image that will be associated to your agent and will be visible by your users. #### Language Use this control to choose the edit language for the Welcome Message and Privacy Policy Url fields. This field **does not set the agent language** but let you edit the different texts for your agent. #### Welcome Message The very first message your user will see as soon as your agent is started. This text does not override the Start Interaction first message: this message will be seen right after your user writes something. #### Privacy Policy Url The url of your privacy policy for the currently selected language. ### Advanced #### Process First User Message If enabled this flag will send the very text your user writes to your chatbot. If your chatbot is not expecting any input, this may cause the flow to be redirected to the fallback. The behaviour of this flag is identical to the [WhatsApp counterpart](/basic-concepts/publishing/channels/whatsapp#process-first-user-message). By default this flag is set to false. #### Ignore Chat Feedback When enabled, this flag will ignore any positive or negative feedback the user sends by interacting with the up and down thumbs that are available on the chat UI. If disabled, Xenioo will parse these feedback messages and send them to the chatbot as text. You can manage the feedback text by using a [global input](/actions-and-operations/input/xenioo.bots.actions.base.textdetectionaction) checking for "feedback:POSITIVE" or "feedback:NEGATIVE" patterns. # Google Business Messages Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | -------------- | ------------------------------------------------------------------------------------- | | bot\_channel | set to GBMChannel | | locale | The two letters locale of the current user | | device\_locale | The two letters locale of the current user device (may be different from user locale) | # SMS The Xenioo SMS channel can make your chatbot active on any mobile phone number and allow you to reach millions of mobile SMS users. SMS integration is done through professional providers selected by our team among the most reliable and cost effective. You're free to choose the provider that best suits your needs depending on your budget, expected traffic, and mobile availability. | Provider | Configuration | | ------------- | -------------------------------------------------------------------------------------------- | | LINK Mobility | [Configuration](/basic-concepts/publishing/channels/sms/configuring-providers/link-mobility) | # SMS Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | ------------------- | ------------------------ | | bot\_channel | Set to "SMSChannel" | | user\_id | The contact phone number | | user\_phone\_number | The contact phone number | # Configuring Providers # LINK Mobility LINK mobility is Xenioo preferred SMS channel partner. To setup your LINK Mobility SMS channel follow the easy steps below: * Setup an SMS Channel account on [LINK Mobility](https://linkmobility.com/products/sms/) * Upon activation you will receive your service credentials as well as Partner and Platform ID. * Fill the required data in the SMS Publishing Dialog on Xenioo ![](/files/-MYiGRQT7jpNhrD8RIah) * Make sure to select the correct localization option on the Platform ID parameter. Refer to LINK Mobility online documentation if in doubt. * Click on Save and then Publish to go live! # Facebook The Facebook channel let you publish your chatbot on your Facebook page. Your chatbot will automatically reply whenever someone initiates a chat using the "Send Message" button on your selected page. Additionally, Xenioo is also integrating with your page events to give your two more advanced options: * automatic reaction to any of your page posts (by either opening automatically the chat or replying as a comment) * posting new content on your page directly from the chatbot. Refer to the complete actions guide to know more about these features. ### Registering Xenioo on your Facebook Page Registering your page for publishing is a very quick process. The very first time your open the Facebook publishing dialog, Xenioo will require you to bind your Facebook account. To do so, click on the Facebook button you see in the center of the dialog and follow the step by step procedure. Once the procedure completes, Xenioo will automatically display the list of all the pages where your account has access as admin. If the page is not available in the list your Facebook account does not have access to it or it is not specified as an admin of the page itself.\ \ If you create a page after linking your account with Xenioo, just click on the *Reload Page List* button and it should appear immediately. ### Disconnecting Xenioo #### Disconnecting from your Account If you later change your mind and want to disconnect Xenioo from your account, you can do so directly from the [Facebook App Integration](https://www.facebook.com/settings?tab=applications) list. #### Disconnecting a single page If, instead, you just want to disconnect a single page from Xenioo, click on the Disconnect Page red button inside the Facebook publishing dialog in Xenioo. ### Transferring subscribers from another bot platform If you already have a bot on another platform and want to transfer its subscribers over to Xenioo, please follow the below instructions: 1. Connect your Xenioo bot to the Facebook page that has your other bot connected to it 2. Send a broadcast with a Button to all your subscribers via the first bot 3. Everyone who interacts with the broadcast will appear in your Xenioo chatbot as a new subscriber 4. Now you're free to reach out to your previous bot's audience through Xenioo ## General Channel Settings The Facebook publishing channel will display the following settings: ### Welcome Text This is the text displayed by Facebook messenger as the user opens the chat area on the very fist contact. After the user chats with chatbot once, this text is not visibile anywhere. ### Whitelisted Domains This list is used to specify third party domains, outside of your Facebook page, that can be used as a target URL for context menu buttons, extensions as well as the web url of the page hosting the Facebook Messenger Web Widget. Each URL must be fully qualified with its own protocol (e.g. https\://) and separated by a semicolon (;). ## Customer Chat Plugin Settings These settings can be modified to have Xenioo automatically generate the required code to embed your Facebook messenger chatbot in your web page. The integration is managed directly by a Facebook script and Xenioo can help you to quickly configure it visually. Once you're happy with these settings, just click on the Show Button Code button to view the full required code: copy and paste the code in your web page to activate your Xenioo chatbot as a Facebook Messenger embedded plugin. ### Show Minimized If enabled, the web plugin will be shown as minimized. Only the Facebook Page icon will be visible on the page at startup. ### Greetings You can write here a text that will be displayed by the plugin as a greeting for the user. This message is displayed only if the current page visitor is currently logged in Facebook. ### Logged Out Greetings This text has the same purpose of the previous setting but it is used only when your page visitor is not logged into Facebook. ### Theme Color A standard HTML color code that will be used as a general accent color for the Facebook chat plugin. Additional informations about functionalities and suppoted pages setup can be found on the official [Facebook Chat Plugin Page](https://developers.facebook.com/docs/messenger-platform/discovery/customer-chat-plugin/). {% embed url="" %} # Facebook Ads Integration Your Xenioo chatbot can be easily activated by a Facebook Ads integration by simply customizing the payload JSON. By connecting directly to a specific behavior, you can have your Facebook Advertising start a very specific section of your chatbot when interacted.\ \ To use this feature, simply copy and paste the following JSON inside the Facebook Ads custom JSON. Just replace "title", "image-url", "subtitle" and "payload" with your correct values and you're ready to go. ``` { "message": { "attachment": { "type": "template", "payload": { "template_type": "generic", "elements": [ { "title": "ANY TITLE", "image_url": "ANY IMAGE URL>", "subtitle": "ANY SUBTITLE", "buttons": [ { "type": "postback", "title": "CALL TO ACTION", "payload": "::" } ] } ] } } }, "user_edit": true } ``` **Remember: the payload token must always end with 2 (two) colon.** The behavior API token can be easily copy/pasted directly from the [behavior details panel](/basic-concepts/the-chatbot-designer/behaviours_concepts). ![](/files/-LdhYjUBxyaf5mqf3ITd) # Feed Integration Xenioo permissions will include also the power to post on your page feed creating both brand new posts or replies to users.\ You can use this integration to automatically post content on your page, directly from your chatbot or reply to your users comments on your page using your chatbot flow.\ If you enable this feature [on some specific actions](/basic-concepts/the-chatbot-designer/actions_and_operations), Xenioo will smartly react in two different ways: * If the user adding the comment has already interacted with you or with the chatbot trough messenger a conversation will be automatically started. * If the user has never interacted with you the text reply produced by your chatbot will become a reply to the user post. You can include in the text a link to your messenger. To let you distinguish between know and unknown users a specific [runtime variable](/actions-and-operations/variables-and-tags) will be generated during execution. To use feed integration you turn on, on a[ global bot operation](/basic-concepts/the-chatbot-designer/actions_and_operations), the [React to Page comments flag](/actions-and-operations/input/global-detection/xenioo.bots.actions.base.operations.textinputglobaloperation). ![](/files/-Lkc64xWoGKWZc3DRt0h) Once enabled you can choose to react to a very specific post by filling the "Specific Post Id" field with the Facebook post id or react to any comment done on any post of your page. In this second case, you can leave the input field blank. ![](/files/-Lkc6vJRJ2Y-0le7ND6o) # Messenger Referral Xenioo Facebook channel fully supports the Facebook Referral link format. This enables your chatbot to automatically present your user with different informations depending on a specific keyword added to your chat link. ## Building the chat link A standard Facebook chat link would look something like this: ``` http://m.me/ ``` Where \ is the name of your page. To build a referral link, you just add the referral parameter at the end of the link like this: ``` http://m.me/?ref= ``` The \ value can be anything you like and it is going to be the value your bot will be looking for. {% hint style="info" %} If your page does not have a unique name, the \ may not work. Use the page id instead: the page id can be retrieved by going into your page settings and selecting the "Messaging" menu section. {% endhint %} ## Checking for a referral Inside your chatbot, the referral (ref) value will be translated to a simple text. For your chatbot it will be like the user has typed the referral value. You can check this value anywhere in the chatbot by simply using a [global text detection operation](/actions-and-operations/input/global-detection). ![](/files/-LnrJFcO-njkpXJs1deX) ## Further Reading {% embed url="" %} # Facebook Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bot\_channel | Set to "FacebookChannel" | | facebook\_page\_id | The full id of the current Facebook page where the chatbot is hosted | | facebook\_page\_name | The name of the current Facebook page where the chatbot is hosted | | first\_name | The first name of the user | | last\_name | The last name of the user | | locale | The locale of the user in standard four letter ISO code notation (e.g. en-US) | | timezone | The timezone of the user based on GMT hours shift. This value is automatically used if [User Timezone](/broadcast/scheduling/basic-settings/untitled#time-zone-mode) mode is selected for broadcasts. | | profile\_pic | The user public profile pic url. | | gender | The user specified gender | | age\_range\_min | The minimum age value of the age range of the user | | age\_range\_max | The maximum age value of the age range of the user | | user\_id | The page-scoped id of the user | | subject\_to\_new\_eu\_privacy\_rules | This flag will be true if your Facebook page is subject to Facebook EU regulations. False otherwise. | Depending on user specific privacy settings some values may still be empty. # Moving users from an existing bot to Xenioo You can easily [import user](/conversations/contacts#import-users) from different formats directly into Xenioo but if you're moving from another Facebook chatbot some additional steps are required. Facebook gives to each of your contacts a unique id that is associated with the chatbot engine you are using. If you disconnect the previous engine and connect Facebook all of your users will be given a brand new id and you'll not be able to track or target them. To move your users from your current chatbot to Xenioo, follow the steps below: * Create your Xenioo chatbot
* Put a [Flow Control Action](/actions-and-operations/flow/xenioo.bots.actions.base.stopinteractionaction) as the very first action of your start interaction, like in the picture below.\ This will stop your Xenioo chatbot as soon as it starts. We do not want this later of course but its perfectly fine right now. ![](/files/-M3KiRhLYGB1Mt-3J-0O) * From your previous bot platform send a broadcast to your users. The content should require to press a simple button or just reply to a simple answer. Any form of interaction will do.
* Any user interacting with your bot will activate Xenioo that in turn will record the contact.
* Your users are now stored inside the Conversation section of Xenioo. You can now disconnect your old bot and publish your full Xenioo chatbot. # Telegram Xenioo Telegram channel can bring online your chatbot on any defined Telegram bot and handle both one-on-one conversations and group chats. ## General Channel Settings ### API Token This is the API token that is given to you by the Telegram [BotFather](https://telegram.me/BotFather) upon registering your bot. All bot configurations such as privacy settings for groups or avatar icon must be done inside the [BotFather](https://telegram.me/BotFather) configuration bot on Telegram. ## Further Reading The following Xenioo articles and resources can guide you in configuring, publishing and maintaining your Telegram chatbot. {% embed url="" %} {% embed url="" %} # Telegram Deep Linking Xenioo Telegram channel fully supports the [Telegram Deep Linking](https://core.telegram.org/bots#deep-linking) link format. This enables your chatbot to automatically present your user with different informations depending on a specific keyword added to your chat link. ## Building the chat link A standard Telegram chat link would look something like this: ``` http://t.me/ ``` Where \ is the name of your page. To build a referral link, you just add the referral parameter at the end of the link like this: ``` http://t.me/?start= ``` The \ value can be any single word without blank spaces, and it is going to be the value your bot will be looking for. ## Checking for a referral Inside your chatbot, the referral value will be available in a variable named *referral*. Inside your chatbot startup flow, you can use the referral value to [differentiate the flow](/actions-and-operations/flow/xenioo.bots.actions.base.variableconditionaction) accordingly. # Telegram Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bot\_channel | Set to "TelegramChannel" | | profile\_pic | The full url of the user profile picture | | is\_group\_chat | TRUE if the current conversation is happening in a group, empty otherwise. | | telegram\_new\_users\_count | The number of new users joined during a group conversation. 0 if no users has joined | | telegram\_user\_leaving | The username of the last user leaving the group | | last\_user | The user name of the last user that has typed something in the current group conversation | | last\_user\_id | The user id of the last user that has typed something in the current group conversation | | telegram\_new\_user\[INDEX] | The indexed user name of each user that has joined the chat group | | telegram\_new\_user\[INDEX]\_type | The indexed user type of each user that has joined the chat group. Can be either USER for a human user or BOT if a bot has joined the conversation. | | referral | The [referral code](/basic-concepts/publishing/channels/telegram/telegram-referral) that is passed through the telegram bot link | | keyboard\_is\_persisting | Indicates if the Telegram [custom keyboard](/actions-and-operations/content/xenioo.bots.actions.base.buttonsarrayaction) is persisting between messages or not. true if is persisting otherwise false or empty. | The following article fully details how to manage your Telegram group using Xenioo: {% embed url="" %} # Slack Using the Slack channel will publish your Xenioo chatbot as a Slack Bot Application of your choice. All the settings for your Slack bot like name, description, avatar and so on can be managed directly from your [Slack Application](https://api.slack.com/apps) area. ## General Channel Settings ### API Token This is the API token that your can retrieve from your [Slack Application](https://api.slack.com/apps) settings. Copy and paste it here before publishing your chatbot. # Configuring Slack The following steps will guide you through the publication of your chatbot on any bot application. ### Create a Slack Application The first thing to do before publishing your Slack chatbot is to create a new Slack Application. Xenioo uses **the classic Slack application configuration** detailed below. * First, start creating a new [classic slack app](https://api.slack.com/apps?new_classic_app=1). * Make sure the Create Slack App title is showing "Classic". ![](/files/-MUwdrkaVtPbC2gSAbIW) * Give your application a name and select on which development workspace you would like to deploy it.\ The application name is not the name of your bot in Slack but can have the same value. ![](/files/-MUweNSyrjRghB86EMD5) * Click on the Create App button to confirm all the parameters * You will be redirected to a page with multiple features and functionalities that can be added to your app. We are going to choose "Bots" as that is what we need. ![](/files/-MUwelA4M1p_cUZgELRI) * Click on "Bots" and let Slack add the functionalities you need to your app. * From the new page that will appear, click on Add Legacy Bot User. This will create a new user that will be impersonated by our bot. ![](/files/-MUwf72qSowLIudSKFR9) * Choose a Display Name and a User name for your bot. These information will be visible to any user chatting with your bot. Confirm your data by clicking on the "Add" button. * On the left side, click on the "OAuth & Permissions" menu item, under the "Features" group. * In the OAuth & Permissions page, click on the very first green button named "Install To Workspace". ![](/files/-MUwfqlprXWABm-5rN-G) * You will be redirected to a standard authorization page where you will be informed of what your bot will be able to do on your workspace. Review all permissions and click on the green "Allow" button. ![](/files/-MUwgLwqtaCjwZan_m1Y) * Slack will automatically install your application to your workspace and your OAuth & Permissions page should now display the required authorization tokens. * From this page, copy the Bot User OAuth Token. ![](/files/-MUwggAdeMN0pgPcEQ8Q) * Paste the token you've just copied inside the API Token field of the Xenioo Slack Channel configuration. ![](/files/-LdtMC4V9lUs9SlRdhMT) * Save the Slack Channel data and click on Publish to send your bot online! ### Enabling Button Events If your chatbot is going to use standard Slack buttons, please follow the steps below to enable the necessary Xenioo integration: * From your application details menu, click on "Interactivity & Shortcuts" * In the target page, click on the checkbox on the top right to enable interactivity. ![](/files/2s1YTTlC43bj24zDyOze) * Copy and Paste the Hook Url you see in the Xenioo Slack publish dialog in the Request URL field. * Save Changes * The subscription is now active and buttons are now enabled on your Xenioo Slack bot. # Slack Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | ------------ | ---------------------------------- | | bot\_channel | Set to "SlackChannel" | | user\_name | The user name of the slack contact | | user\_id | The user id of the slack contact | # Microsoft Teams Xenioo Microsoft Teams channel can bring online your chatbot on any Microsoft Bot App and handle both one-on-one conversations and group chats. ## General Channel Settings ### Bot Id This is the bot id that [Microsoft App Studio](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/app-studio-overview) will generate for your bot. ### Bot Password This is the bot password that [Microsoft App Studio](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/app-studio-overview) will generate for your bot. ### Messaging Endpoint This is the Xenioo webhook that must be used when configuring your bot application inside [Microsoft App Studio](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/app-studio-overview). # Microsoft Teams Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | ----------------- | -------------------------------------------------- | | bot\_channel | Set to "MSTeamsChannel" | | user\_name | The full name of the user chatting with your bot. | | locale | The 4 letters ISO code of the current user locale. | | msteams\_user\_id | The unique Microsoft Teams id of the current user | # Discord The Discord channel let you publish a Xenioo chatbot on Discord. The chatbot can then be invited to servers and channels. Xenioo Discord bots can communicate in channels and to single users directly. ## General Channel Settings ### Auth Token This is the authorization token you can retrieve from your bot development page on the Discord Developer Portal. ![](/files/-MPjRJXOW52RXJaPiGja) ### Messages Filter Here you can specify a general message filter that will be applied to all incoming messages. Use this parameter to block unwanted messages that may trigger specific chatbot actions. ## Button Styles Xenioo supports Discord interactive content in the form of standard Carousel Cards or Interactive Messages. When used for other channels both these actions will be transformed into standard Discord Interactive Content. Discord buttons can also have a different color, depending on the associated style. On the Xenioo designer you can associate different colors using the Custom Style Action. The following styles are currently supported: | Style | Button | | ---------- | ------------------------------------------- | | .primary | The default button color | | .secondary | Alternate button color | | .danger | Red button color | | .success | Green button color | | .link | Alternate button color with a "link" symbol | ## Further Reading {% embed url="" %} # Discord Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | --------------- | ----------------------------------------------------------------------------------------- | | bot\_channel | Set to "DiscordChannel" | | is\_group\_chat | TRUE if the current conversation is happening in a group, empty otherwise. | | last\_user | The user name of the last user that has typed something in the current group conversation | | last\_user\_id | The user id of the last user that has typed something in the current group conversation | # Alexa The Alexa publishing channel will automatically build an Alexa skill model from your chatbot design and bring it online on a specific webhook. This webhook can be used as the Alexa skill endpoint for every dialog [interaction ](/basic-concepts/the-chatbot-designer/interactions_concepts)and dynamic operation. When you publish your chatbot to Alexa, Xenioo will automatically create an Alexa Skill model based on the [NLP intents and expressions](/ai/intents) you've created inside the [Natural Language Processing](/ai/intents) section. Xenioo Skills built for Alexa are fully compliant and production ready. The Xenioo webhook is also perfectly capable of passing all security tests made by Amazon during the pre-publish phase. The first time you open this publish dialog no option is available as the you must first login to your [Amazon Developer Account](https://developer.amazon.com/alexa). After that, you may still be required to refresh your grant for Xenioo as we do not store any kind of information for longer than required to basically update your skill on demand. ## General Channel Settings ### Target Skill Here you will see the list of all Alexa Skills that are assigned to the [Amazon Developer Account](https://developer.amazon.com/alexa) you've used to identify for the Alexa channel. Xenioo will not create a new skill for you: you first need to create an Alexa skill using your [Amazon Developer Account](https://developer.amazon.com/alexa).\ As soon as the skill is created you will see it here. ### Activation Text This is basically the name of your skill. By default the name of your chatbot will be used but you're free to change it to whatever you like. The activation text must follow [Alexa naming guidelines](https://developer.amazon.com/docs/custom-skills/choose-the-invocation-name-for-a-custom-skill.html): choosing a name outside of these guidelines may result in an error during publishing or in your skill being refused by marketplace testers. ### Hook Url This is the Xenioo webhook that your Skill need to use in order to integrate with this Xenioo chatbot. Copy the full URL from here and copy it into the Endpoint section of your Alexa Skill builder. The following image shows where the Hook option is located. ![](/files/-Ldx3Malk0BWIiAEwfnK) For each hook, remember to select *"My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority"* as type. This operation must be done only once. After the first publishing, this information is stored forever in your Alexa Skill. ### Do Not Update Alexa Model Enable this flag if you do not wish to have Xenioo automatically build your Alexa Skill Model for you. This flag can be useful later in the process whenever you want to push a minor change in the chatbot design but do not want to update the whole model or if you wanted to do some manual model modifications and you just want to update the chatbot backend.\ Also, this flag can help you publish minor changes to your chatbot while the skill is under Amazon review during live publish phase.\ *If your skill is already live and published on the marketplace you do not need to enable this flag: your live skill will not be updated by the publishing process.* ## User Details Permissions Under this section you can specify what data your Alexa chatbot will try to retrieve from the user profile. Make sure **to enable only the information** that you've already marked as requested inside your Alexa Skill builder.\ Enabling any setting here without adding the required permission inside your Alexa Skill builder has no effect on the retrieved data: Xenioo will try to get the data and will be simply denied. ## Further Reading This interesting Alexa article series is detailing the steps to create a personalized streaming platform using Alexa and Xenioo. {% embed url="" %} {% embed url="" %} # Troubleshooting Based on your [design ](/basic-concepts/the-chatbot-designer)and your [Natural Language Processing](broken://pages/-LdPE8qz0fvL12XOy9TJ) setup, Xenioo will automatically build an Alexa Skill model everytime your choose to publish. The Alexa model enforces some very specific rules on specific contents and variables that may halt your publishing process.\ You can find below the most common messages. If you encounter a message that is not listed and cannot understand what and why it is happening [contact our support](/basic-concepts/your-account/support) for a quick resolution. ### There is a build in-progress for this skill This message may be shown whenever you try to publish from Xenioo to Alexa after a very short while from the previous publish. There's no real issue with your Skill just wait some minutes to allow Alexa to complete the build of the previous submission. ### No AI Intents defined for Alexa skills management This message is displayed whenever your chatbot has no valid intents specified under the AI section. Alexa Skills are AI based chatbots and can only work using [Intents and Expressions.](/ai/intents) You must define the required intents for your skill and try again. ### Missing sample utterance. At least one sample utterance is required At least one of the intents you've created is missing at least one utterance. All intents you are defining inside the Xenioo NLP engine, excluding [some very specific Alexa types](https://developer.amazon.com/docs/custom-skills/standard-built-in-intents.html#amazonnavigatehomeintent), must have at least one utterance. ### Intent name *"NAME"* contains invalid characters. Intent names must begin with an alphabetic character and may only contain alphabets, periods, and underscores. All intents that are going to be used for an Alexa skill must follow a strict naming rule that does not allow non alphabetical characters outside standard letters, periods and underscores. # Alexa Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | ---------------------------- | --------------------------------------------------------------------------------------- | | bot\_channel | Set to "AlexaChannel" | | device\_id | The id of the device currently contacting your chatbot | | locale | The locale of the device currently contacting your chatbot | | alexa\_user\_id | The full Alexa user id retrieved from Alexa contact data | | alexa\_account\_link\_token | The account link token that Alexa is retrieving from your won account linking procedure | | device\_state | The current state of the Alexa device | | alexa\_api\_endpoint | The Alexa reply endpoint | | alexa\_api\_messaging\_token | The Alexa messaging token value | | user\_name | The user name of your contact | | first\_name | The first name of your contact | | user\_email | The full email address of your contact | | country\_code | The two letter ISO country code of your contact | | postal\_code | The delivery postal code of your contact | | state\_or\_region | The delivery state or region of your contact | | city | The delivery city of your contact | | address\_line1 | The delivery first address line of your contact | | address\_line2 | The delivery second address line of your contact | | address\_line3 | The delivery third address line of your contact | | district\_or\_country | The delivery district or country of your contact | Some of the fields above are related to very specific Skill permissions that need to be requested from the user and specified in your skill deployment from the [Amazon Skill Development](https://developer.amazon.com/alexa/console/ask?) dashboard. If the required permissions are not requested the fields will be left blank. # Google Assistant Using this channel you can publish, update and manage a complete, production ready Google Assistant Action compatible with multiple Smartphones, Home Assistant Devices, TV and in-car systems.\ Xenioo will not just automatically build for you the basic dialog and settings for your Action but will also be able to act as a full backend for it, managing your dynamic chatbot. ## General Channel Settings ### Project Id This is the id of the project you can copy directly from your action details after creation. \ The first time you publish this will be the only parameter required. After pasting the project id, press Save to proceed to auth token request. ![](/files/-LdxommDTVfnMVaih0Wu) ### Authorization Code This is the authorization code shown by the Google integration page that becomes available after pressing Save on the Xenioo publish wizard. This code is required for interacting with your action and updating your settings. ## Further Reading The following Xenioo articles and resources can guide you in configuring, publishing and maintaining your Google Assistant Action. {% embed url="" %} # Google Assistant Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bot\_channel | Set to "GoogleAssistantChannel" | | ga\_user\_id | The user id of the current user contacting Xenioo | | ga\_input\_mode | The [input mode](https://developers.google.com/actions/reference/rest/Shared.Types/InputType) used by the user to send the current command. | | locale | The locale of the user in standard four letter ISO code notation (e.g. en-US) | | ga\_surface\_capabilities | The [detailed capabilities](https://developers.google.com/actions/reference/rest/Shared.Types/AppRequest#Surface) of the current Google Assistant device, as received from the Google Action. | | ga\_account\_link\_token | The full account link token as specified by your account linking integration procedure. | # Phone The Phone channel let you integrate a voice/phone provider directly into Xenioo. The result is a chatbot that lives behind a standard phone number and can reply to your users directly on a standard phone line. ## General Channel Settings ### Service Provider This is the provider you're going to use for your chatbot. Different providers may offer different features, coverage and pricing. Xenioo is constantly looking for new providers that meet our quality standards so the list may vary from time to time. Supported providers: | Provider | Available Language | | ---------------------------------------------------------------------------------------- | ------------------ | | Twilio | English only | | [Voximplant](/basic-concepts/publishing/channels/phone/configuring-providers/voximplant) | Multiple Languages | ### # Phone Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | ------------------- | ----------------------------------------------------------------- | | bot\_channel | Set to "PhoneChannel" | | user\_phone\_number | The full phone number of the user calling your chatbot | | user\_name | The full user name of the user calling your chatbot, if available | # Configuring Providers # Voximplant To enable your phone based chatbot on Voximplant follow the steps below: * Signup for a [Voximplant ](https://voximplant.com/)account * On your home page, after logging in, go to the **Settings** menu on the left * From this section, move to the **API Keys** section * Copy both Account id and API Key into the same fields of your Xenioo Phone Voice Channel dialog ![](/files/-MGOf8DuWzhf_juhbkXF) * From the Xenioo Phone Voice Channel select which voice you would like your bot to use and what language your users are expected to speak. * Click on save and then on publish * Xenioo will automatically setup for you everything you need on your account {% hint style="info" %} The steps below are not automated as you are required to actually buy a phone number for the country you wish and (in some cases) provide a number of additional information. {% endhint %} * After the publish is completed, go back to your Voximplant account and select the **Applications** section * You should find an Application created for you by Xenioo. Click on it to enter your application. * Once you are inside your application details select the **Numbers** option from the menu * Select the Available section and click on **Buy a number** * After you've a number, click on the number and **attach** it to the current application * That's it! Your voice chatbot is ready! # Custom The Xenioo Custom Channel allows any application capable of making simple RESTful https calls to integrate and interact with a [Xenioo](https://www.xenioo.com/) chatbot. This channel is available for live publishing only after adding the [Custom Channel Package](/basic-concepts/your-account/additional-packages) to your [premium account](/basic-concepts/your-account). Using the Xenioo Custom Channel you will be controlling the way the conversation will be displayed to the user as well as [being able to change runtime variables](https://www.xenioo.com/changing-conversation-flow/) anytime. The custom channel allows the creation of both completely custom chat channels (e.g.. a mobile app, a custom voice provider) and the integration of external services into existing services and conversations. In [this GitHub repository](https://github.com/xenioo/API-Channel) you can find two simple C# examples of chatbot interaction as well as a python implementation of a shell based chatbot. All of the samples connect to a Xenioo demo chatbot that is always online for testing. Inside the C# samples folder you can also find the full current source of Xenioo Custom Channel client library that you can reference to your projects as source or directly as a [Nuget package from Visual Studio](https://www.nuget.org/packages/Xenioo.Channels.API/1.0.1). ## General Channel Settings ### API Key This is the key that Xenioo has generated for your chatbot. You should use this key [on every global call](/basic-concepts/publishing/channels/customchannel/rest-reference-guide#general) you are going to make to your API channel. ### Webhook Url This is the URL that Xenioo will automatically call for every message that is generated "offline" from your connection. Messages such as Broadcasts and pushed content that may be sent to your chatbot while the user is not connected will be redirected to this hook.\ If not values is specified, all messages will be queued and sent to you on your [next API request.](/basic-concepts/publishing/channels/customchannel/rest-reference-guide#chatting) ### Include All Channels Conversations When this flag is enabled your Webhook endpoint will be receiving real-time user and chatbot events from any conversation happening on any chatbot channels. {% hint style="info" %} Each notification message sent in real-time from another conversation channel will be counted as an additional [action message](/basic-concepts/your-account/messages-count#action-messages). {% endhint %} # REST Reference Guide ### General Each call made to your Xenioo chatbot must include the following headers: | Header | Value | Description | | ------------- | ---------------- | ----------------------------------------------------------------------------------------- | | Authorization | Bearer \[APIKEY] | This is the API Key you can copy from your Xenioo Custom Channel publishing dialog. | | Content-Type | application/json | All data exchanged with Xenioo must be of this type | | user-id | \[any string] | This is the current chat user id. If no value is specified, Xenioo will create a new user | {% hint style="warning" %} Your chatbot account is permanently tied to a Xenioo server node. \ Any call you make to the custom channel must be directed to your chatbot node or it will fail.\ Your server node is the same you see on the address bar when you're logged in Xenioo (e.g. app, app02 etc).\ If your server address is, for example, app03.xenioo.com, then you must use the same address. {% endhint %} ### Retrieving Configuration You chatbot basic configuration, as specified in your Xenioo designer, can be retrieved using the **config** endpoint as follows: ``` curl -X GET \ https://.xenioo.com/apihook/config \ -H 'Authorization: Bearer [APIKEY]' \ ``` Since this is a global configuration, you don't need to specify the current user-id here. Xenioo reply to this request will be similar to this one: ``` { "Name": "My Awesome Bot", "EnableTypeSpeed": true, "WordsPerMinute": 800, "Avatar": "https://.xenioo.com/api/assets/8e23ff8b3ee7_60f1113c-8e6e-46ce-bf19-a53da5ff4ed0.jpg", "Version": 96, "DefaultBehaviour": { "Name": "My Top Behaviour", "APIKey": "[Behaviour API Key]" } } ``` | field | type | description | | ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | string | The name of your chatbot | | EnableTypeSpeed | boolean | Indicates if the chatbot is configured to use typespeed simulation. If so, TypeDelay will be valued for actions where necessary | | WordsPerMinute | number | The number of words per minute your chatbot can write. This affects the TypeDelay parameter value | | Avatar | string | The url of the avatar specified under your chatbot general settings | | Version | number | The version number of your chatbot. This number is automatically increased by Xenioo | | DefaultBehaviour | object | The name and the API Key associated to your default chatbot Behaviour. You can use the API Key to forcefully redirect your chatbot conversation to another Behaviour | ### Initiating Chat The fist connection to your chatbot chat must be done by calling the **chat** endpoint using the previously specified headers. This endpoint, called without sending any data will reset the conversation to the starting point. If the user-id is specified in this call, the conversation will be reset but historic conversation will be kept in the Xenioo conversation history interface. ``` curl -X POST \ https://.xenioo.com/apihook/chat \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' ``` If you wish instead to continue a previous conversation with a know user you can add the READY command to the request as below. In this case, Xenioo will not reset the conversation and return the full history as first reply. ``` curl -X POST \ https://.xenioo.com/apihook/chat \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' \ -d '{ "Command":"READY" }' ``` A succesful reply from Xenioo may look like this: ``` { "Parts": [ { "Type": 0, "Text": "Hello...I am Xenioo 9000.", "TypeDelay": 300, "BehaviourName": "New Bot Behaviour", "InteractionName": "Start Interaction", "Parts": [] } ], "UserId": "some-user-id", "Creation": "2018-10-05T14:43:43.7057755+01:00", "EnableUserChat": true, "ControlType": 0 } ``` The root reply fields have the following format: | field | type | description | | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Parts | array | This is an array of 1 or more chat parts. Each chat part is usually a Xenioo Action Result | | UserId | string | The user-id of the current user chatting with you. If you did not create it yourself store it and re-use it for subsequent calls | | Creation | datetime | The Xenioo reply creation date and time | | EnableUserChat | boolean | This may change depending on your chatbot design. You should comply to the chabot designer choices by either allowing or forbidding an open reply from the user | | ControlType | number | The control state of the chatbot. 0-Xenioo, 1-Operator Requested, 2-Operator Taken Over | Each part may contain different fields, depending on the type. All general fields are as follows: | field | type | description | | --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Type | number | The type of content represented by the part of the reply. Your client is responsible for displaying the correct content based on this value. See below for a list of all actions | | Text | string | The text content of the action. If available it should be displayed to the user in some way | | Command | string | The command payload associated to this action. To execute this action you should send back this payload to Xenioo | | TypeDelay | number | The delay, in milliseconds, you should wait before displaying the content. Your interface should have a mean of showing a typical typing indicator | | BehaviourName | string | This is the name of the Behaviour that generated this conversation part | | InteractionName | string | The interaction, inside the Behaviour that generated this conversation part | | Parts | array | This array may hierarchically contain more parts, depending on the complexity of the action. | The type parameter is a number representing different types of contents. Refer to the table below for a full list of all possible types. {% hint style="info" %} Values are not fully sequential as some of the contents are reserved for internal use by the Xenioo engine. The missing values should not be expected in a standard parts reply. {% endhint %} | Value | Content | | ----- | --------------------------------------------------------------------------------------------------------------- | | 0 | [Text](/actions-and-operations/content/xenioo.bots.actions.base.textaction) | | 1 | [Button / Quick Reply](/actions-and-operations/content/xenioo.bots.actions.base.buttonaction) | | 3 | [Image](/actions-and-operations/content/xenioo.bots.actions.base.imageaction) | | 5 | [Generic Card](/actions-and-operations/cards) | | 6 | [Question](/actions-and-operations/input) | | 8 | [Go To](/actions-and-operations/flow/xenioo.bots.actions.base.gotointeractionaction) | | 9 | [Video](/actions-and-operations/content/xenioo.bots.actions.base.videoaction) | | 10 | Audio | | 11 | [File](/actions-and-operations/content/xenioo.bots.actions.base.fileaction) | | 12 | [List Card](/actions-and-operations/cards/xenioo.bots.actions.base.listtemplateaction) | | 13 | [Button Card](/actions-and-operations/cards/buttons-card-template-action) | | 14 | [Card Element](/actions-and-operations/cards/xenioo.bots.actions.base.generictemplateaction) | | 17 | [Url](/actions-and-operations/content/xenioo.bots.actions.base.linkaction) | | 19 | User Text | | 22 | [Phone Number Button](/actions-and-operations/input/xenioo.bots.actions.base.phonerequestaction) | | 23 | [Email Button](/actions-and-operations/content/xenioo.bots.actions.base.emailbuttonaction) | | 24 | [Location Button](/actions-and-operations/content/xenioo.bots.actions.base.locationbuttonaction) | | 25 | [Chat Delay](/actions-and-operations/content/xenioo.bots.actions.base.delayaction) | | 27 | [Client Side Script](/actions-and-operations/integration/xenioo.bots.actions.base.clientjsaction) | | 28 | [IOT Device Session End](/actions-and-operations/iot/xenioo.bots.actions.base.controldevicestateaction) | | 29 | [IOT Device Directive Command](/actions-and-operations/iot/xenioo.bots.actions.base.devicestateconditionaction) | | 30 | [Form Render](/actions-and-operations/forms) | | 31 | [Template Message](/actions-and-operations/content/highly-structured-message) | | 32 | [One Time Notification Request](/actions-and-operations/cards/one-time-notification-request-action) | | 33 | [Interactive Message](/actions-and-operations/cards/interactive-message-action) | | 34 | [Location](/actions-and-operations/content/display-location) | ### Chatting Once the chat control is given to the user, he can interact with your chatbot in two ways: executing a command or saying something (sending a text). After acquiring the user input, you can relay it to Xenioo using the same connection endpoint, with the following syntax: ``` curl -X POST \ https://.xenioo.com/apihook/chat \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' \ -d '{ "Text":"Hello there!" }' ``` Depending on how you've implemented your chatbot reactions and interactions the answer may change but will always be compliant to the previous reply fields. If your user has instead any mean to click on chat buttons you've implemented or on Carousel contents you must forward to Xenioo the command payload as follows: ``` curl -X POST \ https://.xenioo.com/apihook/chat \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' \ -d '{ "Command":"3131292d-945e-4b6b-9f78-7f5eacebf5b6" }' ``` Command payloads are always GUID values generated by Xenioo. If the command payload is recognized, the command will trigger and the conversation continue, according to the flow you've designed. ### Chatting on other channels The chat command can be used to send messages from a third party platform to an existing Xenioo conversation on any channel. When invoking the endpoint, if user-id is related to an existing user-id for the selected chatbot, the related conversation will be used and the message sent on the associated channel. Additionally, you can use the chat-dir header parameter to indicate the direction of the message according to the table below. Leaving the parameter empty will by default assign the supplied text to the user. | Value | Meaning | | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | BOT | The message will be said by Xenioo and marked as chatbot source | | OPERATOR | The message will be said by Xenioo and marked as if an operator wrote it. This does not require a real take-over of the conversation. | | USER | Default. The message will be set in the conversation as if the user wrote it. | ``` curl -X POST \ https://.xenioo.com/apihook/chat \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' \ -H 'chat-dir: OPERATOR' -d '{"Text":"this is a human operator speaking!"}' ``` Since chatting on other channels can be used to simulate the chatbot talking, it also possible to send more complex content to your users target channel by using the same syntax of standard chatbot outgoing messages. The example below will send a text bubble and a button to your user channel. ``` curl -X POST \ https://.xenioo.com/apihook/chat \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' \ -H 'chat-dir: OPERATOR' -d '{ "Parts":[ { "Type":0, "Text":"Hello there!" }, { "Type":1, "Command":"my button id", "Text":"Click me!" } ] }' ``` Please note that since it has been built by the request, the above button will not be recognized by Xenioo and the click will trigger a [fallback](/basic-concepts/the-chatbot-designer/interactions_concepts#the-fallback-interaction). {% hint style="info" %} If the [*Include All Channels Conversations* ](/basic-concepts/publishing/channels/customchannel#include-all-channels-conversations)option is enabled your hook will also receive real-time notification of users and chatbot messages to the custom webhook endpoint.\ All these additional real-time notification will count as an additional [action message](/basic-concepts/your-account/messages-count#action-messages) for the active account. {% endhint %} ### Variables, Tags and Conversation State You can update (or create new) variables value or conversation tags using the **status** endpoint like in the example below: ``` curl -X POST \ https://.xenioo.com/apihook/status \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' \ -d '{ "UpdateType":"[type]", "Name":"variable_name", "Value":"variable_value" }' ``` ### Update Type The UpdateType parameter specifies the type of operation to be done on the chatbot conversation. You have four different update types as specified in the table below: | type | description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | set-var | Updates or set the variable with name specified in Name and value specified in Value | | del-var | Drops the variable with name as specified in Name field | | set-tag | Adds a new tag named Name in the conversation | | del-tag | Removes the specified tag | | take-over | The chat is taken over by an operator | | hand-over | The chat is given back to Xenioo | | user-ban |

The user is banned until the chat state is sent back to hand-over or take-over.
Messages incoming from banned users are ignored.

| #### Additional Hand Over and Take Over parameters When updating the status of a chat by altering the take over and hand overs status, an additional parameter can be specified to change how Xenioo handles currently active conversation urls. The parameter, named UpdateMode, can be specified as follows: ``` curl -X POST \ https://.xenioo.com/apihook/status \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' \ -d '{ "UpdateType":"hand-over/take-over", "UpdateMode":"drop-shares" }' ``` Refer to the following table for a quick reference on UpdateMode possible values: | Value | Description | | --------------- | ------------------------------------------------------------------------------------- | | drop-shares | Delete all currently existing shares | | set-view-shares | Each active share will be transformed into a view-mode share | | reset-shares | Each active share will return to be a take-over share if previously set to view-only. | Leaving UpdateMode empty will leave any conversation shared url untouched. #### Multiple Variables The status call can also be used to apply changes to multiple variables and tags by supplying an array of changes to the very same endpoint like below: ``` curl -X POST \ https://.xenioo.com/apihook/status \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' \ -d '{ "Updates":[ { "UpdateType":"set-var", "Name":"test", "Value":"hello" }, { "UpdateType":"set-var", "Name":"test2", "Value":"hello again" }, { "UpdateType":"del-var", "Name":"test_to_be_removed" }, ] }' ``` Variable changes are immediate and can even alter variables that have been created or changed during last interaction execution. {% hint style="info" %} The Status call can update **any conversation** related to the chatbot. You can use this rest call to update any conversation variable for any conversation of the chatbot. This means you can update a variable of a **conversation happened on** [**WhatsApp** ](/basic-concepts/publishing/channels/whatsapp)**or** [**Telegram**](/basic-concepts/publishing/channels/telegram), provided the chatbot is also active on the Custom Channel. {% endhint %} ### Retrieving values Using custom channel it is possible to access a single variable, tag or privacy flag value using the following url path: ``` curl -X GET \ https://.xenioo.com/apihook/status// \ -H 'Authorization: Bearer [APIKEY]' \ -H 'user-id: some-user-id' \ ``` The following call, for example, will retrieve the value of the specified conversation user\_telephone\_number: ``` curl -X GET \ https://.xenioo.com/apihook/status/variable/user_telephone_number \ -H 'Authorization: Bearer [APIKEY]' \ -H 'user-id: some-user-id' \ ``` If successful, the request will answer with the value of the variable or, if a tag or privacy flag is required, with either true or false. ``` { "Value": "+555-555-555" } ``` The type url part can be **variable**, **tag** or **privacy**, depending on the type of value you want to access. ### Conversation Position You can freely change the current conversation position using the **set-pos** command update as described below: ``` curl -X POST \ https://.xenioo.com/apihook/status \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' \ -d '{ "UpdateType":"set-pos", "Behavior":"My Behavior", "Interaction":"Some Interaction" }' ``` The result of this call will redirect the conversation to the specified [Behavior ](/basic-concepts/the-chatbot-designer/behaviours_concepts)and [Interaction ](/basic-concepts/the-chatbot-designer/your_chatbot)and execute its contents (exactly like a standard [Go To Action](/actions-and-operations/flow/xenioo.bots.actions.base.gotointeractionaction)). If the behavior or the interaction cannot be found on the bot, no action is executed. The **set-pos** update can be chained with other update types to first update and then redirect the conversation like in the example below: ``` { "Updates":[ { "UpdateType":"set-var", "Name":"myvar", "Value":"some value" }, { "UpdateType":"set-pos", "Behavior":"My Behavior", "Interaction":"Some Interaction" } ] } ``` The execution of this state change is immediate: any channel attached to this conversation will receive any flow part rendered by Xenioo. {% hint style="warning" %} Updates are executed based on the order of arrival. If you move the conversation **before** updating other variables values will still be set, but the interaction execution will not be able to see the updates. {% endhint %} ### Conversation History You can access the conversation history [that is still available](/conversations/data-retention) for any user by invoking the /chat endpoint like in the example below: ``` curl -X GET \ https://.xenioo.com/apihook/chat \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' ``` The endpoint will return **any** conversation history (even if it happened on a different channel) as long as the user-id exists. If the user is found, each part of the available conversation will be returned in a single array. ### Status Any time during conversation you can retrive the full chatbot status calling the **status** endpoint as in the example below: ``` curl -X GET \ https://.xenioo.com/apihook/status \ -H 'Authorization: Bearer [APIKEY]' \ -H 'Content-Type: application/json' \ -H 'user-id: some-user-id' ``` Xenioo reply will contain all of the currently valued variables, tags, Privacy flags and context in the following format: ``` { "Variables": [ { "Name": "user_name", "Value": "User 1372503197" }, [...] ], "Tags": [ "new_user" ], "PrivacyFlags": [ { "Name": "personal_data_processing", "Enabled": false }, [...] ], "Context": { "BehaviorName": "My Current Behaviour", "InteractionName": "Start Interaction" } } ``` Depending on the complexity of your users conversations and on the amount of data stored in your variables, it may be more # API Variables The following variables are automatically added to your conversation when your chatbot is conversating on this channel: | Variable | Description | | ------------ | ---------------------- | | bot\_channel | Set to "CustomChannel" | # Users and Conversation Persistance As a default settings, any user information (where available) and conversation captured by a chatbot within any of the available channels, is being persisted on Xenioo storage. Xenioo storage is provided by a secure cloud infrastructure based in EU. The lifetime of the persistent storage is limited by the type of the account subscription and it ranges between 1 to 9 months. Using the [Forget User Action](/actions-and-operations/privacy/xenioo.bots.actions.privacy.privacyforgetuseraction) It is however possible to configure each chatbot conversation so that no information is persisted or stored any Xenioo infrastructure beside temporary volatile memory. {% hint style="warning" %} This configuration will **completely remove** each and every information about the user contacting your chatbot. Conversation history, variables, phone numbers, emails and every other detail will be **completely deleted** from Xenioo. In case of a brand new conversation (the user is contacted or contacts the chatbot for the first time), enabling this flag will ensure that **no information is saved** in any case on Xenioo db, making the conversation **fully volatile**. {% endhint %} # Intents Intents are a collection of expressions that are all used to express a specific request. You chatbot may have multiple intents to express different requests such as 'room reservation', 'vacancy check' and so on.\ \ Intents creation is directly counted to your [account capabilities](/basic-concepts/your-account/upgrading-from-free) but will be counted only when you publish. As long as your chatbot stays in preview or draft you are free to create as many intents as you like. To create a new intent click on the Add Intent button on the Intents page. Once your new intent has been created clicking on it will redirect you to the [expressions creation page](/ai/expressions). If you have multiple intents and expressions you may also [quickly import them](/ai/testing-and-verifying/importing-from-file). Once your intent is defined, just click on the intent row to access the [expressions views](/ai/expressions). ## Main Intent Properties ### Name This is the name of the intent. It can be any name you like. ### Key This value is used only on platforms where intents may be used to [represent builtin or default intents](/basic-concepts/publishing/channels/alexa). In any other case, it can be anything you like. ### Description This is the description of the intent. It can be anything you like. ### Language You can specify here the language that will be used by the NLP engine when training the expressions. Selecting the correct language may dramatically improve training results as many terms and words are automatically [stemmed ](https://en.wikipedia.org/wiki/Stemming)to a more common form, increasing confidence and detection percentage. The current supported languages are: English, Spanish, Italian, German and French. ## Context Context is used to automatically filter intents detection based on the context of a previous expression. Let's consider the following chat: ``` User: Is there cable tv in every room? Bot: Yes, of course. All of our rooms have cable tv! User: and Wifi? Bot: Sorry, I'm not sure I've understood your question. ``` This is a very typical example of a non-contextual chat: when the second question is asked by the user, the chatbot has lost the context (which is room services) and replies vaguely with a typical bot answer.\ Using Xenioo NLP, you can build intents with context and intents that activate only on very specific contexts so that your chatbot is capable of sustaining a meaningful conversation. In our example above, we could have a general room services intent setting a "Room Service" context and a general "Room Services" intent that activates only on if "Room Service" context is set. By doing so, the conversation can be easily adjusted to handle something like this: ``` User: Is there cable tv in every room? Bot: Yes, of course. All of our rooms have cable tv! User: and Wifi? Bot: Yes, also Wifi is available in all of our rooms! ``` The chatbot above brings a much smoother exchange with the user, resulting in a better conversational experience. A bot not staying in context is bad but of course, also a bot always staying in context is equally bad. Again, imagine a conversation like this: ``` User: Is there cable tv in every room? Bot: Yes, of course. All of our rooms have cable tv! User: and Wifi? Bot: Yes, also Wifi is available in all of our rooms! User: Nice, and do you have any room available for August? Bot: Sorry we don't have this service. Do you want a list of available room services? User:how can I reserve a room? Bot: Room services can be reserved by simply calling our service desk! ``` As you can see, the conversation is going nowhere. This is because this time the bot has no way of leaving its current context. Again, Xenioo intents can be configured to automatically leave context after a number of "out of context messages" so that our chatbot can successfully react to these changes. ``` User: Is there cable tv in every room? Bot: Yes, of course. All of our rooms have cable tv! User: and Wifi? Bot: Yes, also Wifi is available in all of our rooms! User: Nice, and do you have any room available for August? Bot: We have multiple rooms available for that period. What type of room are you intereseted in? ``` The settings below can be used to configure how your intent reacts to context changes. ### Value This is the context value set by this intent. Usually each intent sets its own context with some intents not setting any but also multiple intents can set the same context. ### Context Filter In this area you can specify one or more context values that will act as a filter for this intent activation. If this area is empty this intent will be activated by any expression match that reaches the configured confidence. ### Context Expiration This is the number of times an out of context answer may happen before the current context is erased and reset to nothing. By default the reset context number count is zero which means that context is reset as soon as an out of context answer is received. ## Topic While your chatbot dialog capabilities grow, you may face issues like [false positives](https://en.wikipedia.org/wiki/False_positives_and_false_negatives) or near confidence when a user express an intent that can lead to different topics. Let have a look at the following conversation: ``` Bot: Hello! Welcome to Awesome Printers! How can I help you? User: I need to setup my printer network Bot: Sure! To help you install your printer I first need to know your PC Operating System! ``` As you can read, the chatbot reply is not *really correct...and not really wrong*. It may be possible that the user just wanted to setup the network but also that none of the initial setup steps has been followed. To handle these dialog states, [Xenioo NLP uses *Topics*](/actions-and-operations/content/xenioo.bots.actions.base.topicssummaryaction). Using Topics you can assign to any intent a generic topic and minimum viable confidence and Xenioo will be able to detect, group and display to your user all the intents that have matched the expression. ``` Bot: Hello! Welcome to Awesome Printers! How can I help you? User: I need to setup my printer network Bot: Sure, I'll be glad to help you. Bot: What would you like to do? Bot: 1- Setup the printer on my PC Bot: 2- Setup your printer for network printing ``` As you can see, the bot had two possible topics and gave the user an option for both. Once configured, it [can be handled automatically](/actions-and-operations/content/xenioo.bots.actions.base.topicssummaryaction) by Xenioo and ultimately translates to a much better experience. Each detected topic will automatically increase the value of the conversation\_topics runtime [variable](/actions-and-operations/variables-and-tags). Use this variable to see if a [topics summary](/actions-and-operations/content/xenioo.bots.actions.base.topicssummaryaction) may be useful to your user. ### Topic Title This is the text that will be displayed by the [NLP Topics Action](/actions-and-operations/content/xenioo.bots.actions.base.topicssummaryaction) if the confidence reaches the Propose Confidence value. ### Propose Confidence This is the confidence percent above which the topic will be added to the detected topics list. ## Conversation Using the conversation section of the intent settings you can configure your intent to generally activate without using any [kind of behavior](/basic-concepts/the-chatbot-designer/behaviours_concepts) or [global bot operations](/basic-concepts/the-chatbot-designer/actions_and_operations). ### Activation This setting shows the type of activation used for this intent. | Type | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Manual | The intent is activated manually by an [action or operation](/basic-concepts/the-chatbot-designer/actions_and_operations). This intent will not be triggered by your chatbot in any way, unless used specifically. | | Automatic Redirection | Using this setting will automatically redirect the conversation to the specified [behaviour ](/basic-concepts/the-chatbot-designer/behaviours_concepts)and [interaction ](/basic-concepts/the-chatbot-designer/interactions_concepts)whenever the confidence goes above the selected percentage. | | Immediate Reply | A specific reply will be show to the user whenever the intent is triggered by the selected percentage. | ### Confidence This is the minimum required confidence to be met by the engine to trigger the activation modes. ### Priority Using this setting you can change the order of activation when multiple expressions may trigger automatically. Take for example these two expressions: ``` Intent:Salutations --> Hello there! Intent:Hotel Search --> Hello there! I'm looking for a hotel ``` Both these expressions may end up triggering their respective intent but of course, you would prefer to have the hotel search triggered and not just reply something like this: ``` User: Hello there! Bot: Hello! User: Hello there! I'm looking for a hotel Bot: Hello! ``` To avoid a situation like the one above, you can just assign to the Salutations intent a lower priority than to Hotel Search. As a result, Xenioo will trigger Salutations *only* if there isn't any Hotel Search triggered. ### Behaviour This is the [behaviour ](/basic-concepts/the-chatbot-designer/behaviours_concepts)where the conversation will be automatically redirected when Automatic Redirection is selected. ### Interaction This is the [interaction](/basic-concepts/the-chatbot-designer/interactions_concepts) where the conversation will be automatically redirected when Automatic Redirection is selected. ### Reply Text This is the text that will be sent to the user when Immediate Reply is selected. Like in any other text, [Dynamic variable parsing](/actions-and-operations/dynamic-parsing) can be used here. ### Can Bypass Input State Enabling this option will allow the automatic activation to override any currently blocking input and activate the associated flow. {% hint style="info" %} Changing the flow during a blocking question will fully skip the question. Use the [Bookmark action](/actions-and-operations/flow/conversation-bookmark-action) to allow your users to eventually go back to the question. {% endhint %} ### Further Reading {% embed url="" %} # Expressions Expressions are basically a list of sentences that define the parent [intent](/ai/intents). While the intent represent a generic description, expression define what users would actually be saying to express it.\ As an example, a "Hotel Search" intent could contain the following expressions: ``` Hello, I'm looking for an hotel near the beach I need a room with ocean view I've been looking for a room for 2 persons I want to book a room I need a room for 4 ``` As you add expressions to your intent you improve the training of your AI and improve the future confidence percent of user messages. The more expressions you add the more precise the AI engine will become [after training](/ai/testing-and-verifying). Expressions alone may be enough for some situations but most of the times your chatbot will need a way to retrieve specific dynamic content from an expression to trigger specific flows. This is done using [Entities](/ai/entities). # Entities Entities are basically specific parts of your expressions that can be detected by the Xenioo engine and extracted to your chatbot variables. Entities are used whenever a specific word represent a value that your chatbot, your flow or even your [remote endpoints](/actions-and-operations/integration/xenioo.bots.actions.base.callapiserviceaction) require. The fastest way to define an entity is by picking a word inside your expressions and click on it. Xenioo will automatically bring up the entity selector dialog where you will be able to either assign the word to an existing entity or create a new one. ![](/files/-LeMQHIiwxgBxY_-pU96) Once you've defined your entity, Xenioo will be able to recognize variations inside the expression as well as detect any of the different entity values inside different sentences. Consider the following example: ``` I want a cheeseburger I'm having a taco I think I'll have an hamburger ``` What our chatbot needs to know is not really how the user asked for food but what food has been asked. Assigning to cheeseburger, hamburger and taco the entity 'food', our expressions will look to Xenioo something like this: ``` I want a {food} I'm having a {food} I think I'll have an {food} ``` Also, the entity 'food' can now be either cheeseburger, hamburger or taco so all of the above sentences become acceptable for any type of order. Later, if you need to add new food types you can [manually add](/ai/entities/creating-manually) new entries (or even [variations](/ai/entities/synonims)) to the same entity # Creating Manually You can create an entity manually by using the Entities editor you find under the AI section of Xenioo.\ Entities created manually from scratch can later be referenced using the [contextual editor mode](/ai/entities). An entity created manually is never referenced or available until at least one [expression ](/ai/expressions)uses it. ## Entity Properties ### Name This is the name of the entity. You can use any name you like as long as it does not contain spaces. The name you choose for the entity will also be the name of the [variable ](/actions-and-operations/variables-and-tags)that will be created when a sentence is parsed by Xenioo and the result is redirected to your chatbot. ### Type This field represent the type of entity your are creating or editing. Currently Xenioo supports the following entity types: | Type | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | Standard | This is the default type. Standard entities are represented by a list of values and possible [variations](/ai/entities/synonims). | | Wildcard | This is a [placeholder ](/ai/entities/default-entities#wildcards)representing any value at the specified position. | Additionally, Xenioo is also capable of [detecting numbers](/ai/entities/default-entities#numbers) both in numerical and textual form and forward them to your chatbot as contextual entity [variables](/actions-and-operations/variables-and-tags). ### Key This value can be used to reference a specific entity type for a specific channel. If you are publishing for [Alexa ](/basic-concepts/publishing/channels/alexa)for example, you may enter here the corresponding [Alexa Slot Type](https://developer.amazon.com/docs/custom-skills/slot-type-reference.html) name. ### Values Here you will find all the values you've specified while creating the entity using [contextual mode](/ai/entities). You can add as many values as you wish and also specify here [synonyms](/ai/entities/synonims). # Entity Types Different entities will produce different intent recognition results. You can find here a full reference of all currently supported entity types. ## Default Entities This is the default entity type for any newly created entity both manually and contextually. Default entities can be single or multiple words long. All default entities that are recognized inside a user expression are automatically translated to a corresponding [Xenioo variable](/actions-and-operations/variables-and-tags) for your chatbot. A "food" entity, if recognized, will become a variable "food" with a value equal to the word (or words) specified by the user inside the expression. ## Numbers Numbers are built-in entities that do not need and entity definition and are recognized and translated automatically by Xenioo into a numerical value. Whenever the user uses a number inside an expression, Xenioo will automatically create a variable for your chatbot called "number\" where \ will be a number starting from one indicating the index of the number. For example, an expression like this: ``` I am 40 years old ``` Will generate a variable called **number1** with **40** as value. An expression like this : ``` I'll be twenty years old in one month ``` Will generate a variable called **number1** with **20** as value and one called **number2** with **1** as value.\ \ Numbers are recognized and transformed only if expressed in the language of the intent being triggered. ## Wildcards Wildcards act formally like Default entities with one important exception: *values do not need to be specified*. This means that once you identify a specific part of a sentence as wildcard anything that the user says inside the expression boundary will be translated to an entity value. So, for example: ``` My name is John and I'm 20 years old ``` In the expression, we mark John as an entity user\_name like this: ``` My name is {user_name} and I'm 20 years old ``` Using a default entity type, we would need to specify all possible first names and sometimes this is impossible. Instead, we proceed to update the entity by manually making it a wildcard. From now on anything specified by the user inside that expression (or similar) is passed to user\_name. For example, taking the following expression: ``` My name is Mark Albert the third and I'm 20 years old ``` Xenioo will recognize the sentence and extract as a wildcard a user\_name entity value "Mark Albert the third". Of course expression variations are acceptable as well as multiple expression containing the same wildcard. # Synonims Synonyms can be used whenever an entity value could be expressed in different ways but you still need the original value passed to your chatbot. For example: ``` I live in New York I live in the big apple ``` The above expressions are both referring to New York. By default, we could add both New York and Big Apple to the entity location and the AI engine would be perfectly capable of parsing both. ![](/files/-LeMnLAM8GkyN8_PhL3s) The problem comes when we would like to have all variations (big apple) to point to an original value (New York) as we do need to have a unique value in our chatbot. To accomplish this, we simply move big apple on the same line as new york, inside brackets: ![](/files/-LeMnnIB9T38BWH_CWb9) This notation will tell Xenioo that Big Apple is a synonym of New York and that, while it should be accepted as a possible value, should be translated back to the main value when passed as a variable. Going back to our example, both of the expression would now both create a location variable valued New York. Additional synonyms can be specified by just separating them with a comma and there's no limit to the number of synonyms you can add for each entity. Standard entity notation for alternate values continue of course to be possible. ![](/files/-LeMosrrNSuoCfrOhsH0) # Training & Testing your Model As you add new expressions and entities to your AI model, you will notice a warning sign near the Train & Test section. The warning sign is alerting you that re-training is required. To train your model just click on the "Train & Test" button on the left of the AI section. Xenioo training is very fast: your model train (or re-train) should be completed in a few seconds. After that, all your intents are ready to be tested. To test your model, just type an expression in the evaluation text box and see what Xenioo AI is parsing as a result. ![](/files/-LeMqXYj4SFHPoFifcnF) 1. This is the parsed sentence. From here you can see what Xenioo AI engine is parsing and stemming your example expression. Entities are expressed by their own name in place of words. 2. This is the list of all intents that are processed and that have any relevance to the expression. Below each intent name you will see the expression that is triggering the intent. \ If you have more than one intent triggering a 100% relevance you may end up having false positives or out of context answers. It may be a good idea to check your model or implement [priority ](/ai/intents#priority)or [topics](/ai/intents#topic). 3. This is the list of all the entities that have been found in the submitted expression noted both with main value and detected [synonym ](/ai/entities/synonims)(if any). # Using the NLP Parse Logs The NLP Parse Logs view gives you an overview of all the nearly missed expressions that have been sent by your chatbot users. This view can be critical to diagnose near misses or outstanding variations that can be used to further improve your chatbot training. ![](/files/-LeMuESUD0V50kWvUucl) Using the contextual menu on each row you can quickly add an expression to an existing intent. Once you've added all the expressions you like, remember to [train](/ai/testing-and-verifying) again your model and, eventually, [publish your chatbot](/basic-concepts/publishing). This list is automatically tailed daily. Entries older than 5 days are automatically removed. # Importing Intents From File [Intents ](/ai/intents)and [expressions ](/ai/expressions)can be massively imported from a file to avoid manual creation on every new chatbot and speed up each training phase. The import file must be a comma delimited CSV file using some or all of the columns specified below. | Column | Description | Required | | ---------------------- | ------------------------------------------------------------------------------------------ | -------- | | key | The key of the intent | No | | name | The name of the intent. If the intent exist, it will be overwritten. | Yes | | locale | The locale of the intent, according to the table below | Yes | | expression | Expression associated to the intent. | Yes | | activation | The activation mode of the intent. | No | | activation\_confidence | The confidence of the automatic or reply activation, expressed with a number from 0 to 99. | No | | auto\_reply | The text that should be used as a direct reply when automatic activation is detected | No | | behaviour | The name of the target behaviour when using automatic redirection | No | | interaction | The name of the target interaction when using automatic redirection | No | *All imports are additive to the currently existing intents and expressions.* The file **must** contain column names. The import will start from the second line as the first line is assumed to contain column names. If your file is using special characters such as grave, acute accents or other symbols make sure that the physical file encoding is set to *UTF-8*. Locale string must be specified according to the following table: | Locale | Language | | ------ | -------- | | en | English | | es | Spanish | | de | German | | it | Italian | | fr | French | # NLP Master By enabling the NLP Master [package ](/basic-concepts/your-account/additional-packages)it becomes possible for your Xenioo account to share [Intents ](/ai/intents)among all of your chatbots without repeating them in every instance. Once added to your account, the Master NLP package will automatically create a new master entry in your chatbot list where all your global NLP can be created. ![](/files/-LevVlXSi9o75IUNV1dX) Global NLP [Intents](/ai/intents) and [Entities](/ai/entities) can be referenced in any of your chatbot account. Any update you make on the NLP Master Container will be automatically reflected on every chatbot. The integration with your chatbots will be seamless: you will see the Global NLP Intents and Entities as part of your chatbot with no additional configuration. *Shared intents are counted only once. Shared intents used by chatbots are not counted toward account NLP usage.* ### Redirection Settings While your intents and expressions are fully defined inside your NLP Master Container instance you still have the ability to configure redirection targets for every single chatbot. In your chatbot [AI ](/ai/intents)section you will be able to identify shared Intents by color and style, like in the picture below: ![](/files/-Leve1Ssh_nITjsuTL2R) Editing shared Intents will bring up the Master Intet Detail dialog, where you can still choose where the intent is redirecting locally to your chatbot like you would do with a standard one. ![](/files/-LevfA7FtkgYhLHxzuxQ) ### NLP Master Limits The following limit apply to the AI section when using NLP Master Intents and Entities: 1. Expressions of Intents shared from a NLP Master Container cannot be changed, added or removed 2. Intents names, topics and contexts of Intents shared from a NLP Master Container cannot be updated 3. Entities of Intents shared from a NLP Master Container cannot be extended with new values. Existing entity values can be used to train chatbot local intents. Outside of the above limits, you're free to configure and update shared intents in each and every chatbot. # Xenioo Database The Xenioo Database section gives your chatbot full access to high performance cloud database that can be quickly accessed by your chatbots and shared between conversations. Using Xenioo Database, your chatbot can access multiple [collections ](/database/collections)of data that can be used to store dynamic values. Values, stored in collections, can be accessed from your chatbot flow [using actions](/actions-and-operations/database), [scripting ](/actions-and-operations/integration/xenioo.bots.actions.base.executescriptaction/xenioo-database-collection-methods)and API for [reading, writing and deleting](/database/database-api-access). Data stored in collections is persistent and shared among all conversation instances. ![](/files/-M_REcWKPVLhvj0NM9vC) The Xenioo Database features require an active Database [package](/basic-concepts/your-account/additional-packages). ### Further Reading {% embed url="" %} # Collections Collections are containers of data very similar to a table in a standard database. The main difference is that a collection has no real structure and can contain records with wildly different fields and content.\ The basic format of a single collection record is a JSON document. ## Creating a new collection A new collection can be created by using the Add New Collection button you may see in the Database section of your account. ![](/files/-MagudfIJRU0fcddFsCk) Each collection is built around the parameters detailed below. ### Collection Name This is the name of the collection. It is the name that you will later use inside the designer or in API calls to refer to the collection. Collection names can be whatever you prefer but cannot contain the following characters: (space), (tab), ., $, \ or /. If any of these characters is found in the collection name, it will be replaced by an underscore (\_). Also, collection names cannot be longer than 64 characters. {% hint style="warning" %} Once assigned, the collection name **cannot** be changed. {% endhint %} ### Collection Description Collection Description is a pure descriptive field that can contain any kind of information you may find useful. ### Enable API Access If enabled, this flag will allow access to this collection through Xenioo REST API interface which in turn enables integrations with external custom applications and tools.\ If this flag is disabled, this collection may only be accessed from the chatbot itself or from the administration interface. ## Collection Fields This list contains all of the view fields you wish to define. As stated earlier, collections are not bound to a pre-defined structure like you may find in standard database tables but can contain arbitrary, unstructured data. Still, inserting and viewing records may prove much easier if the general fields you associate with the current collection are defined here.\ Fields defined in this list are later used by Xenioo to dynamically display collection data and to dynamically build an update/insert form that can be used to manage data directly. ![](/files/-M_XIsvp_7NmPwZqYENy) {% hint style="info" %} Please note that collection fields are just a direct reference to a field inside the Xenioo collection document and may not reflect the actual JSON representation of the record. Likewise, removing a field or changing the field name does not affect the real contents of the collection like a in a typical relational table structure. {% endhint %} ### Field Group Field group defines the tab name under which the field will be rendered when editing or inserting an item of the collection. All fields with the same Field Group will be rendered under the same tab page. ### Field Name Field name refers to any field of your Collection model. If the field does not exist an empty column and an empty field will be show. When inserting or updating a record if the field does not exist it will be added dynamically to your document. {% hint style="info" %} Field Names are forcefully converted to lowercase when the collection is saved. Any special character will also be transformed into an underscore character. {% endhint %} ### Value Edit Mode You can choose from here the way Xenioo will render the field in the edit/insert dialog. Different fields are available that can make managing your collection much easier. ### Default Value Or Source You can set here the default value the field should have when a new documents created. If you are creating a Multiple Choice field you can set here all options, separated by a semicolon. ### Mandatory If enabled, Xenioo will require the field to be filled when editing or inserting a document. ### Display in View If enabled, the field will be displayed in the tabular data view of the collection. {% hint style="warning" %} View Fields do not enforce collection contents in any way. Using Xenioo Actions or API or even inserting full JSON you can still add to the collection whatever model you desire. {% endhint %} ## Managing Collection Data Once created, collection data can be added, edited or deleted in multiple ways depending on your requirements: ### Importing from a file Using a very basic CSV structure data can be [imported into a Collection](/database/collections/import-and-export-collections-data). ### Dynamically editing data or using pure JSON By using [View Fields ](/database/collections#view-fields)defined in the collection, Xenioo is capable of creating a custom edit and insert form on the fly that can be used to quickly access your data.\ Pure JSON access is also available for a more finetuned control over you documents. ### From your online chatbot flow using both Actions and Cloud Scripting Using [Actions and Operations](/basic-concepts/the-chatbot-designer/actions_and_operations) designed to [handle database operations](/actions-and-operations/database) you can handle dynamic data directly in your chatbot flow. \ A full set of scripting functions can also be used to access your collections data from [Xenioo Cloud Scripting](/actions-and-operations/integration/xenioo.bots.actions.base.executescriptaction). ### Using Database API Interface If you have external tools and custom applications that require access to your chatbot data collections you can integrate [Xenioo Database API Interface](/database/database-api-access). ## Limits And Counters There are no actual limits to the number of collections each chatbot can have and to the number of records that each collection can contain. {% hint style="info" %} Collection table view, accessible by clicking on the View Data button of a collection will display a maximum of 1024 documents. This is a query/visualization limit that is not imposed on the actual data container that has no technical limit on the number of documents. {% endhint %} Different operations may increase your action messages count according to the following table: | Operation | | | ------------------------------------------------------------------------------------------------------- | -------------------------------- | | Create Collection | 1 Message | | Query Collection Entities | 1 Message, regardless of records | | Delete | 1 Message, regardless of records | | Insert/Update | 1 Message | | [Export](/database/collections/import-and-export-collections-data) | 1 Message, regardless of records | | [Import Data from CSV](/database/collections/import-and-export-collections-data#import-collection-data) | 1 Message every 20 records | | [CSV Direct Data](/database/database-api-access/csv-direct-data) | 1 Message every 10 records | # Import And Export Collections Data The data contained in each collection can be imported and exported anytime from the global collection view. ![](/files/-M__c5G8ImuywWajUMmo) ### Export Collection Data To export all of your collection data simply click on the "Export Data" icon button available on the general data view. Export is executed using a scheduled ASAP report that will be carried on by Xenioo.\ As soon as the report is ready for download you will receive an email at the address configured on your account.\ The export procedure will export all of the records contained in the current collection. Query [limits ](/database/collections#limits-and-counters)imposed on the general data view are not applied to data export. Data Export is also available in a real-time, [API based access.](/database/database-api-access) ### Import Collection Data Data can be imported in your collection by simply supplying a standard CSV file. The file is expected to have field names on the very first line. CSV files starting with a SEP indicator on the very first line are also accepted. If the supplied file contains a column named "**\_id**", Xenioo will attempt to update the document with a unique id equal to the value of the current CSV line. If the document does not exist, it will be inserted with the specified unique id. The import is immediate, as soon as the file is uploaded to your Xenioo account. --- [Next Page](/llms-full.txt/1)