Retail Assistant Guide

Steps to integrate the retail assistant into your app

Slang’s Web Retail Assistant (aka SlangRetailAssistant) is a fully trained voice assistant specialized for Web apps in the Retail domain. By integrating with this assistant, apps can help their users perform the following user journey through voice:

• Search for the grocery retail items

The following guide describes the steps that apps need to take in order to integrate with the assistant.

Add the assistant to your project

Depending on your package management system, you can follow the steps under the appropriate tab below to add the SlangRetailAssistant.

npm

$ npm install slang-retail-assistant

import SlangRetailAssistant from "slang-retail-assistant"

yarn

$ yarn add slang-retail-assistant

import SlangRetailAssistant from "slang-retail-assistant"

html

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/slang-retail-assistant@0/index-iife.js"></script>

This should bring SlangRetailAssistant into the scope of your application, and you can refer to it.

Integration Details

First define your actionListener

const retailAssistantListener = {
  onSearch: (searchInfo, session) => {
    // do actual search here with searchInfo
    // searchInfo.retailItem contains the actual item users searched for
    return SlangRetailAssistant.SearchResult.SEARCH_SUCCESS;
  }
};

onSearch action handler is called once the assistant collects the details of the search from the user. It passes SearchInfo and AssistantSession objects as parameters and the handler is expected to return SearchResult once taking necessary action.

All these functions can be async, in which case either return a promise or use async/await.

SearchInfo: Contains the details about the search made by the user. RetailItem is the key property of this object that contains the details about the item being searched. RetailItem contains the following fields to get granular details of the item being searched.

 retailItem.brand - the brand of the item the user searched for
 retailItem.size - an object that describes the size -eg: 2 kg or 2 litres
    // size = { amount :2 , unit : "kg"}
 retailItem.quantity - quantity the user asked for -eg: { amount :2 , unit : "pack"}
 retailItem.variants - an array of the product variants the user asked for
 retailItem.productType - the item name, eg: rice, shampoo, juice, etc.
 retailItem.price - the price that the user specified.
 
 retailItem.description - Utility method that returns the item description 
                          that is ready to be used in the search.
                          If the needs of the app isn't fulfilled with this, you 
                          should be using the individual properties (mentioned above)
                          and generate your own search string

    

Session and return values

SearchResult: The SearchStatus value that you return from the onSearch() API allows you to have fine-grained control over the behavior of the SlangAssistant in the following ways:

• UNSUPPORTED - Indicates that the app is not handling this particular user journey. Slang assistant will speak an appropriate message to the user and exit.

• SEARCH_SUCCESS - Indicates that the search was successful. Slang assistant will speak an appropriate success message to the user and exit.

• SEARCH_FAILURE - Indicates that the search was not successful. Optionally, the reason for the failure can be set in the AssistantSession object. Slang assistant will speak an appropriate failure message to the user and exit. Supported failure reasons are:

  • ITEM_NOT_FOUND - Indicates that the requested item is not sold on the app.

  • ITEM_OUT_OF_STOCK - Indicates that the requested item is not in stock currently.

AssistantSession: This is the assistant's session object for the current interaction with the user. This should be used in conjunction with the search result. Mainly to communicate failure reasons Below are the APIs to be used for these purposes.

session.setSearchFailureReason(SlangRetailAssistant.SearchFailureReason.ITEM_NOT_FOUND);

Set the action listener

SlangRetailAssistant.setAction(retailAssistantListener);

Then initialize slang assistant

SlangRetailAssistant.init({

  assistantID: "<assistant_id>", // you would have gotten it from the Slang team. Required.
  apiKey: "<api_key>", // you would have gotten it from the Slang team. Required.
  environment: "prod", // use "stage" when in development mode. Defaults to stage if omitted.
});

Showing/Hiding the assistant UI (mandatory)

SlangRetailAssistant.ui.show();

Starting the conversation automatically (optional).

By default, the Slang assistant will prompt the user to speak the item to search on the user clicking the trigger. However, if the app would like to prompt users automatically when landed on a specific page, it could do so by using the below API.

SlangRetailAssistant.startConversation(SlangRetailAssistant.UserJourneys.RETAIL_SEARCH);