---
title: "Conector Twilio Flex"
description: "Guia completo de integração do Twilio Flex para sincronizar interações de contact center, atividade de agentes e conversas com clientes com o Brevo via Tajo."
url: https://tajo.io/pt/docs/connectors/custom/twilio-flex/
markdown: https://tajo.io/pt/docs/connectors/custom/twilio-flex.md
lang: pt-BR
robots: noindex
---

Solicite acesso antecipado

Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo.

# Conector Twilio Flex

Status do conector: Planejado Ainda não construído. O Tajo não executa este conector hoje.

| Campo de origem | Campo de destino | Valor de exemplo |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Conecte seu contact center Twilio Flex ao Brevo para obter histórico unificado de interação com o cliente, fluxos de marketing pós-conversa e analytics de engajamento orientado por suporte através do Tajo.

## Visão geral

| Propriedade | Valor |
| --- | --- |
| **Plataforma** | Twilio Flex |
| **Categoria** | Personalizado |
| **Complexidade de configuração** | Avançada |
| **Integração oficial** | Não |
| **Dados sincronizados** | Clientes, Conversas, Eventos |
| **APIs utilizadas** | Flex API, Conversations API, TaskRouter API |
| **Autenticação** | Account SID + Auth Token / API Key |
| **URL base** | `https://flex-api.twilio.com` |

## Recursos

- **Sincronização de conversas** - Encaminhe interações de voz, SMS, WhatsApp e chat para timelines do Brevo
- **Enriquecimento de perfil do cliente** - Sincronize dados de cliente do Flex para atributos de contato do Brevo
- **Campanhas pós-interação** - Dispare workflows do Brevo após o término de conversas de suporte
- **Rastreamento de eventos CSAT** - Sincronize resultados de pesquisas de satisfação como eventos do Brevo
- **Dados de atividade de agentes** - Rastreie métricas de desempenho de agentes para relatórios operacionais
- **Analytics de filas** - Encaminhe dados de tempo de espera e abandono para otimização de experiência

## Pré-requisitos

Antes de começar, certifique-se de ter:

1. Uma conta Twilio com o Flex habilitado
2. Seu Twilio Account SID e Auth Token
3. Uma instância Flex com canais ativos (voz, SMS, chat ou WhatsApp)
4. TaskRouter workspace configurado
5. Uma conta Brevo com acesso à API
6. Uma conta Tajo com assinatura ativa

## Autenticação

O Twilio Flex usa os métodos padrão de autenticação do Twilio.

### Credenciais da conta

```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 (Recomendado para produção)

1. Vá para **Twilio Console** > **Account** > **API keys & tokens**
2. Clique em **Create API Key**
3. Selecione o tipo de chave **Standard**
4. Armazene o SID e o Secret com segurança

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

Seu Auth Token tem acesso completo à conta. Para produção, use API Keys com escopo. As API Keys podem ser revogadas individualmente sem interromper outras integrações.

### Conectando ao Tajo

```bash
tajo connectors install twilio-flex \
  --account-sid $TWILIO_ACCOUNT_SID \
  --auth-token $TWILIO_AUTH_TOKEN \
  --flex-flow-sid $TWILIO_FLEX_FLOW_SID
```

## Configuração

### Configuração básica

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

### Mapeamento de campos

Mapeie dados de cliente e interação do Flex para atributos do Brevo:

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

### Mapeamento de eventos

```yaml
event_mapping:
  task.created: SUPPORT_REQUESTED
  task.completed: SUPPORT_RESOLVED
  task.canceled: SUPPORT_ABANDONED
  conversation.ended: CONVERSATION_ENDED
  survey.completed: CSAT_SUBMITTED
```

## Endpoints da API

O Tajo integra-se com os seguintes endpoints da API Twilio Flex e APIs relacionadas:

| Endpoint | Método | API | Finalidade |
| --- | --- | --- | --- |
| `/v1/Configuration` | GET | Flex | Obter configuração do Flex |
| `/v1/Interactions` | GET | Flex | Listar interações |
| `/v1/Channels` | GET | Flex | Listar canais Flex |
| `/v1/WebChannels` | POST | Flex | Criar canal de web chat |
| `/v1/Conversations` | GET | Conversations | Listar conversas |
| `/v1/Conversations/{sid}/Messages` | GET | Conversations | Listar mensagens da conversa |
| `/v1/Conversations/{sid}/Participants` | GET | Conversations | Listar participantes |
| `/v1/Workspaces/{sid}/Tasks` | GET | TaskRouter | Listar tarefas |
| `/v1/Workspaces/{sid}/Workers` | GET | TaskRouter | Listar workers (agentes) |
| `/v1/Workspaces/{sid}/TaskQueues` | GET | TaskRouter | Listar filas de tarefas |
| `/v1/Workspaces/{sid}/Events` | GET | TaskRouter | Listar eventos do workspace |

## Exemplos de código

### Inicializar o conector

```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
});
```

### Sincronizar histórico de conversas

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

### Gatilho de campanha pós-conversa

```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');
});
```

### Integração com Flex Plugin

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

O endereço `example.com` acima é um exemplo provisório até que o endpoint da Tajo esteja disponível.

## Limites de taxa

O Twilio aplica limites de taxa em todas as suas APIs:

| API | Limite de taxa | Observações |
| --- | --- | --- |
| **Flex API** | 100 requisições/segundo | Por conta |
| **Conversations API** | 100 requisições/segundo | Por conta |
| **TaskRouter API** | 30 requisições de leitura/segundo | Por workspace |
| **TaskRouter Events** | 20 requisições/segundo | Por workspace |

Event Streams

Para processamento de eventos em alto volume, considere usar o Twilio Event Streams em vez de fazer polling nos eventos do TaskRouter. O Event Streams envia eventos em tempo real via webhooks ou Kinesis.

## Solução de problemas

### Problemas comuns

| Problema | Causa | Solução |
| --- | --- | --- |
| 401 Unauthorized | SID ou token inválido | Verifique o Account SID e Auth Token no Twilio Console |
| 403 Forbidden | Flex não habilitado | Certifique-se de que o Flex está ativado na sua conta Twilio |
| Conversas ausentes | Intervalo de data errado | Expanda o intervalo de data da sincronização ou verifique o estado da conversa |
| Tarefas não rastreadas | Workspace TaskRouter incorreto | Verifique o SID correto do workspace |
| Plugin não disparando | Listener de evento não registrado | Verifique se o Flex plugin está implantado e ativo |

### Modo de depuração

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

### Testar conexão

```bash
tajo connectors test twilio-flex
# ✓ Flex API connection successful
# ✓ Conversations API accessible
# ✓ TaskRouter workspace found
# ✓ Agent list readable
# ✓ Queue configuration loaded
```

## Melhores práticas

1. **Use API Keys em vez de Auth Tokens** - API Keys podem ter escopo definido e ser revogadas individualmente
2. **Aproveite o Event Streams** - Eventos baseados em push são mais eficientes do que polling no TaskRouter
3. **Construa um Flex Plugin** - Use um plugin de UI para capturar eventos de conclusão de tarefas em tempo real
4. **Mapeie canais de forma consistente** - Normalize dados de voz, SMS e chat em eventos unificados do Brevo
5. **Rastreie scores CSAT** - Sincronize dados de satisfação para o Brevo para segmentação orientada por experiência
6. **Monitore métricas de fila** - Use dados de tempo de espera para disparar comunicação proativa com o cliente

## Segurança

- **Account SID + Auth Token** - Autenticação padrão do Twilio
- **API Keys** - Credenciais revogáveis, não-root para uso em produção
- **Somente HTTPS** - Toda comunicação com a API é criptografada via TLS 1.2+
- **Validação de webhook** - Verifique assinaturas de webhook do Twilio com `X-Twilio-Signature`
- **Conformidade com PCI** - Twilio Flex é PCI DSS Level 1 compliant
- **Armazenamento criptografado** - Credenciais criptografadas em repouso no Tajo

## Recursos relacionados

- [Conector Gorgias](https://tajo.io/pt/docs/connectors/support/gorgias)
- [Conector Jira](https://tajo.io/pt/docs/connectors/custom/jira)
- [Skill de sincronização de clientes](https://tajo.io/pt/docs/skills/data-sync/customer-sync)
- [API de contatos do Brevo](https://tajo.io/pt/docs/contact-management)