Ajukan akses awal

Masukkan nama depan serta email atau nomor telepon Anda. Kami akan menghubungi Anda dengan detail akses Tajo.

Konektor Typeform

Hubungkan Typeform ke Brevo melalui Tajo untuk menyinkronkan respons formulir secara otomatis, menangkap lead dari formulir konversasional, dan memicu otomatisasi pemasaran berdasarkan pengiriman survei dan hasil kuis.

Ikhtisar

Properti	Nilai
Platform	Typeform
Kategori	Formulir & Survei (Custom)
Kompleksitas setup	Mudah
Integrasi resmi	Tidak
Data yang disinkronkan	Respons, kontak, event, formulir
Metode autentikasi	OAuth 2.0 / Personal Access Token

Fitur

Sinkronisasi respons real-time - Tangkap pengiriman formulir secara otomatis via webhook
Pembuatan kontak - Buat atau perbarui kontak Brevo dari respons formulir
Lead scoring - Gunakan skor kuis dan data formulir untuk kualifikasi lead
Hidden Fields - Kirimkan data pelanggan lewat Hidden Fields untuk formulir yang dipersonalisasi
Pemetaan kondisional - Petakan field formulir yang berbeda berdasarkan logika respons
Dukungan multi-formulir - Hubungkan beberapa typeform ke list Brevo yang berbeda

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Akun Typeform (paket Basic atau lebih tinggi untuk webhook)
Personal Access Token dari Pengaturan Akun Typeform
Akun Brevo dengan akses API
Akun Tajo dengan izin konektor

Autentikasi

Personal Access Token

# Generate a token at https://admin.typeform.com/account#/section/tokens
export TYPEFORM_ACCESS_TOKEN=tfp_your_personal_access_token
export TAJO_API_KEY=your_tajo_api_key
export BREVO_API_KEY=your_brevo_api_key

OAuth 2.0

// OAuth 2.0 Authorization Flow
const authUrl = 'https://api.typeform.com/oauth/authorize?' +
  new URLSearchParams({
    client_id: process.env.TYPEFORM_CLIENT_ID,
    redirect_uri: 'https://your-app.com/callback',
    scope: 'forms:read responses:read webhooks:write accounts:read',
    state: generateState()
  });

// Exchange authorization code for access token
const tokenResponse = await fetch('https://api.typeform.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: authorizationCode,
    client_id: process.env.TYPEFORM_CLIENT_ID,
    client_secret: process.env.TYPEFORM_CLIENT_SECRET,
    redirect_uri: 'https://your-app.com/callback'
  })
});

Konfigurasi

Setup dasar

connectors:
  typeform:
    enabled: true
    access_token: "${TYPEFORM_ACCESS_TOKEN}"

    forms:
      - form_id: "abc123"
        list_id: 5
        mapping:
          email_field: "email"
          name_field: "full_name"
      - form_id: "xyz789"
        list_id: 6
        mapping:
          email_field: "work_email"

    sync:
      responses: true
      contacts: true
      events: true

    webhook:
      enabled: true
      secret: "${TYPEFORM_WEBHOOK_SECRET}"

Pemetaan field

field_mapping:
  # Map Typeform field references to Brevo attributes
  email: email
  name: FIRSTNAME
  company: COMPANY
  phone: SMS
  score: LEAD_SCORE
  quiz_result: QUIZ_SCORE
  nps_rating: NPS_SCORE
  feedback: LAST_FEEDBACK

Endpoint API

Endpoint	Metode	Deskripsi
`https://api.typeform.com/forms`	GET	Menampilkan semua formulir
`https://api.typeform.com/forms/{form_id}`	GET	Mengambil sebuah formulir
`https://api.typeform.com/forms`	POST	Membuat formulir
`https://api.typeform.com/forms/{form_id}`	PUT	Memperbarui formulir
`https://api.typeform.com/forms/{form_id}/responses`	GET	Mengambil respons
`https://api.typeform.com/forms/{form_id}/responses`	DELETE	Menghapus respons
`https://api.typeform.com/forms/{form_id}/webhooks/{tag}`	PUT	Membuat/memperbarui webhook
`https://api.typeform.com/forms/{form_id}/webhooks/{tag}`	GET	Mengambil webhook
`https://api.typeform.com/forms/{form_id}/webhooks`	GET	Menampilkan webhook

Contoh kode

Inisialisasi konektor

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('typeform', {
  accessToken: process.env.TYPEFORM_ACCESS_TOKEN,
  forms: ['abc123', 'xyz789']
});

Mengambil respons formulir

// Fetch responses using the Responses API
const response = await fetch(
  'https://api.typeform.com/forms/abc123/responses?' +
    new URLSearchParams({
      page_size: 25,
      since: '2024-01-01T00:00:00Z',
      completed: 'true'
    }),
  {
    headers: {
      'Authorization': `Bearer ${process.env.TYPEFORM_ACCESS_TOKEN}`
    }
  }
);

const data = await response.json();

// Sync each response to Brevo
for (const item of data.items) {
  const answers = item.answers;
  const email = answers.find(a => a.field.ref === 'email')?.email;

  if (email) {
    await tajo.contacts.sync({
      email,
      attributes: {
        FIRSTNAME: answers.find(a => a.field.ref === 'name')?.text,
        LEAD_SCORE: item.calculated?.score || 0
      },
      listIds: [5]
    });
  }
}

Menyiapkan webhook

// Register a webhook for real-time response notifications
await fetch(
  'https://api.typeform.com/forms/abc123/webhooks/tajo-sync',
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.TYPEFORM_ACCESS_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://api.tajo.io/webhooks/typeform',
      enabled: true,
      secret: process.env.TYPEFORM_WEBHOOK_SECRET
    })
  }
);

Menangani event webhook

app.post('/webhooks/typeform', async (req, res) => {
  // Verify webhook signature
  const signature = req.headers['typeform-signature'];
  const isValid = verifyTypeformSignature(
    req.rawBody, signature, process.env.TYPEFORM_WEBHOOK_SECRET
  );

  if (!isValid) return res.status(401).send('Unauthorized');

  const { form_response } = req.body;

  await tajo.connectors.handleWebhook('typeform', {
    topic: 'form_response',
    payload: form_response
  });

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

Batas rate

Endpoint	Batas rate	Catatan
Create API	2 permintaan/detik	Pembuatan dan pembaruan formulir
Responses API	2 permintaan/detik	Pengambilan respons
Webhooks API	2 permintaan/detik	Pengelolaan webhook
Semua endpoint	120 permintaan/menit	Batas rate global

Paginasi respons

Responses API mengembalikan maksimum 1.000 respons per permintaan. Gunakan parameter cursor before atau after untuk paginasi saat mengambil kumpulan respons yang besar.

Pemecahan masalah

Masalah	Penyebab	Solusi
Webhook tidak diterima	Webhook dinonaktifkan	Aktifkan webhook di dasbor Typeform
Respons hilang	Filter diterapkan	Periksa parameter `since`/`until` dan `completed`
Error auth 401	Token kedaluwarsa	Buat Personal Access Token baru
Batas rate 429	Terlalu banyak permintaan	Terapkan pembatasan laju permintaan
Jawaban kosong	Field opsional	Tangani nilai jawaban null/undefined

Mode debug

connectors:
  typeform:
    debug: true
    log_level: verbose
    log_webhooks: true
    log_responses: true

Praktik terbaik

Gunakan webhook - Utamakan webhook daripada polling untuk menangkap respons secara real-time
Validasi tanda tangan - Selalu verifikasi tanda tangan webhook demi keamanan
Gunakan Hidden Fields - Isi terlebih dahulu data pelanggan yang sudah diketahui di formulir
Petakan referensi field - Gunakan nilai ref field yang stabil, bukan ID field
Tangani respons parsial - Perhitungkan pertanyaan opsional dan yang dilewati
Siapkan logika retry - Terapkan pemrosesan webhook yang idempoten

Keamanan

OAuth 2.0 - Autentikasi berbasis token yang tercakup
Tanda tangan webhook - Validasi tanda tangan HMAC SHA-256
Hanya HTTPS - Seluruh endpoint API mewajibkan TLS
Pencakupan token - Minta scope OAuth seminimal yang diperlukan
Pengelolaan secret - Simpan token dalam variabel lingkungan atau secret manager
Kepatuhan GDPR - Gunakan Delete Responses API untuk permintaan penghapusan data