--- title: "Twilio Flex Connector" description: "Complete Twilio Flex integration guide for syncing contact center interactions, agent activity, and customer conversations with Brevo via Tajo." url: https://tajo.io/docs/connectors/custom/twilio-flex/ markdown: https://tajo.io/docs/connectors/custom/twilio-flex.md lang: en-US robots: noindex --- # Twilio Flex Connector Connector status: Planned Not built yet. Tajo does not run this connector today. | Source field | Destination field | Sample value | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Connect your Twilio Flex contact center to Brevo for unified customer interaction history, post-conversation marketing flows, and support-driven engagement analytics through Tajo. ## Overview | Property | Value | | --- | --- | | **Platform** | Twilio Flex | | **Category** | Custom | | **Setup Complexity** | Advanced | | **Official Integration** | No | | **Data Synced** | Customers, Conversations, Events | | **APIs Used** | Flex API, Conversations API, TaskRouter API | | **Authentication** | Account SID + Auth Token / API Key | | **Base URL** | `https://flex-api.twilio.com` | ## Features - **Conversation sync** - Forward voice, SMS, WhatsApp, and chat interactions to Brevo timelines - **Customer profile enrichment** - Sync Flex customer data to Brevo contact attributes - **Post-interaction campaigns** - Trigger Brevo workflows after support conversations end - **CSAT event tracking** - Sync satisfaction survey results as Brevo events - **Agent activity data** - Track agent performance metrics for operational reporting - **Queue analytics** - Forward wait time and abandonment data for experience optimization ## Prerequisites Before you begin, ensure you have: 1. A Twilio account with Flex enabled 2. Your Twilio Account SID and Auth Token 3. A Flex instance with active channels (voice, SMS, chat, or WhatsApp) 4. TaskRouter workspace configured 5. A Brevo account with API access 6. A Tajo account with an active subscription ## Authentication Twilio Flex uses Twilio’s standard authentication methods. ### Account Credentials ```bash # Basic Auth: Account SID as username, Auth Token as password curl -X GET "https://flex-api.twilio.com/v1/Configuration" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" ``` ### API Key (Recommended for Production) 1. Go to **Twilio Console** > **Account** > **API keys & tokens** 2. Click **Create API Key** 3. Select **Standard** key type 4. Store the SID and Secret securely ```bash curl -X GET "https://flex-api.twilio.com/v1/Configuration" \ -u "$TWILIO_API_KEY_SID:$TWILIO_API_KEY_SECRET" ``` Auth Token vs API Key Your Auth Token has full account access. For production, use scoped API Keys instead. API Keys can be revoked individually without disrupting other integrations. ### Connecting to Tajo ```bash tajo connectors install twilio-flex \ --account-sid $TWILIO_ACCOUNT_SID \ --auth-token $TWILIO_AUTH_TOKEN \ --flex-flow-sid $TWILIO_FLEX_FLOW_SID ``` ## Configuration ### Basic Setup ```yaml connectors: twilio_flex: enabled: true account_sid: "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" flex_flow_sid: "FOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" sync: conversations: true tasks: true customers: true csat: true agent_activity: false lists: support_contacts: 32 csat_respondents: 33 channels: - voice - sms - whatsapp - webchat ``` ### Field Mapping Map Flex customer and interaction data to Brevo attributes: ```yaml field_mapping: # Customer fields identity: FLEX_IDENTITY friendly_name: FIRSTNAME attributes.email: email attributes.phone: SMS # Interaction metrics last_conversation_date: LAST_SUPPORT_DATE total_conversations: SUPPORT_TICKET_COUNT avg_wait_time: AVG_WAIT_TIME last_csat_score: CSAT_SCORE preferred_channel: PREFERRED_CHANNEL # Custom attributes customer_tier: VIP_TIER account_id: ACCOUNT_ID ``` ### Event Mapping ```yaml event_mapping: task.created: SUPPORT_REQUESTED task.completed: SUPPORT_RESOLVED task.canceled: SUPPORT_ABANDONED conversation.ended: CONVERSATION_ENDED survey.completed: CSAT_SUBMITTED ``` ## API Endpoints Tajo integrates with the following Twilio Flex and related API endpoints: | Endpoint | Method | API | Purpose | | --- | --- | --- | --- | | `/v1/Configuration` | GET | Flex | Get Flex configuration | | `/v1/Interactions` | GET | Flex | List interactions | | `/v1/Channels` | GET | Flex | List Flex channels | | `/v1/WebChannels` | POST | Flex | Create web chat channel | | `/v1/Conversations` | GET | Conversations | List conversations | | `/v1/Conversations/{sid}/Messages` | GET | Conversations | List conversation messages | | `/v1/Conversations/{sid}/Participants` | GET | Conversations | List participants | | `/v1/Workspaces/{sid}/Tasks` | GET | TaskRouter | List tasks | | `/v1/Workspaces/{sid}/Workers` | GET | TaskRouter | List workers (agents) | | `/v1/Workspaces/{sid}/TaskQueues` | GET | TaskRouter | List task queues | | `/v1/Workspaces/{sid}/Events` | GET | TaskRouter | List workspace events | ## Code Examples ### Initialize Connector ```javascript import { TajoClient } from '@tajo/sdk'; const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY }); await tajo.connectors.connect('twilio-flex', { accountSid: process.env.TWILIO_ACCOUNT_SID, authToken: process.env.TWILIO_AUTH_TOKEN, flexFlowSid: process.env.TWILIO_FLEX_FLOW_SID }); ``` ### Sync Conversation History ```javascript await tajo.connectors.sync('twilio-flex', { type: 'incremental', resources: ['conversations'], since: '2024-01-01', channels: ['voice', 'sms', 'whatsapp'] }); const status = await tajo.connectors.status('twilio-flex'); console.log(status); // { // connected: true, // lastSync: '2024-03-15T16:00:00Z', // conversationsTracked: 12400, // customersLinked: 8900, // agentsMonitored: 45 // } ``` ### Post-Conversation Campaign Trigger ```javascript // Trigger a Brevo follow-up after a support conversation ends app.post('/webhooks/flex/task-complete', async (req, res) => { const task = req.body; await tajo.connectors.handleEvent('twilio-flex', { type: 'task.completed', payload: { taskSid: task.TaskSid, customerEmail: task.TaskAttributes?.email, channel: task.TaskChannelUniqueName, duration: task.Age, queueName: task.TaskQueueFriendlyName } }); res.status(200).send('OK'); }); ``` ### Flex Plugin Integration ```javascript // Inside a Flex UI Plugin - send data to Tajo import { FlexPlugin } from '@twilio/flex-plugin'; class TajoPlugin extends FlexPlugin { init(flex, manager) { flex.Actions.addListener('afterCompleteTask', async (payload) => { await fetch('https://api.example.com/webhooks/flex/task-complete', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ TaskSid: payload.task.sid, TaskAttributes: payload.task.attributes, TaskChannelUniqueName: payload.task.taskChannelUniqueName, Age: payload.task.age }) }); }); } } ``` Caution The `example.com` address above is a placeholder until the Tajo endpoint is available. ## Rate Limits Twilio enforces rate limits across its APIs: | API | Rate Limit | Notes | | --- | --- | --- | | **Flex API** | 100 requests/second | Per account | | **Conversations API** | 100 requests/second | Per account | | **TaskRouter API** | 30 read requests/second | Per workspace | | **TaskRouter Events** | 20 requests/second | Per workspace | Event Streams For high-volume event processing, consider using Twilio Event Streams instead of polling TaskRouter events. Event Streams push events in real time via webhooks or Kinesis. ## Troubleshooting ### Common Issues | Issue | Cause | Solution | | --- | --- | --- | | 401 Unauthorized | Invalid SID or token | Verify Account SID and Auth Token in Twilio Console | | 403 Forbidden | Flex not enabled | Ensure Flex is activated on your Twilio account | | Conversations missing | Wrong date range | Expand sync date range or check conversation state | | Tasks not tracked | TaskRouter workspace mismatch | Verify the correct workspace SID | | Plugin not firing | Event listener not registered | Check Flex plugin is deployed and active | ### Debug Mode ```yaml connectors: twilio_flex: debug: true log_level: verbose log_api_calls: true ``` ### Test Connection ```bash tajo connectors test twilio-flex # ✓ Flex API connection successful # ✓ Conversations API accessible # ✓ TaskRouter workspace found # ✓ Agent list readable # ✓ Queue configuration loaded ``` ## Best Practices 1. **Use API Keys over Auth Tokens** - API Keys can be scoped and individually revoked 2. **Leverage Event Streams** - Push-based events are more efficient than polling TaskRouter 3. **Build a Flex Plugin** - Use a UI plugin to capture task completion events in real time 4. **Map channels consistently** - Normalize voice, SMS, and chat data into unified Brevo events 5. **Track CSAT scores** - Sync satisfaction data to Brevo for experience-driven segmentation 6. **Monitor queue metrics** - Use wait time data to trigger proactive customer communication ## Security - **Account SID + Auth Token** - Standard Twilio authentication - **API Keys** - Revocable, non-root credentials for production use - **HTTPS Only** - All API communication encrypted via TLS 1.2+ - **Webhook Validation** - Verify Twilio webhook signatures with `X-Twilio-Signature` - **PCI Compliance** - Twilio Flex is PCI DSS Level 1 compliant - **Encrypted Storage** - Credentials encrypted at rest in Tajo ## Related Resources - [Gorgias Connector](https://tajo.io/docs/connectors/support/gorgias) - [Jira Connector](https://tajo.io/docs/connectors/custom/jira) - [Customer Sync Skill](https://tajo.io/docs/skills/data-sync/customer-sync) - [Brevo Contacts API](https://tajo.io/docs/contact-management) ## Open-Source Implementation Map This section is derived from official or public repository material discovered for the Twilio Flex connector. Use it as the engineering companion to the setup guide above: it shows where the API surface lives, what implementation assets exist, and how Tajo should translate them into reliable Brevo sync behavior. ### Repository Snapshot | Repository | Commit | Languages / formats | Files | | --- | --- | --- | --- | | [twilio/twilio-oai](https://github.com/twilio/twilio-oai) | 69b05ab | JSON (69), YAML (62), Markdown (6), YAML (4), gitignore (1), dockerfile (1) | 145 | | [twilio-labs/mcp](https://github.com/twilio-labs/mcp) | 64c0f05 | TypeScript (36), JSON (11), Markdown (6), png (6), YAML (2), gitignore (1) | 64 | ### Integration Shape ```mermaid graph LR Source["Twilio Flex API / repository"] --> Auth["Auth and scopes"] Source --> Objects["Objects, events, and schemas"] Auth --> Tajo["Tajo connector runtime"] Objects --> Tajo Tajo --> Brevo["Brevo contacts, attributes, lists, campaigns"] Tajo --> Ops["Backfill, cursor, retries, logs"] ``` ### What To Reuse - Twilio’s OpenAPI Specification - This repository contains OpenAPI documents for Twilio’s API. - Files can be found in the json/ and yaml/ directories. - What is OpenAPI? - From the OpenAPI Specification: ### Tajo Revamp Checklist - Keep authentication setup aligned with the vendor docs and the public repository’s current API shape. - Map primary resources into explicit Tajo sync objects with stable external IDs. - Prefer cursor-based or updated-at incremental sync where the API exposes it; otherwise document the fallback. - Treat webhook handlers as idempotent and replay-safe, especially for order, contact, ticket, and campaign events. - Capture pagination, rate limits, retry headers, and partial-failure behavior in connector smoke tests. - Keep examples small and runnable against sandbox or test-mode accounts. ### Sources - [twilio/twilio-oai](https://github.com/twilio/twilio-oai) - [twilio-labs/mcp](https://github.com/twilio-labs/mcp) - [Vendor documentation](https://www.twilio.com/docs/flex)