Conector Freshdesk

Conecte o Freshdesk ao Brevo através do Tajo para unificar dados de suporte e marketing. Sincronize tickets de suporte ao cliente, perfis de contato e pontuações de satisfação para alimentar comunicações segmentadas com base em interações de suporte.

Visão geral

Recursos

• Sincronização de contatos - Sincronização bidirecional de contatos do Freshdesk para listas de contatos do Brevo
• Rastreamento de eventos de ticket - Encaminhe eventos de criação, atualização e resolução de tickets para o Brevo
• Sincronização de CSAT - Sincronize pontuações de satisfação do cliente como atributos de contato do Brevo
• Sincronização de empresas - Mapeie empresas do Freshdesk para segmentação de contatos do Brevo
• Dados de agente - Rastreie atribuições de agentes para automação de workflows internos
• Campos personalizados - Mapeie campos personalizados de tickets e contatos do Freshdesk para atributos do Brevo

Pré-requisitos

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

1. Uma conta Freshdesk com acesso de admin
2. Sua chave de API do Freshdesk (encontrada em Profile Settings)
3. Seu domínio do Freshdesk (por exemplo, suaempresa.freshdesk.com)
4. Uma conta Brevo com acesso à API
5. Uma conta Tajo com credenciais de API

Autenticação

Autenticação por chave API

O Freshdesk usa autenticação por chave API via HTTP Basic Auth. A chave API é usada como nome de usuário com qualquer string (normalmente X) como senha.

curl -u "YOUR_API_KEY:X" \
  https://yourcompany.freshdesk.com/api/v2/tickets

Ou usando codificação Base64 no cabeçalho Authorization:

curl https://yourcompany.freshdesk.com/api/v2/tickets \
  -H "Authorization: Basic BASE64_ENCODED_API_KEY:X" \
  -H "Content-Type: application/json"

Localizar sua chave API

1. Faça login em sua conta Freshdesk
2. Clique na sua foto de perfil no canto superior direito
3. Vá para Profile Settings
4. Sua chave API é exibida no lado direito

Configuração

Configuração básica

connectors:
  freshdesk:
    enabled: true
    domain: "yourcompany.freshdesk.com"
    api_key: "your-freshdesk-api-key"

    # Data sync options
    sync:
      contacts: true
      tickets: true
      companies: true
      satisfaction_ratings: true

    # Brevo list assignment
    lists:
      all_support_contacts: 30
      open_tickets: 31
      resolved_tickets: 32

Mapeamento de campos de contato

Mapeie campos de contato do Freshdesk para atributos do Brevo:

contact_mapping:
  email: email
  name: FULLNAME
  phone: SMS
  company_id: COMPANY
  job_title: JOB_TITLE
  twitter_id: TWITTER
  language: LANGUAGE
  time_zone: TIMEZONE

  # Support metrics
  total_tickets: TICKET_COUNT
  open_tickets: OPEN_TICKETS
  avg_csat: CSAT_SCORE
  last_ticket_date: LAST_SUPPORT_DATE

  # Custom fields
  custom_fields.account_type: ACCOUNT_TYPE
  custom_fields.subscription_tier: PLAN

Mapeamento de eventos de ticket

Mapeie eventos de ticket do Freshdesk para gatilhos de automação do Brevo:

ticket_events:
  ticket_created: "support_ticket_created"
  ticket_updated: "support_ticket_updated"
  ticket_resolved: "support_ticket_resolved"
  ticket_closed: "support_ticket_closed"
  ticket_reopened: "support_ticket_reopened"
  satisfaction_rated: "csat_submitted"
  note_added: "support_note_added"

Endpoints da API

Exemplos de código

Inicializar o conector Freshdesk

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Freshdesk account
await tajo.connectors.connect('freshdesk', {
  domain: 'yourcompany.freshdesk.com',
  apiKey: process.env.FRESHDESK_API_KEY
});

Sincronizar contatos para o Brevo

// Fetch Freshdesk contacts and sync to Brevo
const response = await fetch(
  'https://yourcompany.freshdesk.com/api/v2/contacts?page=1&per_page=100',
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${API_KEY}:X`),
      'Content-Type': 'application/json'
    }
  }
);

const contacts = await response.json();
// Each contact:
// {
//   "id": 12345,
//   "name": "Jane Kim",
//   "email": "[email protected]",
//   "phone": "+15551234567",
//   "company_id": 678,
//   "job_title": "Product Manager",
//   "created_at": "2024-01-15T10:30:00Z"
// }

Rastrear eventos de ticket

// Set up Freshdesk webhook to forward ticket events
// Configure in Freshdesk Admin > Automations > Webhook

// Webhook handler
app.post('/webhooks/freshdesk', async (req, res) => {
  const { ticket, event_type } = req.body;

  await tajo.connectors.handleWebhook('freshdesk', {
    topic: event_type,
    payload: {
      ticketId: ticket.id,
      subject: ticket.subject,
      status: ticket.status,
      priority: ticket.priority,
      requesterEmail: ticket.requester.email,
      createdAt: ticket.created_at
    }
  });

  res.status(200).send('OK');
});

Buscar tickets por cliente

// Search for all tickets from a specific customer
const query = encodeURIComponent('"email:[email protected]"');
const response = await fetch(
  `https://yourcompany.freshdesk.com/api/v2/search/tickets?query=${query}`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${API_KEY}:X`)
    }
  }
);

const { results, total } = await response.json();

Limites de taxa

Limites adicionais:

Solução de problemas

Melhores práticas

1. Use webhooks para sincronização em tempo real - Configure Freshdesk Automations para disparar webhooks em eventos de ticket
2. Sincronize pontuações CSAT - Rastreie avaliações de satisfação do cliente como atributos do Brevo para segmentação
3. Mapeie status de ticket para listas - Mova automaticamente contatos entre listas do Brevo com base no status do ticket
4. Rastreie métricas de suporte - Sincronize contagem de tickets, tempo médio de resposta e taxa de resolução por contato
5. Use a API de busca com moderação - A API de busca tem limites de taxa mais rigorosos; armazene resultados em cache quando possível
6. Paginação para grandes exportações - Use paginação com parâmetros page e per_page para a sincronização inicial

Segurança

• Autenticação por chave API - HTTP Basic Auth simples com chave API
• Somente HTTPS - Toda comunicação com a API requer criptografia TLS
• Whitelisting de IP - Disponível nos planos Estate e Forest
• Acesso baseado em função - Permissões de chave API vinculadas à função do agente
• SOC 2 Type II - O Freshdesk é certificado SOC 2 Type II
• Conformidade com GDPR - Suporta solicitações de exportação e exclusão de dados

Recursos relacionados

• Conector Brevo
• Skill de sincronização de clientes
• Conector Shopify
• API de contatos do Brevo