# Diascript is a json styled way to design scripted dialogs with chatbots

## It is attached to a bot message as invisible metadata.

DiaScript is based on JSON that contains a list of possible responses and the actions to take for each response as well as the default action and aditional parameters.

Example:

{
  "message": {
    "messageTemplateID": "deleteItem4",
    "text": "are you sure you want to delete this item?",
    "diaScript": {
      "params": {
        "itemIdToDelete": "1234"
      },
      "include": {
        "yes": {
          "sendMessage": "yes3",
          "callFunction": "deleteItem"
        },
        "no": {
          "sendMessage": "no3"
        },
        "default": {
          "assignParam": {
            "paramName": "newParamValue"
          },
          "sendMessage": "default3"
        }
      }
    }
  }
}

## - Params

Params are a list of key value pairs that can be used in the diaScript when calling functions to provide additional hidden information to the function.
The params are always inherited from the previous message.

all params are available in the diaScript object as `params.[keyName]`

## Actions

### - CallFunction

CallFunction is a way to call a function in the code and pass the diaScript params to the function.
All params are available in the function.

To add a callable function to the diaScript, add the function to the `diaScriptFunctions` array in the `src/MessagingSystem/DiaScript/DiaScriptConfig.ts` file.

All functions will be called with one `any` parameter that contains the full message object with the diaScript params.

### - SendMessage

SendMessage is a way to send a message to the user.
The message can be a messageTemplateID or a text message.

If no template is found, the text will be sent as a text message.

### - AssignParam

AssignParam is a way to assign a value to a param.
The param will be available in the next message.

## Triggers

### - Include

Include checks if the user response includes a specific word or phrase.
If the response includes the word or phrase, the action will be executed.

### - Exact

Exact checks if the user response is exactly the same as the word or phrase.
If the response is exactly the same, the action will be executed.

### - Default

Default is the action that will be executed if no other action is executed.

## Structure

The diaScriptObject is a JSON object that contains multiple triggers, each trigger contains values that are used to determine if the trigger should be executed.
The trigger also contains one or more actions that will be executed if the trigger is executed.

In addition to the triigers there is one exepction to the structure, the params object, which is a list of key value pairs that can be used in the diaScript when calling functions to provide additional hidden information to the function.

{
  "params": {
    "key": "value"
  },
  "trigger": {
    "possibleValue": {
      "action": "value"
    }
  },
  "trigger": {
    "possibleValue": {
      "action": "value",
      "action": "value"
    }
  },
  "default": {
    "action": "value"
  }
}

## Security and warnings

> ⚠️ **Warning**: The diaScript is a powerful tool that can be used to execute functions in the code.
> Never allow the diaScript to be edited by the user!

> ⚠️ **Warning**: It is possible to create an infinite loop by calling a function that sends a message with a diaScript that calls the same function again, be careful when creating diaScripts and follow the design guidelines.

> ⚠️ **Warning**: Make sure this document is up to date with the code, today is `8-Feb-2023` make sure there arend new breaking changes in the code.