Tone Analyzer

IBM Cloud® Functions is deprecated. Existing Functions entities such as actions, triggers, or sequences will continue to run, but as of 28 December 2023, you can’t create new Functions entities. Existing Functions entities are supported until October 2024. Any Functions entities that still exist on that date will be deleted. For more information, see Deprecation overview.

The installable IBM Watson® Tone Analyzer service uses linguistic analysis to detect emotional and language tones in written text.

The Watson packages are deprecated. Please use the Watson SDKs to perform Watson related functionality. For more information about which Watson SDK is included in the available runtimes, see the Functions runtime documentation.

This service can analyze tone at both the document and sentence levels. You can use the service to understand how your written communications are perceived and then to improve the tone of your communications. Businesses can use the service to learn the tone of their customers' communications and to respond to each customer, or to understand and improve their customer conversations..

Request logging is disabled for the Tone Analyzer service. The service doesn't log or retain data from requests and responses, regardless of whether the X-Watson-Learning-Opt-Out request header is set.

The Tone Analyzer package contains the following entities. You can find more details in the Tone Analyzer API reference by clicking the entity name.

Table 2. Tone analyzer package entities
Entity	Type	Parameters	Description
`tone-analyzer-v3`	Package	`username`, `password`, `iam_access_token`, `iam_apikey`, `iam_url`, `headers`, `headers[X-Watson-Learning-Opt-Out]`, `url`	Work with the Tone Analyzer service.
`tone`	Action	`username`, `password`, `iam_access_token`, `iam_apikey`,`iam_url`, `headers`, `headers[X-Watson-Learning-Opt-Out]`, `url`, `tone_input`, `content_type`, `sentences`, `tones`, `content_language`, `accept_language`	Analyze general tone.
`tone-chat`	Action	`username`, `password`, `iam_access_token`, `iam_apikey`, `iam_url`, `headers`, `headers[X-Watson-Learning-Opt-Out]`, `url`, `utterances`, `content_language`, `accept_language`	Analyze customer engagement tone.

Creating a Tone Analyzer service instance

Before you install the package, you must create a Tone Analyzer service instance and service credentials.

Create a Tone Analyzer service instance.
When the service instance is created, service credentials are automatically created for you.

Installing the Tone Analyzer package

After you have a Tone Analyzer service instance, install the Tone Analyzer package into your namespace.

Installing from the Cloud Functions CLI

Install the Tone Analyzer package from the CLI. Be sure to install the Cloud Functions plug-in for the IBM Cloud CLI first.

To install the Tone Analyzer package:

Clone the Tone Analyzer package repo.

git clone https://github.com/watson-developer-cloud/openwhisk-sdk

Deploy the package.

ibmcloud fn deploy -m openwhisk-sdk/packages/tone-analyzer-v3/manifest.yaml

Verify that the package is added to your package list.

ibmcloud fn package list

Example output

packages
/myOrg_mySpace/tone-analyzer-v3                        private

Bind the credentials from the Tone Analyzer instance you created to the package.
```
ibmcloud fn service bind tone_analyzer tone-analyzer-v3
```
Depending on the region where you created the service instance, the service instance might be named differently because it is an IAM service. If the command fails, use the following service name for the bind command:
```
ibmcloud fn service bind tone-analyzer tone-analyzer-v3
```
Example output
```
Credentials 'Credentials-1' from 'tone_analyzer' service instance 'Watson Tone Analyzer' bound to 'tone-analyzer-v3'.
```

Verify that the package is configured with your Tone Analyzer service instance credentials.

ibmcloud fn package get tone-analyzer-v3 parameters

Example output

ok: got package tone-analyzer-v3, displaying field parameters
[
    {
    "key": "__bx_creds",
    "value": {
      "tone_analyzer": {
        "credentials": "Credentials-1",
        "instance": "Watson Tone Analyzer",
        "password": "AAAA0AAAAAAA",
        "url": "https://gateway.watsonplatform.net/assistant/api",
        "username": "00a0aa00-0a0a-12aa-1234-a1a2a3a456a7"
      }
    }
    }
]

Installing from the Cloud Functions console

Install the Tone Analyzer package from the console.

In the Cloud Functions console, go to the Create page.
Select the namespace that you want to install the package into.
Click Install Packages.
Click the Watson Package group.
Click the Tone Analyzer Package.
Click Install.
After the package is installed you are redirected to the actions page and can search for your new package, which is named tone-analyzer-v3.
To use the actions in the tone-analyzer-v3 package, you must bind service credentials to the actions.
- To bind service credentials to all actions in the package, follow steps 4 and 5 in the CLI instructions.
- To bind service credentials to individual actions, complete the following steps in the console:
You must complete the following steps for each action that you want to use.
1. Click an action from the tone-analyzer-v3 Package that you want to use. The details page for that action opens.
2. In the left navigation, click the Parameters section.
3. Enter a new parameter. For the key, enter __bx_creds. For the value, paste in the service credentials JSON object from the service instance that you created earlier.

Using the Tone Analyzer package

To use the actions in this package, run commands in the following format:

ibmcloud fn action invoke tone-analyzer-v3/<action_name> -b -p <param name> <param>

All actions require a version parameter in the format YYYY-MM-DD. When the API is changed in a backwards-incompatible way, a new version date is released.

This package's functions use the current version of Tone Analyzer, 2017-09-21. Try out the tone action.

ibmcloud fn action invoke tone-analyzer-v3/tone -b -p version 2017-09-21 -p text "i hope you're having a wonderful day"