Tone Analysis

The XO Platform NLP interpreter analyzes user utterances for emotional tone and returns a score you can use to guide conversation flow. For example, if a user is angry, you can automatically route the conversation to a live agent.

Access tone scores from the Context object or configure events from Conversation Intelligence > Events > Sentiment Events. Learn more

---

Tone Types

The Platform evaluates six possible emotions:

Tone	Description
angry	Anger detected in the utterance.
disgust	Disgust detected.
fear	Fear detected.
sad	Sadness detected.
joy	Joy detected.
positive	A special tone that evaluates the general positivity of an utterance.

Tones are not mutually exclusive — an utterance can score high for fear and mild for sadness simultaneously.

Starting from v8.1, the Platform detects emojis in user utterances and sets tone accordingly.

---

Tone Score Scale

Tone emotions are scored on a scale of -3 to +3:

Score	Meaning
+3	User definitely expressed the tone.
+2	User expressed the tone.
+1	User likely expressed the tone.
0	Neutral — tone not expressed or suppressed.
-1	User likely suppressed the tone.
-2	User suppressed the tone.
-3	User definitely suppressed the tone.

Positive values indicate the tone is explicitly expressed; negative values indicate it is explicitly negated.

Examples:

• “I am happy about this news” → positive joy score
• “I am not happy about this news” → negative joy score

---

How Scores Are Calculated

The score is calculated from the base tone value and any modifiers (adverbs or adjectives that amplify or reduce the base tone).

Examples:

• “I am extremely disappointed” → higher angry score than “I am disappointed”
• “I am not disappointed” → negative angry score

The tone analyzer compiles all base tones per emotion and calculates:

• Current node score → stored in message_tone
• Session average score → stored in dialog_tone (reset at end of each session)

---

Context Object Variables

Variable	Scope	Description
message_tone	Current node	Array of tone emotions and scores for the current dialog node.
dialog_tone	Session	Array of average tone emotions and scores for the entire conversation session.

Both variables return arrays of objects with tone_name, count, and level fields. Key/value pairs are only returned when a tone is detected. A level of 0 is returned when the tone is recognized as neutral.

When accessing tone variables, handle positive, negative, zero, and undefined values.

---

Examples

message_tone
   0: tone_name: positive, level: 2
   1: tone_name: disgust, level: -2
   2: tone_name: angry, level: -2

dialog_tone
   0: tone_name: angry, level: -3
   1: tone_name: sad, level: -3
   2: tone_name: positive, level: 3
   3: tone_name: joy, level: 3

Sentence: “I don’t think that this is a good idea and I am not happy with how it came out, especially because of your attitude.”

"dialog_tone": [
  { "tone_name": "joy", "count": 1, "level": 0.67 },
  { "tone_name": "sad", "count": 1, "level": 0.5 },
  { "tone_name": "angry", "count": 1, "level": 0.5 }
]

Sentence: “This is a great idea! I’m super excited already.”

"dialog_tone": [
  { "tone_name": "joy", "count": 1, "level": 3 },
  { "tone_name": "sad", "count": 1, "level": 2.8 },
  { "tone_name": "angry", "count": 1, "level": -3 }
]

Sentence: “This was a funny and casually well-written book, a good read. But it’s a little frustrating because it abandons the narrative without finishing it.”

"dialog_tone": [
  { "tone_name": "joy", "count": 1, "level": 1.5 },
  { "tone_name": "sad", "count": 1, "level": -1.5 },
  { "tone_name": "angry", "count": 1, "level": -1 }
]

Using tone scores in transition conditions:

if context.message_tone.angry > 2.0
    then goTo liveAgent

For more information, see Context Object.

---

Adding Sentiment Words to Concepts

You can extend tone detection by adding custom words to tone concepts during concept training.

Concept name syntax: ~tone-<tonename>-<level>

• <tonename> — one of the 6 tone types listed above.
• <level> — a number from 1 to 7, where 1 = -3, 4 = 0 (neutral), 7 = +3.

Only add base tone words. Intensity modifiers like very or extremely are handled automatically by the Platform.

Examples:

Word	Concept	Meaning
freaking	~tone-angry-7	Very strong anger (+3)
Yikes!	~tone-angry-5	Mild anger (+1)
please	~tone-angry-4	Neutral tone (0)
Thanks!	~tone-angry-1	Not angry at all (-3)