A Brief Intro To Twnel’s Bot Spec Basics

In this post, I will provide a short intro to the Twnel Bot Spec. Understanding its main elements will allow you to get a head start when developing chatbot flows using the Twnel Framework.

A chatbot flow in Twnel has the following components:

Twnel bot spec components

A flow is divided into steps (that we call transitions). Each transition has to have an associated action.  But let’s cover each component in more detail.

Variables  – The framework supports 3 types of variables:

  1. User variables: read-only parameters supplied by the Twnel Platform. User name, phone, country, and tags. These are the same used on the Twnel’s Control Tower. (read-only)
  2. Chatbot variables. These are parameters that are common to each and every user of a particular flow. (read-only)
  3. Session variables. These are parameters that are created, modified, and consumed during a session. Their scope is for the flow and each particular user.

Messages: It is a list of value pairs “key-value” that can be used as message templates. Messages are optional since you can enter them directly in each action.

"messages": {
	"error_message": "An error has ocurred",
	"ask_passcode_message": "Hi {{ name }}, please enter your pin",
	"end_message": "Bot ended"
},

Files: They are used to handle the URL of the media files used by the flows

"files" : {
	"my_image": "IMAGE_S3_URL",
	"my_audio": "AUDIOE_S3_URL",
	"my_video": "VIDEO_S3_URL",
	"my_cert": "CERT_S3_URL",
	"my_pdf": "PDFE_S3_URL",
}

Storage: Twnel supports two modes of storage: client or twnel. This functionally allows saving media files captured by the flow on Amazon S3, Azure Storage, or on a personalized HTTP method.

"storage": {
	"twnel": {
		"enable": true,
		"mode": "public"
	},
	"customer": {
  		"enable": false,
   		"drivers": {
    		"s3": {
        		"bucket": "AWS_S3_BUCKET_NAME",
          		"service_account": {
          			"name": "my_aws_s3_account",
        			"credentials": {
                      "aws_access_key_id": "",
                      "aws_secret_access_key": ""
               		}
    			}
            },
            "azure": {
                "bucket": "AZURE_BLOB_CONTAINER_NAME",
                "service_account": {
                    "name": "my_azure_blob_account",
                    "credentials": {
                        "azure_storage_account_name": "",
                        "azure_storage_account_key": ""
                    }
                }
            },
            "gcloud": {
                "bucket": "GOOGLE_CLOUD_BUCKET_NAME",
                "service_account": {
                    "name": "my_google_storage_account",
                    "credentials": {
                        "type": "",
                        "project_id": "",
                        "private_key_id": "",
                        "private_key": "",
                        "client_email": "",
                        "client_id": "",
                        "auth_uri": "",
                        "token_uri": "",
                        "auth_provider_x509_cert_url": "",
                        "client_x509_cert_url": ""
                    }
                }
            }
        }
    }
},

Entry Point. Defines the initial transition of the flow, where the flow will start.

"entrypoint": "welcome"

Transitions. Each transition is a state. Each one has an action and the next transition. The next parameter can be predefined or it can be dynamically calculated using variables. 

"entrypoint": "barcode",
	"transitions": {
		"barcode": {
			"action": "barcode",
			"next": "get_product_info"
		},
		"get_product_info": {
			"action": "get_product_info",
			"next": "price"
		},
		"price": {
			"action": "price",
			"next": "save"
		},
		"save": {
			"action": "save",
			"next": "store_image"
		},
		"store_image": {
			"action": "store_image",
			"next": "response"
		},
		"response": {
			"action": "response",
			"next": "show_image"
		},
		"show_image": {
			"action": "show_image",
			"next": "scan_other"
		},
		"scan_other": {
			"action": "scan_other",
			"next": {
				"yes": "barcode",
				"no": "end"
			}
		},
		"end": {
			"action": "end"
		}
	},

Actions. There are 6 types of actions:

  • send_message: It is used to send messages to the user. Also, it allows users to interact with the bot. For that, the framework spec supports a number of input types, such as text, number, phone, email, radio, checkbox, date, password, location, media, and barcode.
    For more info on input types and examples, refer to the documentation.
  "scan_other": {
    "type": "send_message",
    "messages": [
      "Would you like to scan another product barcode?"
    ],
    "input": {
      "method": "keyboard",
      "type": "radio",
      "data": [
        {
          "id": "yes",
          "label": "Yes"
        },
        {
          "id": "no",
          "label": "No. I'm good"
        }
      ]
    }
  },
  "end": {
    "type": "send_message",
    "vars": {},
    "messages": [
      "No problem. You can launch the chatbot flow at any time to scan more products"
    ],
    "close_chat": true
  }
  • map_result. It is very useful to map values gathered by an API that needs to be transformed before consumed by the flow.
"store_code": {
	"type": "map_result",
	"vars": {},
	"eval": {
		"targets": [{
			"from": "{{ transition.scan_barcode }}",
			"assign": [{
				"map": "output.answer.value",
				"to": "variables.session.barcode"
			}]
		}]
	}
},
  • call_api. It allows defining the parameters to call HTTP endpoints.
"get_product_info": {
	"type": "call_api",
	"vars": {},
	"eval": {
		"method": "POST",
		"content_type": "application/json",
		"url": "{{ variables.chatbot.get_products_details }}",
		"body": {
			"phone": "{{ variables.user.phone}}",
			"barcode_number": "{{ variables.session.barcode}}",
			"remove": false
		},
		"headers": {}
	}
},
  • call_function. It is used to execute functions defined by the functions component.
"call_function18_action": {
	"type": "call_function",
	"vars": {},
	"eval": {
		"function": "get_ideal_height",
			"input": {
				"height": "{{ variables.session.height }}",
				"gender": "{{ variables.session.gender }}"
			}
	}
},
  • Eval_next. On many occasions, the next transition depends on certain conditions of the flow. For example, if the value of a certain variable is larger than a threshold, the next transition should be X, otherwise should be Y.
"eval_next_for_company": {
	"type": "eval_next",
	"vars": {},
	"eval": {
		"function": "ask_if_company",
		"input": {
			"data": "{{ transition.tipe_client.output.answer.selected.label }}"
		}
	}
},
  • Functions. This component holds a list of functions to be used by the flow. Each function gets an input object and returns an output object. Thus, it can handle multiple input and output values.
    The functions have to be written in JavaScript ES5.
"ask_n_contrato": {
	"runtime": "js",
	"version": "5",
	"code": "function ask_n_contrato(input) { var res = input['data']; if (res == 'Persona Natural') { return 'no'; } else { return 'yes'; } }",
	"input": {
		"data": "string"
	},
	"output": {
		"type": "string",
		"values": [
			"no",
			"yes"
		],
		"sample": "no"
	}
},

To learn more or see some examples of chatbot flows visit the official documentation.

For more information,  visit Twnel’s website, where we are posting how-to articles periodically

Copy link
Powered by Social Snap