AWS Mobile Hub Developer Guide
Developer Guide

Add Conversational Bots to Your Mobile App with Amazon Lex

The following reference content only applies to existing apps that were built using the AWS Mobile SDKs for iOS and Android. If you’re building a new mobile or web app, or you're adding cloud capabilities to an existing app, visit the Amplify Framework website instead. Documentation for the AWS Mobile SDKs for iOS and Android is now part of the Amplify Framework.

Overview

Add the natural language understanding that powers Amazon Alexa to your mobile app. The AWS mobile Hub Conversational Bots feature provides ready-made bot templates using the Amazon Lex service.

Set Up Your Backend

  1. Complete the Get Started steps before your proceed.

  2. Enable Conversational Bots: Open your project in Mobile Hub and choose the Conversational Bots tile to enable the feature.

    1. Choose one of the sample Bots or import one that you have created in the Amazon Lex console.

  3. When the operation is complete, an alert will pop up saying "Your Backend has been updated", prompting you to download the latest copy of the cloud configuration file. If you're done configuring the feature, choose the banner to return to the project details page.

  4. From the project detail page, every app that needs to be updated with the latest cloud configuration file will have a flashing Integrate button. Choose the button to enter the integrate wizard.

  5. Update your app with the latest copy of the cloud configuration file. Your app now references the latest version of your backend. Choose Next and follow the Cloud API documentation below to connect to your backend.

Connect to your backend

To add AWS Mobile Conversational Bots to your app

Android - JavaAndroid - KotliniOS - Swift
Android - Java

Set Up Your Backend steps.

  1. Add the following permissions to your AndroidManifest.xml:

    <uses-permission android:name="android.permission.RECORD_AUDIO" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  2. Add the following to your app/build.gradle:

    dependencies{ implementation ('com.amazonaws:aws-android-sdk-lex:2.7.+@aar') {transitive = true;} }
  3. For each Activity where you make calls to Amazon Lex, import the following APIs.

    import com.amazonaws.mobileconnectors.lex.interactionkit.Response; import com.amazonaws.mobileconnectors.lex.interactionkit.config.InteractionConfig; import com.amazonaws.mobileconnectors.lex.interactionkit.ui.InteractiveVoiceView;
  1. Add a voice button to an activity or fragment layout

    1. Add a voice_component to your layout file.

      <com.amazonaws.mobileconnectors.lex.interactionkit.ui.InteractiveVoiceView android:id="@+id/voiceInterface" layout="@layout/voice_component" android:layout_width="200dp" android:layout_height="200dp"/>
    2. In your strings.xml file add the region for your bot. Note: Currently bots are only supported in US Virginia East (us-east-1).

      <string name="aws_region">us-east-1</string>
    3. Initialize the voice button

      Add the following init() function to the onCreate() of the activity where your Bot will be used.

      Initialize AWSMobileClient before the call to init(), as the InteractiveVoiceView in the function connects to Amazon Lex using the credentials provider object created by AWSMobileClient .

      import com.amazonaws.mobile.client.AWSMobileClient; import com.amazonaws.mobile.client.AWSStartupHandler; import com.amazonaws.mobile.client.AWSStartupResult; import com.amazonaws.mobileconnectors.lex.interactionkit.Response; import com.amazonaws.mobileconnectors.lex.interactionkit.config.InteractionConfig; import com.amazonaws.mobileconnectors.lex.interactionkit.ui.InteractiveVoiceView; public class MainActivity extends AppCompatActivity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); AWSMobileClient.getInstance().initialize(this, new AWSStartupHandler() { @Override public void onComplete(AWSStartupResult awsStartupResult) { Log.d("YourMainActivity", "AWSMobileClient is instantiated and you are connected to AWS!"); } }).execute(); init(); } public void init(){ InteractiveVoiceView voiceView = (InteractiveVoiceView) findViewById(R.id.voiceInterface); voiceView.setInteractiveVoiceListener( new InteractiveVoiceView.InteractiveVoiceListener() { @Override public void dialogReadyForFulfillment(Map slots, String intent) { Log.d(LOG_TAG, String.format( Locale.US, "Dialog ready for fulfillment:\n\tIntent: %s\n\tSlots: %s", intent, slots.toString())); } @Override public void onResponse(Response response) { Log.d(LOG_TAG, "Bot response: " + response.getTextResponse()); } @Override public void onError(String responseText, Exception e) { Log.e(LOG_TAG, "Error: " + responseText, e); } }); voiceView.getViewAdapter().setCredentialProvider(AWSMobileClient.getInstance().getCredentialsProvider()); //replace parameters with your botname, bot-alias voiceView.getViewAdapter() .setInteractionConfig( new InteractionConfig("YOUR-BOT-NAME","$LATEST")); voiceView.getViewAdapter() .setAwsRegion(getApplicationContext() .getString(R.string.aws_region)); } }
Android - Kotlin
  1. Set up AWS Mobile SDK components with the following steps.

    1. Add the following permissions to your AndroidManifest.xml:

      <uses-permission android:name="android.permission.RECORD_AUDIO" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    2. Add the following to your app/build.gradle:

      dependencies{ implementation ('com.amazonaws:aws-android-sdk-lex:2.7.+@aar') {transitive = true;} }
    3. For each Activity where you make calls to Amazon Lex, import the following APIs.

      import com.amazonaws.mobileconnectors.lex.interactionkit.Response; import com.amazonaws.mobileconnectors.lex.interactionkit.config.InteractionConfig; import com.amazonaws.mobileconnectors.lex.interactionkit.ui.InteractiveVoiceView;
  2. Add a voice button to an activity or fragment layout

    1. Add a voice_component to your layout file.

      <com.amazonaws.mobileconnectors.lex.interactionkit.ui.InteractiveVoiceView android:id="@+id/voiceInterface" layout="@layout/voice_component" android:layout_width="200dp" android:layout_height="200dp"/>
    2. In your strings.xml file add the region for your bot. Note: Currently bots are only supported in US Virginia East (us-east-1).

      <string name="aws_region">us-east-1</string>
    3. Initialize the voice button

      In the onCreate() of the activity where your Bot will be used, call init().

      fun init() { voiceInterface.interactiveVoiceListener = object : InteractiveVoiceView.InteractiveVoiceListener() { override fun dialogReadyFOrFulfillment(slots: Map, intent: String) { Log.d(TAG, "Dialog ready for fulfillment:\n\tIntent: $intent") } override fun onResponse(response: Response) { Log.d(TAG, "Bot response: ${response.textResponse}") } override fun onError(responseText: String, e: Exception) { Log.e(TAG, "Error: ${e.message}") } } with (voiceInterface.viewAdapter) { credentialsProvider = AWSMobileClient.getInstance().credentialsProvider interactionConfig = InteractionConfig("YOUR-BOT-NAME","$LATEST") awsRegion = applicationContext.getString(R.string.aws_region) } }
iOS - Swift
  1. Set up AWS Mobile SDK components with the following steps.

    1. Podfile that you configure to install the AWS Mobile SDK must contain:

      platform :ios, '9.0' target :'YOUR-APP-NAME`' do use_frameworks! pod 'AWSLex', '~> 2.6.13' # other pods end

      Run pod install --repo-update before you continue.

      If you encounter an error message that begins "[!] Failed to connect to GitHub to update the CocoaPods/Specs . . .", and your internet connectivity is working, you may need to update openssl and Ruby.

    2. Classes that call Amazon Lex APIs must use the following import statements:

      import AWSCore import AWSLex
  2. Add permissions to your info.plist that allow the app to use the microphone of a device.

    <plist version = "1.0"></plist> <dict> <!-- . . . --> <key>NSMicrophoneUsageDescription</key> <string>For demonstration of conversational bots</string> <!-- . . . --> </dict>
  3. Add your backend service configuration to the app.

    From the location where your Mobile Hub configuration file was downloaded in a previous step, drag awsconfiguration.json into the folder containing your info.plist file in your Xcode project.

    Select Copy items if needed and Create groups, if these options are offered.

  4. Add a voice button UI element that will let your users speak to Amazon Lex to an activity.

    1. Create a UIView in a storyboard or xib file.

    2. Map the UIView to the AWSLexVoiceButton class of the AWS Mobile SDK.

    3. Link the UIView to your ViewController.

    
                           Image of creating a button and mapping it to the AWS Mobile SDK in Xcode.
  5. Register the voice button.

    The following code shows how use the viewDidLoad method of your View Controller to enable your voice button to respond to Amazon Lex success and error messages The code conforms the class to AWSLexVoiceButtonDelegate. It initializes the button by binding it to the bot you configured in your Mobile Hub project, and registers the button as the AWSLexVoiceButtonKey of your Amazon Lex voice interaction client.

    import UIKit import AWSLex import AWSAuthCore class VoiceChatViewController: UIViewController, AWSLexVoiceButtonDelegate { override func viewDidLoad() { // Set the bot configuration details // You can use the configuration constants defined in AWSConfiguration.swift file let botName = "YOUR-BOT-NAME" let botRegion: AWSRegionType = "YOUR-BOT-REGION" let botAlias = "$LATEST" // set up the configuration for AWS Voice Button let configuration = AWSServiceConfiguration(region: botRegion, credentialsProvider: AWSMobileClient.sharedInstance().getCredentialsProvider()) let botConfig = AWSLexInteractionKitConfig.defaultInteractionKitConfig(withBotName: YOUR-BOT-NAME, botAlias: :YOUR-BOT-ALIAS) // register the interaction kit client for the voice button using the AWSLexVoiceButtonKey constant defined in SDK AWSLexInteractionKit.register(with: configuration!, interactionKitConfiguration: botConfig, forKey: AWSLexVoiceButtonKey) super.viewDidLoad() (self.voiceButton as AWSLexVoiceButton).delegate = self } }
  6. Handle Amazon Lex success and error messages by adding the following delegate methods for the Voice Button in your View Controller.

    func voiceButton(_ button: AWSLexVoiceButton, on response: AWSLexVoiceButtonResponse) { // handle response from the voice button here print("on text output \(response.outputText)") } func voiceButton(_ button: AWSLexVoiceButton, onError error: Error) { // handle error response from the voice button here print("error \(error)") }