# Kauz-Markup

Die nachfolgende Dokumentation beschreibt die technische Funktionalität des Kauz-Markup. Sie ist zur besseren Kollaboration mit mehrsprachigen Entwicklungsteams auf Englisch verfasst.

# Events

# Event

Each chatbot conversation consists of an unlimited number of events. An event can be published or observed as part of a chatbot conversation. This includes, but is not limited to, supplying conversational content.

Model of an event
<...
  conversation = xs:string
  date = xs:dateTime
  id = xs:string>
sender? 
</...>

# Message extends Event

Represents a natural-language message exchanged between participants using a digital communication system. A message is always bound to one conversation. A conversation signifies the context in which a message is to be processed and understood by the participants of the conversation.

Since a chatbot conversation involves technological systems in addition to human interlocutors, a message carries two kinds of information:

text contents meant to be rendered to end-users
Metadata is meant to aid in message delivery and display, or data intended to provide insights to analysts overseeing the product.

Each message carries a globally unique identifier that cannot be set. Two messages are deemed equal if their component attributes (content, metadata, links, date) are equal. Message identifiers are ignored when assessing message equality.

Model of a message
<message
  conversation = xs:string
  date = xs:dateTime
  id = xs:string>
sender? (content, isInternal, meta, links )
</message>

Example for a message element
<message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
    id="c6a98305-2ca8-4ada-9c4d-98ca47d8db27" 
    conversation="bc0523e7-bb36-4ccf-b4a0-cfe20c0ae9ae" 
    date="2022-05-04T07:34:56.966Z">
    <content>test</content>
    <links/>
    <meta>
        <entry>
            <key>chat_i18n_language</key>
            <value xsi:type="xs:string">de</value>
        </entry>
    </meta>
    <sender type="USER"/>
</message>

# AnalyticsEvent extends Event

Data intended for analytics processes. An analytics event consists of an arbitrary set of tags used to classify the event, as well as a mapping between arbitrary string keys and values of arbitrary data structures. Publishing an analytics event makes the data stored therein available to analytics processes.

Analytics events are associated with a target, which may be either a conversation or an individual message. An analytics event is always associated with the conversation in which it occurred. Each analytics event carries a globally unique identifier that cannot be set.

Two analytics events are deemed equal if their component attributes are equal. Event identifiers are ignored when assessing event equality.

Model of an AnalyticsEvent
<analytics
  conversation = xs:string
  date = xs:dateTime
  id = xs:string>
sender? (target?, tags, data )
</analytics>

Example for an analytics element
<analytics xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
    id="4098db68-17d9-4216-bf41-4a3e751637f4" 
    conversation="f4989ee9-2a8a-4b10-8340-18fff91c27dc" 
    date="2022-05-04T07:38:03.735Z">
    <target type="MESSAGE" id="c852bbea-0c84-4eca-b15c-89499991af20"/>
    <tags>
        <tag>kauz.link.open</tag>
    </tags>
    <data>
        <entry>
            <key>url</key>
            <value xsi:type="xs:string">https://kauz.ai/</value>
        </entry>
    </data>
</analytics>

# Attribute-Summary

Attribute	Field and Description
`conversation`	The conversation UUID to which this event is bound.
`date`	The point in time at which this event is to be added to the conversation. This information will be used by conversational participants or analytics systems to induce an ordering over events received as part of that conversation.
`id`	The UUID of this event. Events are associated with a globally unique identifier.

# Element-Summary

# sender

analytics message

Information about the originator of an event.

Name	Description	Value
`id`	Unique identifier of the sender within a conversation	String
`type`	Specifies the sender	('BOT' \| 'USER')

Model of the sender element
<senderInfo
  id = xs:string
  type = senderType>
</senderInfo>

# target

analytics

Represents the target of an analytics event.

Name	Description	Value
`id`	Unique identifier of the targeted event	String
`targetType`	type of the targeted event	('CONVERSATION' \| 'MESSAGE')

Model of the target element
<...
  id = xs:string
  type = targetType>
</...>

# tags

analytics

Any number of tags with information on the analytics event.

Name	Description	Value
`tag`	single tag element containing information on the analytics event	String

Model of the tags element
<tags>
  (tag*)
</tags>

# data

analytics

Analytics payload data. For each data entry, an arbitrary key string can be associated with data of any class.

Name	Description	Value
`entry`	Single payload data entry consisting of a key and a value	key - the key under which to store the datum value - the payload associated with the key

Model of the data element
<data>
  <entry>
    (key?, value? )
  </entry> 
</data>

# link

message

Represents a link relation between events. All links are bracketed by a <links>-element.

Name	Description	Value
`relation`	a link relation type	'RESPONSE'
`target`	the id of another event targeted by this event	String

Model of the link element
<links>
  <link
    relation = relation
    target = xs:string>
  </link>
<links>

# meta

message

Metadata associated with this event. This includes but is not limited to information used by reporting users such as the answer-ID, module, thematicKey and status. There may be any number of entries.

Name	Description	Value
`entry`	Single metadatum consisting of a key and a value	key - the key under which to store the metadatum value - the value associated with the key

Model of the meta element
<meta>
  <entry>
    (key?, value? )
  </entry>
</meta>

# isInternal

message

Boolean specifying whether a question is a true customer question or posted for internal testing purposes, i.e. health checks. If true, developers of a reporting UI might choose not to display the event in question.

Model of the isInternal element
<isInternal>
  boolean
</isInternal>

# content

message

Content of a message. Content is differentiated from message metadata by the fact that content should be displayed to the message recipient. Apart from natural language, content also subsumes user-interface descriptions and other mark-up.

Name	Description	Value
`text`	text content of a message.	text string that may contain mark-up elements (see below)
`mapInfo`	information needed to display a map	see below
`sliders`	wrapper for elements to be displayed as sliders	see below
`actions`	additional action information for the frontend	see below
`searchresults`	wrapper for searchresults	see below
`card`	Adaptive Card	see below

Model of the content element
<content>
  (text, mapInfo?, sliders?, actions?, searchresults?, card?)
</content>

# Content Elements

# mapInfo

Information needed to display a map. The mapInfo can contain any number of mapElements that need to be displayed in the map.

Name	Description
`name`	name of the location
`type`	type of the location, e.g. branch
`address`	address of the location
`latitude`	latitude of the location
`longitude`	longitude of the location
`openingHours`	comma-separated opening hours of the location

Model of the mapInfo element
<mapInfo>
  <mapElements xsi:type="fifiMapElement">
    (name, type, address, latitude, longitude, openingHours)
  </mapElements>
</mapInfo>

Example for a mapInfo element
<mapInfo>
    <mapElements>
        <name>Kölner Dom</name>
        <type>Kathedrale</type>
        <address>Domkloster 4, 50667 Köln</address>
        <latitude>50.941447</latitude>
        <longitude>6.958281</longitude>
        <openingHours>Täglich 06:00 - 20:00 Uhr</openingHours>
    </mapElements>
    <mapElements>
        <name>Willy-Millowitsch-Denkmal</name>
        <type>Denkmal</type>
        <address>Willy-Millowitsch-Platz, Breite Str., 50667 Köln</address>
        <latitude>50.938528</latitude>
        <longitude>6.945177</longitude>
        <openingHours>Durchgehend geöffnet</openingHours>
    </mapElements>
    <mapElements>
        <name>Ping</name>
        <type>Pong</type>
        <address>Willy-Millowitsch-Platz, Breite Str., 50666 Köln</address>
        <latitude>50.928528</latitude>
        <longitude>6.935177</longitude>
        <openingHours>Täglich 06:00 - 20:00 Uhr</openingHours>
    </mapElements>
    <latitude>50.939564</latitude>
    <longitude>6.953370</longitude>
</mapInfo>

# sliders

Wrapper for elements to be displayed as sliders, e.g. images or dialogplans.

Model of the sliders element
<sliders>
  (text)
</sliders>

# actions

Actions for the frontend. Each action must consist of a command, a button-specification and any number of parameters.

Name	Description	Value
`command`	name of the action	String
`button`	specifies whether a button is needed	boolean
`parameters`	key-value-pair containing further specifics needed for the action	key - the key specifying the kind of the parameter value - the value with the key

Model of the actions element
<actions 
  command = xs:string 
  button = xs:boolean>
    <parameters 
    name = xs:string>
        <value> xs:string </value>
    </parameters>
</actions>

# searchresults

The following mark-up elements are only used in the chat-&-search product. Each searchresult is specified using a

searchresultlink marking its location and anchorText and
a searchresult containing further information which could be used to construct a destination url or add analytics data.

Name	Description
`id`	unique identifier of the searchresult
`score`	score indicative of the searchresult’s quality
`url`	original link to the document
`shortDescription`	short description for the result
`title`	title of the result
`thematicKey`	thematicKey assigned to the result
`type`	type of the result, e.g. document or form
`category`	category of the result
`language`	language of the content
`customSpec`	map of further customer specific fields

Model of the searchresults element
<searchresults>
    <searchresult>
      (id, score, url, short_description, title, thematicKey, type, category, language, customSpec)
    </searchresult>
</searchresults>
...
<searchresultlink destination="<id>">
  (anchorText)
</searchresultlink>

# card

JSON Payload and Data to be rendered using the Adaptive Card Framework. For usage in the chatbot, see also Adaptive Cards .

Name	Description
`payload`	Adaptive Card JSON payload
`data`	Adaptive Card JSON data

Model of the card element
<card>
    <payload>
        <![CDATA[
          {...}
        ]]>
    </payload>
    <data>
        <![CDATA[
            {...}
        ]]>
    </data>
</card>

# Mark-Up-Elements

# Typography/Presentation of Text

Name	Description	Mark-Up	Legacy-Mark-Up
`italics`	represents a span of text that is to be displayed in italics	`<italic>…</italic>`	`\textit{<text>}`
`boldface`	represents a span of text that is to be displayed in boldface	`<bold>…</bold>`	`\textbf{<text>}`
`underline`	represents a span of text that is to be displayed underlined	`<underline>…</underline>`	`\underline{<text>}`
`newline`	newline	`<newline/>`	`##`
`collapsible`	when clicking on anchor text, answer bubble expands and additional text appears; used to present long answers in more compact format at first	`<collapsible anchor="anchor text">additional text</collapsible>`	`\more{<anchor text>}{<additional text>}`
`split`	text before [split] appears immediately; text after [split] appears in separate answer bubble with short time delay	`<split/>`	`[split]`

# Lists

Name	Description	Mark-Up	Legacy-Mark-Up
unordered list	outer markup for unordered list	`<ul>…</ul>`	`\begin{itemize} ... \end{itemize}`
item within unordered list	item within unordered list; is turned into comma when markup is filtered	`<li>…</li>`	`\item … \\` or `\itemAnd … \\` `\itemand … \\` or `\itemOr … \\` `\itemor … \\\`

# Links

Name	Description	Mark-Up	Legacy-Mark-Up
`hyperlink`	link to other website	`<hyperlink destination="<URL>">anchor text</hyperlink>`	`\hyperlink{<URL>}{<anchor text>}`
`documentlink`	* used mostly analogically to hyperlink * displayed differently in frontend (opened in pop-up)	`<documentlink destination="<path>">anchor text</documentlink>`	`\documentlink{<path>}{<anchor text>}`
`internallink`	clickable links to chatbot answer. When clicked, the frontend must send IL: to the backend	`<internallink destination="<TextObject-Identifier>">anchor text</internallink>`	`\internallink{<TextObject-Identifier>}{<anchorText>}` `\internallink{}`
`optionlink`	for clickable options in dialog plans. When clicked, the frontend must send OL: to the backend. If an anchor text is specified, it should be displayed as user answer in the chat. Otherwise, the destination without the mark-up OL: should be displayed. If both option identifier and anchor text exist, the anchor text must be added as meta : `kauz.link.option.label` to the Message so it can be displayed in the Editor-Reporting.	`<optionlink destination="<option identifier>"/>` or `<optionlink destination="<option identifier>"><anchor text></optionlink>`	`\optionlink{<option identifier>}` or `\optionlink{<option identifier>}{<anchor text>}`
`forced option link`	wrapper for option links where one option link must be selected for the user to continue	`<choice force="true">any number of optionlinks</choice>`	NA
`dialoglink`	refers to linked topic in form of dialog plan. When clicked, the frontend must send DL: to the backend	`<dialoglink destination="<dialogPlanName>">anchorText</dialoglink>`	`\dialoglink{<dialogPlanName>}{anchorText}`
`phonelink`	serves to make phone numbers in answers clickable on mobile phones	`<phonelink destination="<phoneNumber>"/>`	`\phonelink{<phoneNumber>}`
`imagelink`	teaser image or GIF	`<imagelink destination="<imageURL>"/>`	`\imagelink{<imageURL>}`
`videolink`	explanatory video	`<videolink destination="<videoURL>"/>`	`\videolink{<videoURL>}`
`searchresultlink`	link to a search result (only used for chat-&-search apps). Must be interpreted in the context of a searchresult.	`<searchresultlink destination="<id>"><anchorText></searchresultlink>`	`\searchresultlink{<id>}{<anchorText>}`
`serviceportallink` DEPRECATED	link to a search result (only used for chat-&-search apps). Replaced by `searchresultlink` (see above)	`<serviceportallink destination="<id>"><anchorText></serviceportallink>`	`\serviceportallink{<url>}{<anchorText>}`
`create ticket button` DEPRECATED in Chat	button with an action that creates a ticket	`<button action="create ticket"><anchorText></button>`	`\createTicket{<anchorText>}`

# Placeholders for Reference to External Chat Facility

Name	Description	Mark-Up	Legacy-Mark-Up
`Livechat`	Link to livechat (use depends on implemented solution)	`<button action="livechat"/>`	[livechat] [Livechat]
`Videochat`	Link to videochat (use depends on implemented solution)	`<button action="videochat"/>`	[videochat] [Videochat]

# Website embedding

Embedding of a website as iFrame. For usage in the chatbot, see also Webseiten-Einbindung .

Name	Description
`url`	URL of embedded website
`overlay`	boolean for existence of overlay
`overlaytext`	text for the overlay

Model of the webembed element
<webEmbed url="<url>" overlay="<overlay>">
    <overlaytext>
        <![CDATA[
            ...
        ]]>
    </overlaytext>
</webEmbed>

Example for a webembed element
<webEmbed url="https://kauz.ai" overlay="true">
    <overlaytext>
        <![CDATA[
            Bitte lesen Sie vorher unsere <a href="https://kauz.ai/datenschutz/" target="_blank">Datenschutzbestimmungen!</a>
        ]]>
    </overlaytext>
</webEmbed>

# Mapping of Analytics-Events

Analytics Events with standardized tags and data fields can be displayed in the Kauz-Editor-Reporting. A list of the supported tags and required data can be found below.

Event	Tag	Data	Display-Text in Editor-Reporting
Click on `hyperlink`	`kauz.link.open`	url	Derdie Chatbotnutzerin hat auf folgenden Link geklickt: [url]
Click on `searchresultlink`	`kauz.searchResult.open`	url	Derdie Chatbotnutzerin hat folgendes Suchergebnis geöffnet: [url]
Click on `optionlink` DEPRECATED	`kauz.link.option.open`	option	Derdie Chatbotnutzerin hat folgende Option gewählt: [option]
Click on `internalink` DEPRECATED	`kauz.link.internal.open`	url	Derdie Chatbotnutzerin hat auf folgenden InternalLink geklickt: [url]
Click on `createTicket` DEPRECATED	`kauz.button.click`	type: create-ticket	Derdie Chatbotnutzerin hat auf folgenden Button geklickt: [type]
Send searchresult rating	`kauz.searchResult.feedback.question`	rating: (positive\|negative)	Derdie Chatbotnutzerin hat ein Suchergebnis bewertet: [positiv\|negativ]
Send answer rating	`kauz.rating.event`	rating: (positive\|negative)	Derdie Chatbotnutzerin hat eine Chatbotantwort bewertet: [positiv\|negativ]
Send conversation rating	`kauz.rating.conversation`	rating: (positive\|negative)	Derdie Chatbotnutzerin hat die Konversation bewertet: [positiv\|negativ]
Send geo location	`kauz.geo.user.location`	position: (json)	Derdie Chatbotnutzerin hat seine Standortdaten freigegeben: [lat], [long]
Deny geo location	`kauz.geo.user.error`	-	Derdie Chatbotnutzerin hat die Standortdatenfreigabe abgelehnt.
Execute Action.OpenUrl	`kauz.adaptivecard.actionurl.open`	url	Derdie Chatbotnutzerin hat auf folgenden Aktionslink in der Adaptive Card geklickt: [url]
Execute Action.Execute, Verb sendMail	`kauz.adaptivecard.sendMail.open`	address	Derdie Chatbotnutzerin hat auf folgenden E-Mail-Aktionslink in der Adaptive Card geklickt: [address]
Execute Action set-meta	`kauz.actions.set-meta`	relevant meta	Die folgenden Metadaten wurden gesetzt: [{"[key^1]":"[value^1]", ...} ]
Execute Action unset-meta	`kauz.actions.unset-meta`	relevant meta	Die folgenden Metadaten wurden entfernt: [{"[key^1]":"[value^1]", ...} ]
Offer Livechat-Button	`kauz_livechat_offer`	-	Demder Chatbotnutzerin wurde ein Link zum Livechat angeboten.
Click Livechat-Button	`kauz_livechat_click`	url	Derdie Chatbotnutzerin hat den Livechat geöffnet: [url]
Offer Videochat-Button	`kauz_videochat_offer`	-	Demder Chatbotnutzerin wurde ein Link zum Videochat angeboten.
Click Videochat-Button	`kauz_videochat_click`	url	Derdie Chatbotnutzerin hat den Videochat geöffnet: [url]
Unknown tag (fallback)	(unknown)	(unknown)	[tag] : [data]