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/ --> +