From 272e295c0fcce73cd33e65942b88dfdb48bfa658 Mon Sep 17 00:00:00 2001
From: GarethF531 <167188366+GarethF531@users.noreply.github.com>
Date: Thu, 21 Aug 2025 16:49:49 +0200
Subject: [PATCH 01/48] initial working branch
---
STUDIO_FLOW_SETUP.md | 103 ++++++++++
TASKROUTER_SETUP.md | 99 +++++++++
public/index.html | 19 +-
server/controllers/initWebchatController.js | 117 +++++++----
server/helpers/createToken.js | 8 +-
server/helpers/getTwilioClient.js | 9 +-
server/index.js | 2 +-
src/components/ConversationEnded.tsx | 59 ------
src/components/Header.tsx | 2 +-
src/components/MessagingCanvasPhase.tsx | 3 +-
src/components/PreEngagementFormPhase.tsx | 10 +-
src/components/Transcript.tsx | 3 +-
src/components/WebchatWidget.tsx | 18 +-
.../__tests__/ConversationEnded.test.tsx | 193 ------------------
.../__tests__/MessagingCanvasPhase.test.tsx | 12 +-
.../__tests__/WebchatWidget.test.tsx | 26 +--
.../styles/ConversationEnded.styles.ts | 21 --
src/components/styles/EntryPoint.styles.ts | 10 +-
src/index.tsx | 2 +-
19 files changed, 330 insertions(+), 386 deletions(-)
create mode 100644 STUDIO_FLOW_SETUP.md
create mode 100644 TASKROUTER_SETUP.md
delete mode 100644 src/components/ConversationEnded.tsx
delete mode 100644 src/components/__tests__/ConversationEnded.test.tsx
delete mode 100644 src/components/styles/ConversationEnded.styles.ts
diff --git a/STUDIO_FLOW_SETUP.md b/STUDIO_FLOW_SETUP.md
new file mode 100644
index 00000000..40d63078
--- /dev/null
+++ b/STUDIO_FLOW_SETUP.md
@@ -0,0 +1,103 @@
+# Studio Flow Integration Setup
+
+This webchat widget now triggers a Twilio Studio Flow instead of creating TaskRouter tasks directly.
+
+## Required Environment Variables
+
+Add these variables to your `.env` file:
+
+```env
+# Studio Flow Configuration
+STUDIO_FLOW_SID=FWxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Conversations Service (already configured)
+CONVERSATIONS_SERVICE_SID=ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Optional: Keep TaskRouter config for fallback or Studio Flow integration
+TASKROUTER_WORKSPACE_SID=WSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+TASKROUTER_WORKFLOW_SID=WWxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## Setup Steps
+
+### 1. Create a Studio Flow
+1. Go to Twilio Console → Studio → Flows
+2. Create a new flow or use an existing one
+3. Copy the Flow SID (starts with `FW`)
+
+### 2. Configure Flow Parameters
+Your Studio Flow will receive these parameters:
+- `conversationSid`: The Twilio Conversations SID
+- `customerName`: Customer's friendly name
+- `customerEmail`: Customer's email address
+- `customerQuery`: Customer's initial query
+- `channelType`: Set to 'webchat'
+- `direction`: Set to 'inbound'
+- Any additional form data from the pre-engagement form
+
+### 3. Flow Design Options
+
+#### Option A: Direct to Flex
+- Use a "Connect to Flex" widget in your Studio Flow
+- Pass the conversation SID and other parameters to Flex
+- Flex will create the TaskRouter task automatically
+
+#### Option B: Custom Logic Before Flex
+- Add widgets for form validation, routing logic, or business rules
+- Use "Connect to Flex" as the final step
+- You can add delays, conditional routing, or automated responses
+
+#### Option C: No Flex Integration
+- Handle the entire conversation in Studio Flow
+- Use "Send to Flex" widget only when human agent is needed
+
+### 4. Example Flow Structure
+```
+Trigger → Set Variables → [Optional Logic] → Connect to Flex → End
+```
+
+### 5. Flow Trigger Configuration
+- **Trigger Type**: Webhook or REST API
+- **To**: Will be set to the conversation SID automatically
+- **From**: Will be set to your Conversations Service SID automatically
+- **Parameters**: All form data and conversation details
+
+## Benefits
+
+✅ **Flexible Pre-Processing**
+- Form validation and enrichment
+- Business logic and routing rules
+- Automated responses before agent assignment
+
+✅ **Better Control**
+- Conditional routing based on form data
+- Integration with external systems
+- Custom business workflows
+
+✅ **Enhanced Analytics**
+- Flow execution tracking
+- Step-by-step analytics
+- Custom metrics and reporting
+
+## Testing
+
+1. Start the server: `npm run server`
+2. Open the webchat widget
+3. Fill out the form and submit
+4. Check Studio Flow console for the new execution
+5. Verify the flow parameters are passed correctly
+
+## Troubleshooting
+
+- **Flow not triggering**: Check `STUDIO_FLOW_SID` is correct
+- **Conversation SID missing**: Verify `CONVERSATIONS_SERVICE_SID` is set
+- **Parameters missing**: Verify form data is being passed correctly
+- **Flow execution fails**: Check Studio Flow logs for detailed error messages
+
+## Alternative: Webhook-Based Approach
+
+If you prefer to use webhooks instead of direct API calls, you can:
+
+1. Set up a webhook endpoint in your Studio Flow
+2. Modify the controller to send a webhook request instead of using the Studio API
+3. This approach can be more flexible for complex integrations
diff --git a/TASKROUTER_SETUP.md b/TASKROUTER_SETUP.md
new file mode 100644
index 00000000..b9342692
--- /dev/null
+++ b/TASKROUTER_SETUP.md
@@ -0,0 +1,99 @@
+# TaskRouter Integration Setup
+
+This webchat widget now creates TaskRouter tasks for full Flex Insights coverage and control.
+
+## Required Environment Variables
+
+Create a `.env` file in the `server` directory with these variables:
+
+```env
+# Twilio Account Credentials
+ACCOUNT_SID=your_twilio_account_sid
+AUTH_TOKEN=your_twilio_auth_token
+
+# Twilio API Keys (for token generation)
+API_KEY=your_twilio_api_key
+API_SECRET=your_twilio_api_secret
+
+# Twilio Conversations Service
+CONVERSATIONS_SERVICE_SID=your_conversations_service_sid
+
+# TaskRouter Configuration
+TASKROUTER_WORKSPACE_SID=your_taskrouter_workspace_sid
+TASKROUTER_WORKFLOW_SID=your_taskrouter_workflow_sid
+
+# Optional: SendGrid for email transcripts
+SENDGRID_API_KEY=your_sendgrid_api_key
+FROM_EMAIL=your_verified_email@domain.com
+```
+
+## Setup Steps
+
+### 1. Get Twilio Credentials
+- **ACCOUNT_SID** and **AUTH_TOKEN**: From Twilio Console → Account → API Keys & Tokens
+- **API_KEY** and **API_SECRET**: Create new API key in Twilio Console → Account → API Keys & Tokens
+
+### 2. Get Conversations Service SID
+- Go to Twilio Console → Conversations → Services
+- Create a new service or use existing one
+- Copy the Service SID
+
+### 3. Get TaskRouter Workspace SID
+- Go to Twilio Console → TaskRouter → Workspaces
+- Use your Flex workspace or create a new one
+- Copy the Workspace SID
+
+### 4. Create TaskRouter Workflow
+- Go to Twilio Console → TaskRouter → Workspaces → [Your Workspace] → Workflows
+- Create a new workflow for webchat tasks
+- Copy the Workflow SID
+
+### 5. Configure Workflow
+Your workflow should route tasks to agents. Example workflow configuration:
+
+```json
+{
+ "task_routing": {
+ "default_filter": {
+ "queue": "your_agent_queue_sid"
+ }
+ }
+}
+```
+
+### 6. Set Up Webhooks (Optional)
+To automatically complete tasks when conversations end:
+
+1. Go to Twilio Console → Conversations → Services → [Your Service] → Webhooks
+2. Add webhook URL: `https://your-server.com/webhook/conversation`
+3. Select events: `conversation.ended`
+
+## Benefits
+
+✅ **Full Flex Insights Coverage**
+- Task lifecycle tracking
+- Queue performance metrics
+- Agent productivity data
+- Custom attributes and routing data
+
+✅ **Advanced Control**
+- Custom routing logic
+- Skill-based assignment
+- Queue management
+- SLA tracking
+
+✅ **Complete Analytics**
+- Task routing decisions
+- Wait times
+- Agent assignment times
+- Custom business metrics
+
+## Testing
+
+1. Start the server: `cd server && npm start`
+2. Open the webchat widget
+3. Fill out the form and submit
+4. Check TaskRouter console for the new task
+5. Assign the task to an agent in Flex
+
+The task will include all customer information and can be routed based on your workflow configuration.
diff --git a/public/index.html b/public/index.html
index 5ddb00b0..e668d804 100644
--- a/public/index.html
+++ b/public/index.html
@@ -10,6 +10,7 @@
homescreen on Android. See https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/
-->
+