Twilio AI Assistant Deployment Tool - Owl Shoes

Note

Twilio AI Assistants is a Twilio Alpha project that is currently in Developer Preview.

Twilio AI Assistant Deployment Tool - Owl Shoes

A modular tool for deploying a Twilio AI Assistant with pre-configured tools and knowledge bases. This project provides a structured way to create and configure an AI Assistant for retail customer service.

Features

Automated assistant creation with retail-focused personality
Pre-configured tools for common retail operations:
- Customer lookup
- Order management
- Returns processing
- Product recommendations
- Customer surveys
Knowledge base integration for FAQs
Modular and maintainable codebase
Optional front-end integration for demo purposes
Optional Segment integration for analytics
Optional Chat Service integration for messaging
Optional Voice Intel integration for voice calls
Optional Flex integration for voice calls
Optional Studio integration for voice calls

Prerequisites

Node.js (v14 or higher)
Twilio account with AI Assistant access (accept AI Assistants Terms & Conditions)
Twilio Account SID and Auth Token
Airtable account, App ID and API token

Project Structure

twilio-ai-assistant-demo-owl-shoes-web-app/
├── README.md                                # Project documentation and setup instructions
├── LICENSE                                  # MIT license file
├── package.json                             # Project dependencies and scripts
├── .env.example                             # Template for environment variables
├── .twilioserverlessrc                      # Twilio Serverless configuration
├── functions/                               # Serverless function implementations
│   ├── channels/                            # Channel-specific handlers
│   │   ├── conversations/                   # Twilio Conversations handlers
│   │   │   ├── flex-webchat.protected.js    # Flex webchat integration
│   │   │   ├── messageAdded.protected.js    # Message handling
│   │   │   └── response.js                  # Response handling
│   │   ├── messaging/                       # SMS/WhatsApp handlers
│   │   │   ├── incoming.protected.js        # Incoming message handling
│   │   │   └── response.js                  # Response handling
│   │   └── voice/                           # Voice call handlers
│   │       └── incoming-call.js             # Incoming call handling
│   ├── front-end/                           # Front-end integration endpoints
│   │   ├── create-customer.js               # Customer creation endpoint
│   │   └── create-order.js                  # Order creation endpoint
│   └── tools/                               # Assistant tool implementations
│       ├── create-survey.js                 # CSAT survey creation
│       ├── customer-lookup.js               # Customer information lookup
│       ├── order-lookup.js                  # Order status lookup
│       ├── place-order.js                   # Order placement
│       ├── products.js                      # Product catalog access
│       ├── return-order.js                  # Return processing
│       └── send-to-flex.js                  # Flex transfer handler
├── prompts/                                 # Assistant configuration
│   └── assistant-prompt.md                  # Core personality and behavior
├── src/                                     # Deployment and configuration
│   ├── deploy.js                            # Main deployment script
│   ├── config/                              # Configuration modules
│   │   ├── assistant.js                     # Assistant settings
│   │   ├── knowledge.js                     # Knowledge base config
│   │   └── tools.js                         # Tool configurations
│   └── lib/                                 # Core functionality
│       ├── createAssistant.js               # Assistant creation
│       ├── createKnowledge.js               # Knowledge base setup
│       └── createTools.js                   # Tool creation and attachment
└── web/                                     # Demo Web Application
    ├── README.md                            # Web app documentation
    ├── package.json                         # Web app dependencies and scripts
    ├── vite.config.ts                       # Vite configuration
    ├── tsconfig.json                        # TypeScript configuration
    ├── tailwind.config.ts                   # Tailwind CSS configuration
    ├── public/                              # Static assets
    └── src/                                 # Web app source code
        ├── App.tsx                          # Main application component
        ├── index.css                        # Global styles
        ├── components/                       # React components
        │   ├── ui/                          # UI components (shadcn/ui)
        │   ├── Navigation.tsx               # Navigation component
        │   └── checkout/                    # Checkout components
        ├── hooks/                           # Custom React hooks
        ├── integrations/                    # Service integrations
        │   ├── airtable/                    # Airtable client and types
        │   └── twilio/                      # Twilio client
        ├── lib/                             # Utility functions
        ├── pages/                           # Page components
        │   ├── Cart.tsx                     # Shopping cart page
        │   ├── Checkout.tsx                 # Checkout page
        │   ├── Contact.tsx                  # Contact page with chat
        │   ├── Index.tsx                    # Home page
        │   └── ProductDetails.tsx           # Product details page
        └── types/                           # TypeScript type definitions

Part 1: Deploying the AI Assistant

Quick Start

Clone the repository:

git clone https://github.com/twilio-samples/ai-assistant-demo-owl-shoes.git
cd ai-assistant-demo-owl-shoes

Install dependencies:

npm install

Configure Airtable:

a. Copy the Airtable base using this link

b. Once copied, you'll find the base ID in your Airtable URL (it looks like 'appXXXXXXXXXXXXX')

c. Generate an Airtable access token:
- Go to your Airtable account
- Click "Create new token"
- Give it a name and select the necessary scopes for your base
- Copy the generated token
The base includes tables for:
- Customers: Customer information for personalization
- Orders: Order history data
- Inventory: Product catalog information
- Surveys: CSAT surveys conducted by the Assistant
- Returns: Returns proccessed by the Assistant
Its recommend you add yourself and some additional data to the table for demo purposes.
Configure environment variables:

cp .env.example .env
# Edit .env and add your credentials:
# TWILIO_ACCOUNT_SID=your_account_sid
# TWILIO_AUTH_TOKEN=your_auth_token
# AIRTABLE_API_KEY=your_airtable_api_key
# AIRTABLE_BASE_ID=your_airtable_base_id

⚠️ Ensure you accept the Terms and Conditions in the Twilio Console by visiting the AI Assistants page before running the script.

Deploy the assistant:

# Deploy the AI Assistant
npm run deploy

# Redeploy Functions (useful during development)
npm run redeploy

# Start the Web App in development mode
npm run deploy:web

Connecting Channels

After deploying your functions and assistant, you'll need to connect various Twilio channels. Here's how to set up each channel:

Voice Channel

⚠️ Add your Assistant ID to the incoming-call function

Configure your Twilio voice number to use the AI Assistant:

Via Twilio CLI:

twilio phone_number <your-twilio-number> \
    --voice-url=https://<your-functions-domain>.twil.io/channels/voice/incoming-call

OR If Using Voice Intel.

twilio phone_number <your-twilio-number> \
    --voice-url=https://<your-functions-domain>.twil.io/channels/voice/incoming-call-voice-intel

Via Twilio Console:

Open your voice-capable phone number
Set the "When a call comes in" function to: https://<your-functions-domain>.twil.io/channels/voice/incoming-call or https://<your-functions-domain>.twil.io/channels/voice/incoming-call-voice-intel

Messaging Channels

SMS

Via Twilio CLI:

twilio phone_number <your-twilio-number> \
    --sms-url=https://<your-functions-domain>.twil.io/channels/messaging/incoming

Via Twilio Console:

Open your SMS-capable phone number or Messaging Service
Set the "When a message comes in" webhook to: https://<your-functions-domain>.twil.io/channels/messaging/incoming

WhatsApp

Go to your WhatsApp Sandbox Settings in the Twilio Console
Configure the "When a message comes in" function to: https://<your-functions-domain>.twil.io/channels/messaging/incoming

Note: To use the same webhook for multiple assistants, add the AssistantSid as a parameter:

https://<your-functions-domain>.twil.io/channels/messaging/incoming?AssistantSid=AI1234561231237812312

Conversations Channel

Set up Twilio Conversations integration:

Create a Conversations Service or use your default service
Run this Twilio CLI command to configure the webhook:

twilio api:conversations:v1:services:configuration:webhooks:update \
    --post-webhook-url=https://<your-functions-domain>.twil.io/channels/conversations/messageAdded \
    --chat-service-sid=<your-conversations-service-sid> \
    --filter=onMessageAdded

Follow the Twilio Conversations documentation to connect your preferred channels

Tool Functions

The assistant uses several tool functions that need to be implemented:

Customer Lookup (/tools/customer-lookup)
- GET request
- Looks up customer information
- Returns customer details
Order Lookup (/tools/order-lookup)
- GET request
- Retrieves order information
- Validates order ID
- Input schema:
```
{
  order_confirmation_digits: string; //Last 4 digits of customers order
}
```
Create Survey (/tools/create-survey)
- POST request
- Creates customer satisfaction survey records
- Captures rating and feedback
- Requires customer identification via x-identity header
- Input schema:
```
{
  rating: number,    // Required: 1-5 rating
  feedback: string   // Optional: customer feedback
}
```
Order Return (/tools/return-order)
- POST request
- Initiates return process for delivered orders
- Validates order status and existing returns
- Creates return record and updates order
- Input schema:
```
{
  order_id: string,      // Required: order identifier
  return_reason: string  // Required: reason for return
}
```
Place Order (/tools/place-order)
- POST request
- Creates new orders using customer information
- Handles product lookup and pricing
- Calculates any applicable discounts
- Input schema:
```
{
  product_id: string; // Required: product identifier
}
```
Product Inventory (/tools/products)
- GET request
- Retrieves complete product catalog
- Includes product details, pricing, and availability
- Used for product recommendations
- No input parameters required
Product Inventory (/tools/send-to-flex)
- POST request
- Transfers conversation to a flex queue

Development

Adding New Tools

Create your function in the functions/tools directory
Deploy the updated functions:

twilio serverless:deploy

Add tool configuration to src/config/tools.js:

newTool: {
  name: "Tool Name",
  description: "Tool description and rules",
  type: "WEBHOOK",
  method: "GET",
  url: `https://${DOMAIN}/tools/your-new-tool`
}

Redeploy the assistant:

npm run deploy

Modifying Assistant Behavior

Update the prompt in prompts/assistant-prompt.md
Modify tool configurations as needed
Redeploy the assistant

Local Development

Create test credentials in Twilio
Use test credentials in .env
Deploy functions and assistant separately for easier debugging

Part 2: Deploying the Web App

Technical Stack

React 18 with TypeScript
Vite for build tooling
Tailwind CSS for styling
shadcn/ui for UI components
TanStack Query for data fetching
React Router for navigation

Web App Setup

Important: Complete the AI Assistant setup first, as the web application requires the same environment variables and services to be configured.

Navigate to the web directory:

cd web

Install dependencies:

npm install

Copy the environment variables from the root .env file:

cp ../.env .env

Start the development server:

npm run dev

The application will be available at http://localhost:8080.

Features

Product catalog browsing
Shopping cart functionality
Customer service chat integration
Order management
Customer account management

Development

To work on the web application:

Ensure all services (Twilio, Airtable) are properly configured
Run the development server with npm run dev
Make changes to components in web/src/components
Create new pages in web/src/pages

To build for production:

npm run build

Error Handling

The deployment script includes comprehensive error handling:

Environment variable validation
Creation failure handling
Detailed error logging

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Twilio AI Assistant Deployment Tool - Owl Shoes

Table of Contents

Features

Prerequisites

Project Structure

Part 1: Deploying the AI Assistant

Quick Start

Connecting Channels

Voice Channel

Messaging Channels

SMS

WhatsApp

Conversations Channel

Tool Functions

Development

Adding New Tools

Modifying Assistant Behavior

Local Development

Part 2: Deploying the Web App

Technical Stack

Web App Setup

Features

Development

Error Handling

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
assets		assets
evals		evals
examples/database_tables		examples/database_tables
functions		functions
prompts		prompts
src		src
web		web
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
.twilioserverlessrc		.twilioserverlessrc
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

License

nmogil-tw/ai-assistant-demo-owl-shoes-web-app

Folders and files

Latest commit

History

Repository files navigation

Twilio AI Assistant Deployment Tool - Owl Shoes

Table of Contents

Features

Prerequisites

Project Structure

Part 1: Deploying the AI Assistant

Quick Start

Connecting Channels

Voice Channel

Messaging Channels

SMS

WhatsApp

Conversations Channel

Tool Functions

Development

Adding New Tools

Modifying Assistant Behavior

Local Development

Part 2: Deploying the Web App

Technical Stack

Web App Setup

Features

Development

Error Handling

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages