Twilio Flex Connector

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

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

# 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

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

Connecting to Tajo

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

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:

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

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:

Code Examples

Initialize Connector

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

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

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

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

Rate Limits

Twilio enforces rate limits across its APIs:

Troubleshooting

Common Issues

Debug Mode

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

Test Connection

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

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

Integration Shape

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
• twilio-labs/mcp
• Vendor documentation