Amplify CLI Interactions Plugin

4.3.2 verified Sat Apr 25 auth: no javascript

Amplify CLI plugin for managing interactions resources (e.g., Amazon Lex chatbots) within an AWS Amplify project. Version 4.3.2 is the latest stable release. This plugin provides CLI commands to add, update, push, and remove interactions resources. It is part of the Amplify CLI ecosystem and relies on the Amplify core infrastructure. Key differentiators: tightly integrated with Amplify CLI workflow, supports Lex bots, and automatically generates CloudFormation templates. Release cadence follows Amplify CLI releases, approximately monthly.

Common errors

error Cannot find module '@aws-amplify/amplify-category-interactions' ↓

cause Plugin not installed globally or not linked in the project.

fix

Run npm install -g @aws-amplify/amplify-category-interactions.

error amplify interactions add only supports Lex bots, not any other service ↓

cause Misunderstanding of what the plugin does.

fix

Use amplify interactions add only for Amazon Lex resources.

error Resource 'myBot' already exists in this project. ↓

cause Duplicate resource name.

fix

Use amplify interactions update to modify existing resource or remove first.

error Invalid bot alias: $LATEST is not allowed for session timeout > 0 ↓

cause Lex requires a specific alias version for persistent sessions.

fix

Use a numeric alias version (e.g., '1') or create an alias in the Lex console.

Warnings

breaking v4 dropped support for Node.js 12 and earlier. ↓

fix Upgrade to Node.js 14 or later.

breaking v3 migrated from AWS SDK v2 to v3 for Lex runtime calls. ↓

fix Update any custom Lex client code to use @aws-sdk/client-lex-runtime-service.

deprecated The `interactions add` command's `--slots` parameter is deprecated in favor of `--intent` object. ↓

fix Use `--intent '{"name":"IntentName","slots":{}}'` instead.

gotcha Plugin must be installed after Amplify CLI or the `amplify interactions` commands won't be recognized. ↓

fix Run `npm install -g @aws-amplify/amplify-category-interactions` after installing `@aws-amplify/cli`.

gotcha Resource names must be alphanumeric and unique within a project; collisions cause silent overwrites. ↓

fix Use `amplify interactions status` to list existing resources before adding.

deprecated The `amplify interactions configure` command has been removed in v3.0.0. ↓

fix Use `amplify interactions update` to modify existing resources.

Install

npm install amplify-category-interactions

yarn add amplify-category-interactions

pnpm add amplify-category-interactions

Imports

default

wrong

const interactionsPlugin = require('@aws-amplify/amplify-category-interactions');

correct

import interactionsPlugin from '@aws-amplify/amplify-category-interactions';

ESM only; TypeScript ships types. Default export is the plugin instance.

InteractionsResourceManager

import { InteractionsResourceManager } from '@aws-amplify/amplify-category-interactions';

Named export for resource management utilities.

type InteractionsConfig

wrong

const { InteractionsConfig } = require('@aws-amplify/amplify-category-interactions');

correct

import type { InteractionsConfig } from '@aws-amplify/amplify-category-interactions';

Type-only import for TypeScript users; avoid runtime usage.

Quickstart

Shows how to add and push a Lex bot resource using the interactions plugin API.

import { addResource, pushResources } from '@aws-amplify/amplify-category-interactions';
import { $TSContext } from 'amplify-cli-core';

async function setupInteractions(context: $TSContext) {
  // Add a Lex bot resource
  await addResource(context, {
    name: 'myChatbot',
    botName: 'OrderFlowers',
    botAlias: '$LATEST',
    sessionTimeout: 5,
    // Additional config
  });

  // Push resources to cloud
  await pushResources(context);
}