[tone-analyzer] tone_chat function parameter and API Reference need correction

[dtom90]

Analyze customer engagement tone of API Reference shows the following example request for Node:

var watson = require('watson-developer-cloud');

var tone_analyzer = watson.tone_analyzer({
  username: '{username}',
  password: '{password}',
  version: 'v3',
  version_date: '2016-05-19 '
});

tone_analyzer.tone({ utterances: [
        {"text": "Hello, can you help me", "user": "customer"},
        {"text": "How are you ?", "user": "agent"},
        {"text": "Nothing is working" :, "user": "customer"},
        {"text": "Sorry to hear this", "user": "agent"}
    ]},
  function(err, tone) {
    if (err)
      console.log(err);
    else
      console.log(JSON.stringify(tone, null, 2));
});

The above example should be using the tone_chat function rather than the tone function. Also note the extra colon in the text line {"text": "Nothing is working" :, "user": "customer"},

If these errors are corrected and we test with the following script:

var watson = require('watson-developer-cloud');

var tone_analyzer = watson.tone_analyzer({
  username: '{username}',
  password: '{password}',
  version: 'v3',
  version_date: '2016-05-19 '
});

tone_analyzer.tone_chat({ utterances: [
        {"text": "Hello, can you help me", "user": "customer"},
        {"text": "How are you ?", "user": "agent"},
        {"text": "Nothing is working", "user": "customer"},
        {"text": "Sorry to hear this", "user": "agent"}
    ]},
  function(err, tone) {
    if (err)
      console.log(err);
    else
      console.log(JSON.stringify(tone, null, 2));
});

We get this error:

$ node test_ta.js 
{ Error: Invalid JSON input at line 1, column 1
    at Request._callback (/Users/David/Desktop/tone_analyzer_test/node_modules/watson-developer-cloud/lib/requestwrapper.js:83:15)
    at Request.self.callback (/Users/David/Desktop/tone_analyzer_test/node_modules/request/request.js:188:22)
    at emitTwo (events.js:106:13)
    at Request.emit (events.js:192:7)
    at Request.<anonymous> (/Users/David/Desktop/tone_analyzer_test/node_modules/request/request.js:1171:10)
    at emitOne (events.js:96:13)
    at Request.emit (events.js:189:7)
    at Gunzip.<anonymous> (/Users/David/Desktop/tone_analyzer_test/node_modules/request/request.js:1091:12)
    at Object.onceWrapper (events.js:291:19)
    at emitNone (events.js:91:20)
  code: 400,
  sub_code: 'C00012',
  error: 'Invalid JSON input at line 1, column 1' }

This is because the SDK is expecting two nested utterances: keys, (see tone_analyzer.tone_chat({ utterances: { utterances: [ below) so that it passes the inner object to the API:

var watson = require('watson-developer-cloud');

var tone_analyzer = watson.tone_analyzer({
  username: '{username}',
  password: '{password}',
  version: 'v3',
  version_date: '2016-05-19 '
});

tone_analyzer.tone_chat({ utterances: { utterances: [
        {"text": "Hello, can you help me", "user": "customer"},
        {"text": "How are you ?", "user": "agent"},
        {"text": "Nothing is working", "user": "customer"},
        {"text": "Sorry to hear this", "user": "agent"}
    ]} },
  function(err, tone) {
    if (err)
      console.log(err);
    else
      console.log(JSON.stringify(tone, null, 2));
});

This script results in a successful call:

$ node test_ta.js 
{
  "utterances_tone": [
    {
      "utterance_id": 0,
      "utterance_text": "Hello, can you help me",
      "tones": [
        {
          "score": 0.794472,
          "tone_id": "polite",
          "tone_name": "polite"
        }
      ]
    },
    {
      "utterance_id": 1,

Expected behavior would be a single utterances: key as per the API reference and to match the REST call.

Versions:

$ node --version
v7.5.0
$ npm --version
4.1.2
$ npm list watson-developer-cloud
└── watson-developer-cloud@2.29.0

[germanattanasio]

@aprilwebster can you look into this?

[aprilwebster]

@germanattanasio @dtom90 having a look.

[aprilwebster]

@dtom90 you're right - it looks like there's an error in the documentation. Thank you! I'll follow up with the person on the documentation team regarding the API. In the meantime, I provided sample calls for both the tone and tone_chat endpoints in the wdc node-sdk at https://github.com/watson-developer-cloud/node-sdk/blob/master/examples/tone_analyzer.v3.js. I plugged in my credentials for Tone Analyzer and ran it.

Output is as follows:

tone endpoint:
{
  "document_tone": {
    "tone_categories": [
      {
        "tones": [
          {
            "score": 0.068156,
            "tone_id": "anger",
            "tone_name": "Anger"
          },
          {
            "score": 0.095882,
            "tone_id": "disgust",
            "tone_name": "Disgust"
          },
          {
            "score": 0.133478,
            "tone_id": "fear",
            "tone_name": "Fear"
          },
          {
            "score": 0.427032,
            "tone_id": "joy",
            "tone_name": "Joy"
          },
          {
            "score": 0.129309,
            "tone_id": "sadness",
            "tone_name": "Sadness"
          }
        ],
        "category_id": "emotion_tone",
        "category_name": "Emotion Tone"
      },
      {
        "tones": [
          {
            "score": 0,
            "tone_id": "analytical",
            "tone_name": "Analytical"
          },
          {
            "score": 0,
            "tone_id": "confident",
            "tone_name": "Confident"
          },
          {
            "score": 0,
            "tone_id": "tentative",
            "tone_name": "Tentative"
          }
        ],
        "category_id": "language_tone",
        "category_name": "Language Tone"
      },
      {
        "tones": [
          {
            "score": 0.382079,
            "tone_id": "openness_big5",
            "tone_name": "Openness"
          },
          {
            "score": 0.271994,
            "tone_id": "conscientiousness_big5",
            "tone_name": "Conscientiousness"
          },
          {
            "score": 0.538118,
            "tone_id": "extraversion_big5",
            "tone_name": "Extraversion"
          },
          {
            "score": 0.593281,
            "tone_id": "agreeableness_big5",
            "tone_name": "Agreeableness"
          },
          {
            "score": 0.280439,
            "tone_id": "emotional_range_big5",
            "tone_name": "Emotional Range"
          }
        ],
        "category_id": "social_tone",
        "category_name": "Social Tone"
      }
    ]
  }
}
tone_chat endpoint:
{
  "utterances_tone": [
    {
      "utterance_id": 0,
      "utterance_text": "My charger isn’t working.",
      "tones": [
        {
          "score": 0.571926,
          "tone_id": "sad",
          "tone_name": "sad"
        }
      ]
    },
    {
      "utterance_id": 1,
      "utterance_text": "Thanks for reaching out. Can you give me some more detail about the issue?",
      "tones": [
        {
          "score": 0.961781,
          "tone_id": "polite",
          "tone_name": "polite"
        }
      ]
    },
    {
      "utterance_id": 2,
      "utterance_text": "I put my charger in my phone last night to charge and it isn't working. Which is ridiculous, it's a new charger, I bought it yesterday.",
      "tones": [
        {
          "score": 0.882958,
          "tone_id": "sad",
          "tone_name": "sad"
        },
        {
          "score": 0.576779,
          "tone_id": "frustrated",
          "tone_name": "frustrated"
        }
      ]
    },
    {
      "utterance_id": 3,
      "utterance_text": "I’m sorry you’re having issues with charging. What kind of charger do you have?",
      "tones": [
        {
          "score": 0.844104,
          "tone_id": "polite",
          "tone_name": "polite"
        },
        {
          "score": 0.798921,
          "tone_id": "sympathetic",
          "tone_name": "sympathetic"
        }
      ]
    }
  ]
}

[dtom90]

@aprilwebster thanks for the update. Note that In your example the expanded JSON that is passed into tone_chat has two nested utterances: keys. This was the main point of confusion from a user, and I tend to agree, unless there is a reason for this.

[aprilwebster]

@dtom90 - sorry, I misread and thought it was just an api documentation issue. I've made the change to fix the nested utterances key and created a PR. I'll let you know when it gets approved and merged in.

[dtom90]

@aprilwebster no worries, thanks for the fix!

[ibmkaga]

@aprilwebster any update on this, i see that the issue mentioned by @dtom90 still exist and luckily i found this post otherwise it was difficult to understand why am i receiving invalid JSON API error. I am using the tone_chat endpoint only and with a single 'utterances' object (like u mentioned in ur sample code, linked in your comment), it fails right now, but with what @dtom90 has mentioned, it works i.e. two nested utterances object. Is this because am using from OpenWhisk(IBM functions) now, can that possibly have an old copy of hte SDK?

[plummera]

Real quick on that turnaround... ;p

[plummera]

Following up here. Basically; if your getting this error, you haven't collected enough content to be analyzed. Watson needs at least a minimum of 128K mem I think to process... i.e.: ERROR: NOT ENOUGH DATA