# Kauz-Markup

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

The chatbot answers mostly contain markdown that typical for LLMs (e.g. ** for bold text). However, some answer elements consist of mark-up specific to the Kauz.ai platform:

custom elements such as click options
all elements in non-generated Topic Catalogue-answers

# 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, 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>

# 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)
`actions`	additional action information for the frontend	see below
`card`	Adaptive Card	see below

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

# Content Elements

# 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>

# 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>}`
`optionlink`	for clickable options. Options can be attached to Topic Catalogue answers or be inserted into generated answers via the prompt. 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>}`
`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>}`

# 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. The list of supported tags, their data fields, their targets and their display texts is maintained on a dedicated page, together with the endpoint used to send them.

Analytics-Events

../analytics-events/