Understanding whether your customers are satisfied with your products and services is a key priority for every business. However, most feedback collection methods do not allow you to analyse the true sentiment and emotions of your customers. This tutorial provides a step-by-step walk through of how you can integrate IBM Watson Tone Analyzer API with IMIconnect to analyse the sentiment in customer feedback captured via SMS.

Prerequisites

Setup Overview:

A. Create a Service in IMIconnect
B. Get a Phone Number and Assign it to the Service
C. Setup IBM Watson Tone Analyzer API as a reusable integration in IMIconnect
D. Create a Flow to Analyze Customer Feedback
E. Configure a Custom Event API
F. Configure a Rule to Invoke the Flow
G. Invoke your Flow using Postman or any alternative tool


A. Create a Service in IMIconnect

A service is a workspace that allows you to create and manage communication flows, APIs, integrations and configuration settings for any particular communication use case. Here are the steps to create a service:

Step 1 – Add New Service

  1. Click on the Services tab on the top left corner of the screen and choose ADD NEW SERVICE. You will arrive at the CREATE NEW SERVICE dialog box.

Note: Alternatively, you can find ADD NEW SERVICE from the top right corner of IMIconnect.

2. Choose a name for the service and optionally, add the description.

3. Click on the NEXT button at the bottom. You will arrive at the General Settings page, which will have the service key. See the image below.

Note: Service key is used to identify incoming API calls for messaging and event APIs.

Step 2 – Configure the Service Status

Choose the Live option in the Service Configuration section to activate the service.

Note: Click on the REGENERATE button, if you wish to regenerate the service key. Once the service key is regenerated, replace the existing key with the new key in the API request. Please use this option ONLY in case your current service key is not functioning.

Step 3 – Choose Events

  1. Choose the events that you wish to receive on the Callback URLby choosing from the EVENT FILTERS section.
  2. Click on SAVE on the top-right corner of the screen.


B. Get a Phone Number and Assign it to the Service

Now that the service is created, assign a number to it. Follow the below steps to assign number to the service:

Step 1 – Go to Numbers

Click on Numbers under the Services menu to get to Numbers settings

Step 2 – Assign the Number

  1. Choose the number from the drop-down under the SHORTCODES & PHONE NUMBERS FOR SMS section.
  2. Save the choices by clicking on SAVE on the top right corner of the screen.


C. Setup IBM Watson Tone Analyzer API as a reusable integration in IMIconnect

Create a Custom Node

Note: The following integration follows the IBM Watson Tone Analyzer API reference.  

 Step 1 - Add a New Custom Node

  1. Click on Integrations from the top menu. You will arrive at the Integrations screen.
  2. Click on ADD INTEGRATIONS, and then select CUSTOM NODE from the drop-down.

3. Select REST, and then click on the NEXT button on the CREATE NEW CUSTOM NODE window. You will arrive at NODE PROFILE screen.

4. Enter a name for the node in the Node Name field.
5. Select IBM Watson from the Node Category field and optionally, add a description.
6. Choose create blank integration from the drop-down.
7. Click OK at the bottom.  You will arrive at the SETTINGS tab.

Step 2 - Configure the SETTINGS Tab

Configure the Request Details

  1. Enter a name in the Request Name field in the Request Details section.
  2. Choose POST from the drop-down.
  3. Enter the URL: https://gateway.watsonplatform.net/tone-analyzer/api/v3/tone?version=$(version) in the Resource URL field.

Note: The above URL can be taken from IBM Tone Analyzer API. Here is the link: https://www.ibm.com/watson/developercloud/tone-analyzer/api/v3

4. Enter version in the Parameter field.
5. Choose DYNAMIC from the Parameter value type drop-down.
6. Enter version in the Field name field.

Configure the Authorization

Choose BASIC AUTH from the drop-down in the Authorization section.

Configure the User Name

  1. Enter username in the Username field.
  2. Choose DYNAMIC from the Parameter value type drop-down.
  3. Enter Username in the Field name field.

Configure the Password

  1. Enter password in the Password field.
  2. Choose DYNAMIC from the Parameter value type drop-down.
  3. Enter Username in the Field name field.

Configure the Headers

  1. Enter Content-Type from Parameter field.
  2. Choose Static from Parameter value type drop-down.
  3. Enter application/json under Parameter value field.

Configure the Body 

  1. Choose JSON(application/json) from the drop-down.
  2. Enter the code as mentioned below:

{

"text":"$(text)"
}


3. Enter text under Parameter field.
4. Choose DYNAMIC from the Parameter value type drop-down.
5. Enter Text under Field name field.

Configure the Response

  1. Enter Success under Node Event field.
  2. Choose HTTP Status from the drop-down.
  3. Choose equals from the drop-down. 
  4. Enter the value 200 in the Value field.
  5. Choose Success from the drop-down.

6. Enter Tone ID in the Parameter Name field.
7. Choose Body from the drop-down.
8. Enter $.document_tone.tones[0].tone_id under Response Path field.
9. Click ADD NEW from the bottom.
10. Enter Tone ID in the Parameter Name field.
11. Choose Body from the drop-down.
12. Enter $.document_tone.tones[0].tone_name in the Response Path field.

Step 3 - Configure the NODE UI Tab

  1. Enter a name for the field group, for example, Authentication.
  2. Choose Text box from the Field Type drop-down under Username.
  3. Check the Mandatory parameter checkbox.

4. Choose Text box from the Field Type drop-down under Password.
5. Check the Mandatory parameter checkbox.
6. Click ADD NEW FIELD GROUP.

7. Enter a name for the field group, for example, Other Parameters.
8. Choose Text box from the Field Type drop-down under version.
9. Check the Mandatory parameter checkbox.
10. Choose Text box from the Field Type drop-down under text.
11. Check the Mandatory parameter checkbox.
12. Click SAVE at the top of the screen.


D. Create a Flow to Analyze Customer Sentiment

IMIconnect allows you to rapidly configure communication flows using a drag-and-drop flow builder. Here are the steps to configure the flow.

Creating a New Flow

Step 1 - Add a Flow

  1. Click on Flows on the left menu under Settings.
  2. Click on Add New Flow on the top right corner of the Flows screen.

Step 2 – Name the New Flow

  1. Enter a Name for the flow on the CREATE NEW FLOW screen.
  2. Choose the Flow type as Workflow.
  3. Choose Create blank flow from the drop-down.
  4. Click on CREATE FLOW on the top right corner.

Configure the Send Node Settings

Step 1 - Add the Send Node

Drag and drop the Send node on to the flow canvas by dragging from the NODES menu under UTILITIES.

Step 2 – Configure the Node Parameters

Double-click on the Send node to open the configuration menu. See the image below

  1. Click on SMS on the Settings window.
  2. Enter $(msisdn) in the Destination field. 

Note: msisdn stands for Mobile Station ISDN number. It refers to the mapping of telephone number to SIM card.

    3. Choose msisdn from the Destination Type drop-down.
    4.Choose Text from the Message Type drop-down.
    5. Choose the sender id assigned for the service from the senderid drop-down.
    6. Enter the message to be sent to the customer in the Messagebox. 

Note: In the figure below, the message contains $(cust_name) variable. This variable will be replaced with the actual customer name when the SMS is triggered.

   7. Enter a name for the node in the Name field.
   
8. Click on OK at the bottom. 

Step 3 – Configure the 'onerror' Event

The 'onerror' event is configured to record the instance when the flow fails due to any internal error.

To configure the onerror event response: See image below

  1. Drag the red dot next to SMS Node.

2. Choose the onerror from the Node event drop-down on the END FLOW - SETTINGS tab.
3. Choose 102 – Flow completed with an error [Error] from the Custom flow result drop-down.
4. Click on OK at the bottom.

Step 4 – Configure the 'onsuccess' Event 

  1. Drag and drop the green dot next to Send node.

2. Choose onsuccess from the Node event drop-down on the END FLOW - SETTINGS tab.
3. Choose 102 – Flow completed with an error [Error] from the Custom flow result drop-down.
4. Click on OK at the bottom.

Configure the Receive Response Settings

Step 1– Add the Receive Node

Drag and drop the Receive node on to the flow canvas by dragging from the NODES menu under UTILITIES.

Step 2 - Configure the Receive Node Parameters

Double-click on the Receive node to open the configuration menu. You will arrive at the configuration window. See the image below.

  1. Enter the phone number along with the country code for the service in the Number field.
  2. Enter * in the keyword field.
  3. Enter $(msisdn) in the From number field.
  4. Enter the response time in seconds (before which the error is occurred) in the Maximum time out field.
  5. Enter a name for the node in the Name field.
  6. Click on OK at the bottom.

Note: “sysResponseMessage” is a variable where response receipt from the customer is recorded.

Step 3 – Configure the 'ontimeout' Event 

The 'ontimeout' event occurs when the time (in seconds) mentioned in the Time Out field is expired.

To configure the ontimeout event response:

  1. Drag and drop the orange dot that is next to Receive node.

2. Choose ontimeout from the Node event drop-down on the END FLOW - SETTINGS tab.
3. Choose 102 – Flow completed with an error [Error] from the Custom flow result drop-down.
4. Click on OK at the bottom.

Step 4 – Configure the 'onerror' Event 

Follow the process mentioned in the Step 3 of Configure Send Node Parameters.

Step 5 – Configure the 'onsuccess' Event 

Follow the process mentioned in the Step 4 of Configure Send Node Parameters.

Step 6 - Connect the Send and Receive Nodes

  1. Drag and drop the green dot from the Start node to the Send node
  2. Drag and drop the green dot from the Send node to the Receive node to connect send node with the receive node.

Configure the IBM Watson Node

Step 1– Add the IBM Watson Node

Drag and drop the IBM Watson node on to the flow canvas from the NODES menu under IBM WATSON.

Step 2 – Configure the Node Parameters

Double-click on the IBM Watson node to open the Configuration menu. You will arrive at the configuration window. See the image below.

Step 3 - Configure the 'oninvaliddata' Event

The 'oninvaliddata' event occurs when the response received contains no information.

Drag and drop the red dot next to IBM Watson node to configure oninvaliddata event.

To configure oninvaliddata event:

  1. Choose oninvaliddata from the Node event drop-down on the END FLOW - SETTINGS tab.
  2. Choose 102 – Flow completed with an error [Error] from the Custom flow result drop-down.
  3. Click on OK at the bottom.

Step 4 - Configure the 'onauthenticationfail' Event

The 'onauthenticationfail' event occurs when the username or password are not valid.

Drag and drop the red dot that is next to IBM Watson node to configure oninvaliddata event.

To configure onauthenticationfail event:

  1. Choose 'onauthenticationfail from the Node event drop-down on the END FLOW - SETTINGS tab.
  2. Choose 102 – Flow completed with an error [Error] from the Custom flow result drop-down.
  3. Click on OK at the bottom.

Step 5 – Configure the 'onsuccess' Event

Follow the process mentioned in the Step 4 of Configure Send Node Parameters.

Evaluate the Customer Response

The Branch node is used to perform actions based on the response received. It evaluates the response and directs the flow to proceed further accordingly.

Step 1 – Add the Branch Node

Drag and drop the Branch node on to the flow canvas by dragging from the NODES menu under UTILITIES.

Step 2 – Configure the Positive Feedback

Double-click on the Branch node to open the PROPERTIES menu.

Configure the Branch settings

  1. Enter a name for the branch in Branch1 field. For example, Positive Feedback.
  2. Enter $(tone_name) in the $(input_variable) field.
  3. Select the operator as Equals from the drop-down.
  4. Enter the desired word in the value field. For example, Joy.
  5. Click on ADD BRANCH to add a new branch.

Configure Send Node Settings

Step 1 – Add the Send Node 

Drag and drop the Send node on to the flow canvas by dragging from the NODES menu under UTILITIES.

Step 2 - Configure the Send Node 

Follow the steps written in “Step 2 of Configure the Send Node Parameters”.

Step 3 – Configure the 'onerror' Event 

Follow the process mentioned in the Step 3 of Configure Send Node Parameters.

Step 4 – Configure the 'onsuccess' Event

Follow the process mentioned in the Step 4 of Configure Send Node parameters.

Step 3 – Configure the Negative Feedback

Configure the Branch Settings:

  1. Enter a name for the branch in Branch2 field. For example, Negative or Neutral.
  2. Enter $(tone_name) in the $(input_variable) field.
  3. Select the operator as Not Equals from the drop-down.
  4. Enter the desired word in the value field. For example, Joy.
  5. Click on OK at the bottom to apply the changes.

Configure the Send Node

Step 1 – Add the Send Node 

Drag and drop the Send node on to the flow canvas by dragging from the NODES menu under UTILITIES.

Step 2 - Configure the Send Node 

Follow the process mentioned in the Step 2 of Configure the Send Node for Positive Feedback.

Note: The message entered in the Message box for the negative or neutral feedback will differ from what is written in the Step 2 of Configure the Send Node for Positive Feedback. Refer to the image above.

Step 3 - Configure the 'onerror' Event for the Branch Node

Follow the process mentioned in the Step 3 of Configure Send Node Parameters.

Step 4 – Connect the Receive Node with the IBM Watson Node

Drag the green dot that is next to Receive node and drop on to the IBM Watson node.

Step 5 – Configure the 'onerror' Event 

Follow the process mentioned in the Step 3 of Configure Send Node Parameters.

Step 6 – Configure the 'onsuccess' Event

Follow the process mentioned in the Step 4 of Configure Send Node parameters.

Step 7 - Connect the Nodes

  1. Drag the green dot that is next to IBM Watson node and drop on to the Branch node.
  2. Drag the green dot that is next to Branch node and drop on to the Positive Send node.
  3. Select Confirm as event from the Event Selection drop-down and click on OK.
  4. Drag the green dot that is next to Branch node and drop on to the Negative Send node.
  5. Select Confirm as event from the Event Selection drop-down and click on OK.

The overall flow appears as shown below:

Publish the Flow 

  1. Click on MAKE LIVE on the top right corner. You will arrive at Confirm – Make Live message box. 
  2. Click on OK on the Confirm – Make Live message box.

Note: If you wish to add a comment, enter it in the Add an update comment box (optional).

E. Configure a Custom Event API

A custom event is a user-defined event. It can be used to invoke a flow while passing the required API parameters. Follow the steps below to configure custom events:

Step 1 – Add a New Custom Event

  1. Click Custom Events under Settings in the left menu. You will arrive at the Custom Event screen. 
  2. Click ADD NEW CUSTOM EVENT on the Custom Event screen.
  3. Choose Version 1 on the Custom Event screen. 

Step 2 - Name the Custom Event

  1. Choose a name for the custom event.
  2. Click ADD NEW at the bottom on the Create New Custom Event screen. 

Step 3 – Configure the Parameters

  1. Choose String from the Type drop-down and enter msisdn in the Variable Name field. 
  2. Check the Mandatory checkbox.
  3. Click SAVE at the bottom.

The Custom event is created. See the screenshot below.

F. Configure a Rule to Invoke the Flow

Configure a rule to invoke the flow whenever the custom event is triggered. Follow the steps below to configure a rule: 

Step 1 – Create a New Rule

  1. Click on Rules under Settings on the left menu.
  2. Click on ADD NEW RULE button on the top right corner of the screen. 
  3. Click on Custom Event on the Choose a trigger channel screen.

4. Click on SKIP TO ACTIONS on the Enter trigger conditions screen.

Step 2 – Invoke the Flow

  1. Click on Invoke a flow on the Choose an action screen.

2. Choose the flow for which the rule has to be applied from the drop-down, and then click on COMPLETE RULE button.

Step 3 – Configure the Rule Settings

  1. Choose a name for your rule. Choose the start date and time by clicking on the popup calendar.

Note: The end date is optional. 

2. Choose Active from the Set the status of your rule drop-down, and click on the SAVE & SUBMIT button at the bottom.

The Rule is created. See the screenshot below.

The Customer Response Sentiment Analysis service is created.


G. Invoke your Flows using Postman or any alternative tools

Postman is a Google Chrome app, used to interact with HTTP APIs.

Click here to request IMIconnect trial access now using your business e-mail ID.

Did this answer your question?