Note
Twilio AI Assistants is a Twilio Alpha project that is currently in Developer Preview.
A scalable, multi-channel lead generation system powered by Twilio AI Assistants. This reference implementation demonstrates how to build an AI-driven lead nurturing system that can capture leads through various channels and engage in personalized conversations.
[Architecture diagram showing system components and flow]
- 🤖 Dual AI Assistant System
- Rep Assistant: Handles initial customer interactions and generates responses
- Manager Assistant: Reviews and approves outbound communications
- 📱 Multi-Channel Support
- Web form lead capture
- Email communication (via SendGrid)
- SMS, Voice, and WhatsApp (via Twilio)
- Web chat integration
- 💾 Automated Data Management
- Lead information storage
- Conversation history tracking
- Email thread management
- 🔄 Intelligent Workflow
- Automated response generation
- Quality control through Manager AI review
- Channel-specific response handling
lead-gen-ai-assistant/
├── README.md
├── package.json
├── .env.example
├── .twilioserverlessrc
├── assets/
│ ├── index.html
│ ├── lead-form.html
│ ├── style.css
│ ├── providers/
│ │ ├── database/
│ │ └── email/
│ └── utils/
├── converter/
│ ├── package.json
│ └── server.js
├── functions/
│ ├── backend/
│ │ ├── form-submitted.js
│ │ ├── log-inbound-email.js
│ │ ├── send-email.js
│ │ └── send-to-assistant.js
│ ├── channels/
│ │ ├── conversations/
│ │ ├── messaging/
│ │ └── voice/
│ └── tools/
├── knowledge/
│ └── faq.txt
├── prompts/
│ ├── manager-assistant-prompt.md
│ └── rep-assistant-prompt.md
└── src/
├── deploy.js
└── config/
- Node.js 18+
- Twilio account with AI Assistant access
- SendGrid account
- Airtable account
- ngrok installed locally (for webhook testing)
# Clone repository
git clone https://github.com/your-org/lead-gen-ai-assistant.git
cd lead-gen-ai-assistant
# Install dependencies
npm install
# Copy environment file
cp .env.example .env- Copy the Airtable base using this template
- Find your Base ID in the Airtable URL (appXXXXXXXXXXXXX)
- Generate an access token:
- Go to your Airtable account settings
- Click "Create new token"
- Select necessary scopes for your base
- Copy the generated token
The base includes these tables:
- Leads: Track lead information (first_name, last_name, status, email, phone, area_code)
- Sessions: Manage conversation sessions and email grading
- Inbound Emails: Log incoming communications
- Listings: Store property listing data
- Set up your SendGrid account and verify your domain
- Navigate to Settings > Inbound Parse
- Start ngrok:
ngrok http 3000 - Add a new Inbound Parse webhook:
- URL: Your ngrok URL
- Select "Post the raw, full MIME message"
- Test the webhook using SendGrid's test feature
# Deploy the system
npm run deploy
# Start the content type converter before reciving any inbound emails
npm run start:converter-
Customer Lookup
- Purpose: Retrieves customer information at the start of conversations
- When to use: Mandatory at the beginning of each conversation
- Available data: First name, last name, address, email, phone
- Method: GET
- Usage: Enables personalized greetings and context-aware interactions
-
Get Listings
- Purpose: Searches property listings based on customer criteria
- Parameters:
- city (optional): Target city
- zip_code (optional): Specific ZIP code
- state (optional): State code
- price (optional): Maximum price point
- Method: GET
- Usage: Provides relevant property recommendations based on customer preferences
- Outbound Email Grader
- Purpose: Reviews and scores email communications
- Parameters:
- outbound_email_body: Original email content
- manager_score: Quality score (0 to 1, e.g., 0.85)
- outbound_email_status: "Sent" (score > 0.85) or "Draft"
- recommended_email_body: Suggested improvements for low-scoring emails
- Method: POST
- Usage: Quality control for all outbound email communications
Configure your Twilio voice number:
Via Twilio CLI:
twilio phone_number <your-twilio-number> \
--voice-url=https://<your-functions-domain>.twil.io/channels/voice/incoming-callVia 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
Via Twilio CLI:
twilio phone_number <your-twilio-number> \
--sms-url=https://<your-functions-domain>.twil.io/channels/messaging/incomingVia Console:
- Open your SMS-capable number
- Set "When a message comes in" to:
https://<your-functions-domain>.twil.io/channels/messaging/incoming
- Go to WhatsApp Sandbox Settings
- Set "When a message comes in" to:
https://<your-functions-domain>.twil.io/channels/messaging/incoming
Note: Add AssistantSid as parameter for multiple assistants:
https://<your-functions-domain>.twil.io/channels/messaging/incoming?AssistantSid=AI1234561231237812312
- Create/use a Conversations Service
- Configure 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- Start ngrok:
ngrok http 3000 - Update webhook URLs with ngrok URL
- Use test credentials in
.env
- Create function in
functions/ - Redeploy:
npm run redeploy
Common issues and solutions:
-
Webhook Issues
- Ensure ngrok is running and URL is updated in SendGrid
- Check Twilio Functions logs for webhook errors
- Verify all environment variables are set correctly
-
AI Assistant Configuration
- Confirm AI Assistant Terms acceptance
- Check tool configurations in Assistant settings
- Verify knowledge base attachments
-
Database Connectivity
- Validate Airtable API key permissions
- Ensure Base ID is correct
- Check table names and field mappings
- Twilio AI Assistants Documentation
- SendGrid API Documentation
- Airtable API Documentation
- Channel Configuration Guides
This project is licensed under the MIT License - see the LICENSE file for details.# mcp-performance-v2