getting-started.mdx

AWS Amplify Interactions category enables AI-powered chatbots in your web or mobile apps. You can use Interactions to configure your backend chatbot provider and to integrate a chatbot UI into your app with just a single line of code.

Interactions with AWS

AWS Amplify implements Amazon Lex as the default chatbots service. Amazon Lex supports creating conversational bots with the same deep learning technologies that power Amazon Alexa.

The recommended approach is to begin your new App integration with AWS LexV2, as the default module exports are associated with AWS LexV2 APIs. Instructions for AWS LexV1 setup can be found in the following section.

Setup AWS LexV2 bot

You can create Amazon Lex V2 chatbot in Amazon Lex console. To create your bot, follow the steps shown in Amazon Lex V2 Developer Guide.

With manual setup, you also need to add AWS Lex V2 API permissions to IAM roles and bot details to configure your app.

For adding IAM permissions, find you IAM role and attach the policy below (remember to replace the template with real value):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["lex:RecognizeText", "lex:RecognizeUtterance"],
      "Resource": "arn:aws:lex:<Region>:<Account>:bot-alias/<BotId>/<BotAliasId>"
    }
  ]
}

import { Amplify } from 'aws-amplify';
import { parseAmplifyConfig } from "aws-amplify/utils";
import amplifyconfig from './amplifyconfiguration.json';

Amplify.configure({
  ...parseAmplifyConfig(amplifyconfig),
  Interactions: {
    LexV2: {
      '<V2BotName>': {
        aliasId: '<V2BotAliasId>',
        botId: '<V2BotBotId>',
        localeId: '<V2BotLocaleId>',
        region: '<V2BotRegion>'
      }
    }
  }
});

Make sure you call Amplify.configure as early as possible in your application’s life-cycle. A missing configuration or NoCredentials error is thrown if Amplify.configure has not been called before other Amplify JavaScript APIs. Review the Library Not Configured Troubleshooting guide for possible causes of this issue.

Setup AWS LexV1 bot

Create new LexV1 chatbot with Amplify CLI

Prerequisite: Install and configure the Amplify CLI

Run the following command in your project's root folder:

amplify add interactions

Adding interactions from the CLI only allows you to create a Lex V1 bot. If you want to create a LexV2 bot, you can do so following the instructions here.

The CLI will lead you through the steps to specify the chatbot to be created.

You can choose to start from a sample chatbot or start from scratch. If you choose to start from scratch, the CLI will prompt you with a series of questions to set the intents and slots for the chatbot.

You are allowed to run the amplify add interactions command multiple times to add multiple chatbots into your project.

The Interactions category utilizes the Authentication category behind the scenes to authorize your app to send analytics events.

The add command automatically creates a backend configuration locally. To update your backend in the cloud, run:

amplify push

Upon successful execution of the push command, a configuration file called amplifyconfiguration.json will be copied to your configured source directory, for example ./src.

If your Interactions resources were created with Amplify CLI version 1.6.4 and below, you will need to manually update your project to avoid Node.js runtime issues with AWS Lambda. Read more

Manual setup

You can create Amazon Lex V1 chatbot in Amazon Lex console. To create your bot, follow the steps shown in Amazon Lex V1 Developer Guide.

With manual setup, you need to add AWS Lex API permissions to IAM roles and bot details to configure your app.

For adding AWS Lex API permissions, find you IAM role and attach the policy below (remember to replace the template with real value):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["lex:PostText", "lex:PostContent"],
      "Resource": "arn:aws:lex:<Region>:<Account>:bot:<BotName>:<BotAlias>"
    }
  ]
}

Configuring bot details in your web app like this:

import { Amplify } from 'aws-amplify';
import { parseAmplifyConfig } from "aws-amplify/utils";
import amplifyconfig from './amplifyconfiguration.json';

Amplify.configure({
  ...parseAmplifyConfig(amplifyconfig),
  Interactions: {
    LexV1: {
      '<V1BotName>': {
        alias: '<V1BotAlias>',
        region: '<V1BotRegion>'
      }
    }
  }
});

Make sure you call Amplify.configure as early as possible in your application’s life-cycle. A missing configuration or NoCredentials error is thrown if Amplify.configure has not been called before other Amplify JavaScript APIs. Review the Library Not Configured Troubleshooting guide for possible causes of this issue.

Configure frontend

Make sure that the @aws-amplify/interactions package has the same version number as the aws-amplify package in your package.json file.

import js0 from '/src/fragments/lib/interactions/js/frontend.mdx';

<Fragments fragments={{ javascript: js0 , angular: js0, nextjs: js0, react: js0, vue: js0 }} />

import reactnative1 from '/src/fragments/lib/interactions/react-native/frontend.mdx';

<Fragments fragments={{ 'react-native': reactnative1 }} />