Connettore Twilio Flex

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

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

# 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

curl -X GET "https://flex-api.twilio.com/v1/Configuration" \
  -u "$TWILIO_API_KEY_SID:$TWILIO_API_KEY_SECRET"

Connessione a Tajo

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

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:

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

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:

Esempi di codice

Inizializzare il connettore

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

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

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

// 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.tajo.io/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
        })
      });
    });
  }
}

Limiti di rate

Twilio applica limiti di rate sulle sue API:

Risoluzione dei problemi

Problemi comuni

Modalità debug

connectors:
  twilio_flex:
    debug: true
    log_level: verbose
    log_api_calls: true

Testare la connessione

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
• Connettore Jira
• Skill Customer Sync
• Brevo Contacts API