--- title: "Connettore Twilio Flex" description: "Guida completa all'integrazione di Twilio Flex per sincronizzare interazioni del contact center, attività degli agenti e conversazioni con i clienti con Brevo tramite Tajo." url: https://tajo.io/it/docs/connectors/custom/twilio-flex/ markdown: https://tajo.io/it/docs/connectors/custom/twilio-flex.md lang: it-IT robots: noindex --- Richiedi l’accesso anticipato Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo. # Connettore Twilio Flex Stato del connettore: Pianificato Non ancora realizzato. Oggi Tajo non esegue questo connettore. | Campo di origine | Campo di destinazione | Valore di esempio | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Collega il tuo contact center Twilio Flex a Brevo per avere uno storico unificato delle interazioni con i clienti, flussi marketing post-conversazione e analytics di engagement guidati dal supporto, tramite Tajo. ## Panoramica | Proprietà | Valore | | --- | --- | | **Piattaforma** | Twilio Flex | | **Categoria** | Custom | | **Complessità di setup** | Avanzata | | **Integrazione ufficiale** | No | | **Dati sincronizzati** | Clienti, Conversazioni, Eventi | | **API utilizzate** | Flex API, Conversations API, TaskRouter API | | **Autenticazione** | Account SID + Auth Token / API Key | | **Base URL** | `https://flex-api.twilio.com` | ## Funzionalità - **Sync delle conversazioni** - Inoltra interazioni vocali, SMS, WhatsApp e chat sulle timeline Brevo - **Arricchimento profilo cliente** - Sincronizza i dati cliente di Flex sugli attributi dei contatti Brevo - **Campagne post-interazione** - Attiva workflow Brevo dopo la fine delle conversazioni di supporto - **Tracciamento eventi CSAT** - Sincronizza i risultati dei sondaggi di soddisfazione come eventi Brevo - **Dati di attività degli agenti** - Traccia le metriche di performance degli agenti per reporting operativo - **Analytics delle code** - Inoltra dati su tempo di attesa e abbandono per ottimizzare l’esperienza ## Prerequisiti Prima di iniziare, assicurati di avere: 1. Un account Twilio con Flex abilitato 2. Il tuo Twilio Account SID e Auth Token 3. Un’istanza Flex con canali attivi (voce, SMS, chat o WhatsApp) 4. Un workspace TaskRouter configurato 5. Un account Brevo con accesso API 6. Un account Tajo con abbonamento attivo ## Autenticazione Twilio Flex usa i metodi di autenticazione standard di Twilio. ### Credenziali dell’account ```bash # Basic Auth: Account SID come username, Auth Token come password curl -X GET "https://flex-api.twilio.com/v1/Configuration" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" ``` ### API Key (consigliata in produzione) 1. Vai su **Twilio Console** > **Account** > **API keys & tokens** 2. Clicca su **Create API Key** 3. Seleziona il tipo di chiave **Standard** 4. Archivia SID e Secret in modo sicuro ```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 Il tuo Auth Token ha accesso completo all’account. In produzione, usa API Key con scope. Le API Key possono essere revocate singolarmente senza interrompere altre integrazioni. ### Connessione a Tajo ```bash tajo connectors install twilio-flex \ --account-sid $TWILIO_ACCOUNT_SID \ --auth-token $TWILIO_AUTH_TOKEN \ --flex-flow-sid $TWILIO_FLEX_FLOW_SID ``` ## Configurazione ### Setup di base ```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 ``` ### Mapping dei campi Mappa i dati cliente e di interazione di Flex sugli attributi Brevo: ```yaml field_mapping: # Campi cliente identity: FLEX_IDENTITY friendly_name: FIRSTNAME attributes.email: email attributes.phone: SMS # Metriche di interazione 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 # Attributi personalizzati customer_tier: VIP_TIER account_id: ACCOUNT_ID ``` ### Mapping degli eventi ```yaml event_mapping: task.created: SUPPORT_REQUESTED task.completed: SUPPORT_RESOLVED task.canceled: SUPPORT_ABANDONED conversation.ended: CONVERSATION_ENDED survey.completed: CSAT_SUBMITTED ``` ## Endpoint API Tajo si integra con i seguenti endpoint API di Twilio Flex e relativi: | Endpoint | Metodo | API | Scopo | | --- | --- | --- | --- | | `/v1/Configuration` | GET | Flex | Ottieni la configurazione Flex | | `/v1/Interactions` | GET | Flex | Elenca le interazioni | | `/v1/Channels` | GET | Flex | Elenca i canali Flex | | `/v1/WebChannels` | POST | Flex | Crea un canale web chat | | `/v1/Conversations` | GET | Conversations | Elenca le conversazioni | | `/v1/Conversations/{sid}/Messages` | GET | Conversations | Elenca i messaggi della conversazione | | `/v1/Conversations/{sid}/Participants` | GET | Conversations | Elenca i partecipanti | | `/v1/Workspaces/{sid}/Tasks` | GET | TaskRouter | Elenca i task | | `/v1/Workspaces/{sid}/Workers` | GET | TaskRouter | Elenca i worker (agenti) | | `/v1/Workspaces/{sid}/TaskQueues` | GET | TaskRouter | Elenca le code di task | | `/v1/Workspaces/{sid}/Events` | GET | TaskRouter | Elenca gli eventi del workspace | ## Esempi di codice ### Inizializzare il connettore ```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 }); ``` ### Sincronizzare lo storico conversazioni ```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 // } ``` ### Trigger campagna post-conversazione ```javascript // Attiva un follow-up Brevo dopo la fine di una conversazione di supporto 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'); }); ``` ### Integrazione con Flex Plugin ```javascript // All'interno di un Flex UI Plugin - invia dati a 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 L’indirizzo `example.com` qui sopra è un segnaposto finché l’endpoint Tajo non sarà disponibile. ## Limiti di rate Twilio applica limiti di rate sulle sue API: | API | Rate limit | Note | | --- | --- | --- | | **Flex API** | 100 richieste/secondo | Per account | | **Conversations API** | 100 richieste/secondo | Per account | | **TaskRouter API** | 30 richieste di lettura/secondo | Per workspace | | **TaskRouter Events** | 20 richieste/secondo | Per workspace | Event Streams Per l’elaborazione di eventi ad alto volume, considera l’uso di Twilio Event Streams invece del polling di TaskRouter. Gli Event Streams inviano eventi in real-time tramite webhook o Kinesis. ## Risoluzione dei problemi ### Problemi comuni | Problema | Causa | Soluzione | | --- | --- | --- | | 401 Unauthorized | SID o token non valido | Verifica Account SID e Auth Token nella Twilio Console | | 403 Forbidden | Flex non abilitato | Assicurati che Flex sia attivato sul tuo account Twilio | | Conversazioni mancanti | Intervallo di date errato | Espandi l’intervallo di sync o controlla lo stato della conversazione | | Task non tracciati | Workspace TaskRouter sbagliato | Verifica il SID corretto del workspace | | Plugin non scatta | Event listener non registrato | Controlla che il plugin Flex sia deployato e attivo | ### Modalità debug ```yaml connectors: twilio_flex: debug: true log_level: verbose log_api_calls: true ``` ### Testare la connessione ```bash tajo connectors test twilio-flex # ✓ Connessione Flex API riuscita # ✓ Conversations API accessibile # ✓ Workspace TaskRouter trovato # ✓ Lista agenti leggibile # ✓ Configurazione coda caricata ``` ## Best practice 1. **Usa API Key invece di Auth Token** - Le API Key possono avere scope e possono essere revocate singolarmente 2. **Sfrutta gli Event Streams** - Gli eventi push-based sono più efficienti del polling TaskRouter 3. **Costruisci un Flex Plugin** - Usa un UI plugin per catturare eventi di completamento task in real-time 4. **Mappa i canali in modo coerente** - Normalizza i dati voce, SMS e chat in eventi Brevo unificati 5. **Traccia gli score CSAT** - Sincronizza i dati di soddisfazione su Brevo per la segmentazione basata sull’esperienza 6. **Monitora le metriche di coda** - Usa i dati sui tempi di attesa per attivare comunicazioni proattive ## Sicurezza - **Account SID + Auth Token** - Autenticazione Twilio standard - **API Key** - Credenziali revocabili e non-root per uso in produzione - **Solo HTTPS** - Tutte le comunicazioni API cifrate tramite TLS 1.2+ - **Validazione webhook** - Verifica le firme webhook Twilio con `X-Twilio-Signature` - **Conformità PCI** - Twilio Flex è certificato PCI DSS Level 1 - **Archiviazione cifrata** - Credenziali cifrate a riposo in Tajo ## Risorse correlate - [Connettore Gorgias](https://tajo.io/it/docs/connectors/support/gorgias) - [Connettore Jira](https://tajo.io/it/docs/connectors/custom/jira) - [Skill Customer Sync](https://tajo.io/it/docs/skills/data-sync/customer-sync) - [Brevo Contacts API](https://tajo.io/it/docs/contact-management)