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

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/
├── 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

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:

npm run deploy

Connecting Channels

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

Conversations
SMS & Whatsapp
Conversations with React
Transition to Flex
Flex Voice Handoff
Transition to Sudio
Other Examples

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

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

README.md

README.md

Twilio AI Assistant Deployment Tool - Owl Shoes

Features

Prerequisites

Project Structure

Quick Start

Connecting Channels

Voice Channel

Messaging Channels

SMS

WhatsApp

Conversations Channel

Tool Functions

Development

Adding New Tools

Modifying Assistant Behavior

Local Development

Error Handling

Contributing

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

Twilio AI Assistant Deployment Tool - Owl Shoes

Features

Prerequisites

Project Structure

Quick Start

Connecting Channels

Voice Channel

Messaging Channels

SMS

WhatsApp

Conversations Channel

Tool Functions

Development

Adding New Tools

Modifying Assistant Behavior

Local Development

Error Handling

Contributing

License