Connettore Freshdesk

Collega Freshdesk a Brevo tramite Tajo per unificare i dati di supporto e marketing. Sincronizza ticket di supporto clienti, profili contatto e punteggi di soddisfazione per alimentare comunicazioni mirate basate sulle interazioni di supporto.

Panoramica

Funzionalità

• Sync dei contatti - Sync bidirezionale dei contatti Freshdesk alle liste contatti Brevo
• Tracciamento eventi ticket - Inoltra eventi di creazione, aggiornamento e risoluzione ticket a Brevo
• Sync CSAT - Sincronizza i punteggi di soddisfazione clienti come attributi di contatto Brevo
• Sync delle aziende - Mappa le aziende Freshdesk alla segmentazione contatti Brevo
• Dati agent - Traccia le assegnazioni agent per l’automazione del workflow interno
• Campi personalizzati - Mappa i campi personalizzati di ticket e contatto Freshdesk agli attributi Brevo

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Freshdesk con accesso admin
2. La tua chiave API Freshdesk (in Profile Settings)
3. Il tuo dominio Freshdesk (es. yourcompany.freshdesk.com)
4. Un account Brevo con accesso API
5. Un account Tajo con credenziali API

Autenticazione

Autenticazione con chiave API

Freshdesk utilizza l’autenticazione con chiave API tramite HTTP Basic Auth. La chiave API è usata come username con qualsiasi stringa (tipicamente X) come password.

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

Oppure usando la codifica Base64 nell’header Authorization:

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

Trovare la tua chiave API

1. Accedi al tuo account Freshdesk
2. Clicca sull’immagine del tuo profilo nell’angolo in alto a destra
3. Vai in Profile Settings
4. La tua chiave API è visualizzata sul lato destro

Configurazione

Setup di base

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

Mappatura dei campi contatto

Mappa i campi di contatto Freshdesk agli attributi 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

Mappatura eventi ticket

Mappa gli eventi ticket Freshdesk ai trigger di automazione 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"

Endpoint API

Esempi di codice

Inizializza il connettore 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
});

Sincronizza i contatti su 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"
// }

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

Cerca ticket per 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();

Limiti di velocità

Limiti aggiuntivi:

Risoluzione dei problemi

Best practice

1. Usa i webhook per la sync in tempo reale - Configura le Automations Freshdesk per attivare webhook su eventi ticket
2. Sincronizza i punteggi CSAT - Traccia le valutazioni di soddisfazione clienti come attributi Brevo per la segmentazione
3. Mappa lo stato del ticket alle liste - Sposta automaticamente i contatti tra liste Brevo in base allo stato del ticket
4. Traccia le metriche di supporto - Sincronizza conteggio ticket, tempo medio di risposta e tasso di risoluzione per contatto
5. Usa la search API con parsimonia - La search API ha limiti di velocità più stringenti; metti in cache i risultati quando possibile
6. Pagina le esportazioni grandi - Usa la paginazione con i parametri page e per_page per la sync iniziale

Sicurezza

• Autenticazione con chiave API - HTTP Basic Auth semplice con chiave API
• Solo HTTPS - Tutte le comunicazioni API richiedono cifratura TLS
• IP whitelisting - Disponibile sui piani Estate e Forest
• Accesso basato sui ruoli - Permessi della chiave API legati al ruolo agent
• SOC 2 Type II - Freshdesk è certificato SOC 2 Type II
• Conformità GDPR - Supporta richieste di esportazione ed eliminazione dati

Risorse correlate

• Connettore Brevo
• Skill Customer Sync
• Connettore Shopify
• API Contatti Brevo