Trình Kết Nối Freshdesk

Kết nối Freshdesk với Brevo qua Tajo để hợp nhất dữ liệu support và marketing. Đồng bộ customer support tickets, contact profiles và satisfaction scores để tạo ra các thông tin liên lạc có mục tiêu dựa trên tương tác hỗ trợ.

Tổng Quan

Tính Năng

• Đồng bộ contact - Đồng bộ hai chiều Freshdesk contacts sang danh sách contacts Brevo
• Theo dõi ticket events - Forward ticket creation, update và resolution events sang Brevo
• Đồng bộ CSAT - Đồng bộ customer satisfaction scores như thuộc tính liên hệ Brevo
• Đồng bộ company - Ánh xạ Freshdesk companies sang phân đoạn liên hệ Brevo
• Dữ liệu agent - Theo dõi agent assignments cho internal workflow automation
• Custom fields - Ánh xạ Freshdesk custom ticket và contact fields sang thuộc tính Brevo

Yêu Cầu

Trước khi bắt đầu, hãy đảm bảo bạn có:

1. Tài khoản Freshdesk với quyền admin
2. Freshdesk API Key (tìm trong Profile Settings)
3. Domain Freshdesk của bạn (ví dụ: yourcompany.freshdesk.com)
4. Tài khoản Brevo với quyền truy cập API
5. Tài khoản Tajo với API credentials

Xác Thực

Xác Thực API Key

Freshdesk sử dụng API key authentication qua HTTP Basic Auth. API key được dùng làm username với bất kỳ chuỗi nào (thường là X) làm password.

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

Hoặc dùng Base64 encoding trong Authorization header:

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

Tìm API Key

1. Đăng nhập vào tài khoản Freshdesk của bạn
2. Nhấp vào ảnh hồ sơ ở góc trên bên phải
3. Vào Profile Settings
4. API Key được hiển thị ở bên phải

Cấu Hình

Thiết Lập Cơ Bản

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

    # Tùy chọn đồng bộ dữ liệu
    sync:
      contacts: true
      tickets: true
      companies: true
      satisfaction_ratings: true

    # Gán danh sách Brevo
    lists:
      all_support_contacts: 30
      open_tickets: 31
      resolved_tickets: 32

Ánh Xạ Trường Contact

Ánh xạ trường contact Freshdesk sang thuộc tính Brevo:

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

  # Số liệu support
  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

Ánh Xạ Ticket Event

Ánh xạ Freshdesk ticket events sang Brevo automation triggers:

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"

API Endpoints

Ví Dụ Code

Khởi Tạo Trình Kết Nối Freshdesk

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

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

// Kết nối tài khoản Freshdesk
await tajo.connectors.connect('freshdesk', {
  domain: 'yourcompany.freshdesk.com',
  apiKey: process.env.FRESHDESK_API_KEY
});

Đồng Bộ Contacts Sang Brevo

// Lấy Freshdesk contacts và đồng bộ sang 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();
// Mỗi 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"
// }

Theo Dõi Ticket Events

// Thiết lập Freshdesk webhook để forward ticket events
// Cấu hình trong 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');
});

Tìm Kiếm Tickets Theo Khách Hàng

// Tìm tất cả tickets từ một khách hàng cụ thể
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();

Giới Hạn Tốc Độ

Giới hạn bổ sung:

Khắc Phục Sự Cố

Thực Hành Tốt Nhất

1. Dùng webhooks để đồng bộ thời gian thực - Cấu hình Freshdesk Automations để kích hoạt webhooks trên ticket events
2. Đồng bộ điểm CSAT - Theo dõi customer satisfaction ratings như thuộc tính Brevo để phân đoạn
3. Ánh xạ ticket status sang danh sách - Tự động chuyển contacts giữa danh sách Brevo dựa trên ticket status
4. Theo dõi support metrics - Đồng bộ ticket count, thời gian phản hồi trung bình và tỷ lệ giải quyết mỗi contact
5. Dùng search API hạn chế - Search API có giới hạn tốc độ nghiêm ngặt hơn; cache kết quả khi có thể
6. Phân trang exports lớn - Sử dụng phân trang với tham số page và per_page cho lần đồng bộ đầu tiên

Bảo Mật

• Xác thực API key - HTTP Basic Auth đơn giản với API key
• Chỉ HTTPS - Tất cả giao tiếp API yêu cầu mã hóa TLS
• IP whitelisting - Có sẵn trên gói Estate và Forest
• Truy cập dựa trên vai trò - Quyền API key gắn với vai trò agent
• SOC 2 Type II - Freshdesk được chứng nhận SOC 2 Type II
• Tuân thủ GDPR - Hỗ trợ yêu cầu xuất và xóa dữ liệu

Tài Nguyên Liên Quan

• Trình Kết Nối Brevo
• Customer Sync Skill
• Trình Kết Nối Shopify
• Brevo Contacts API