Konektor Typeform

Propojte Typeform s Brevo přes Tajo pro automatickou synchronizaci odpovědí z formulářů, zachytávání potenciálních zákazníků z konverzačních formulářů a spouštění marketingových automatizací na základě odeslaných průzkumů a výsledků kvízů.

Přehled

VlastnostHodnota
PlatformaTypeform
KategorieFormuláře a průzkumy (Vlastní)
Složitost nastaveníSnadná
Oficiální integraceNe
Synchronizovaná dataOdpovědi, Kontakty, Události, Formuláře
Metoda ověřeníOAuth 2.0 / Osobní přístupový token

Funkce

  • Synchronizace odpovědí v reálném čase – Automatické zachytávání odeslaných formulářů přes webhooky
  • Vytváření kontaktů – Vytvářejte nebo aktualizujte kontakty Brevo z odpovědí formulářů
  • Skórování potenciálních zákazníků – Používejte skóre kvízů a data formulářů pro kvalifikaci potenciálních zákazníků
  • Skrytá pole – Předávejte zákaznická data přes skrytá pole pro personalizované formuláře
  • Podmíněné mapování – Mapujte různá pole formuláře na základě logiky odpovědí
  • Podpora více formulářů – Připojte více typeformů k různým seznamům Brevo

Předpoklady

Než začnete, ujistěte se, že máte:

  1. Účet Typeform (plán Basic nebo vyšší pro webhooky)
  2. Osobní přístupový token z Nastavení účtu Typeform
  3. Účet Brevo s přístupem k API
  4. Účet Tajo s oprávněními ke konektoru

Ověření

Osobní přístupový token

Terminal window
# Vygenerujte token na 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

// Autorizační tok OAuth 2.0
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()
});
// Výměna autorizačního kódu za přístupový 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'
})
});

Konfigurace

Základní nastavení

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}"

Mapování polí

field_mapping:
# Mapování odkazů polí Typeform na atributy Brevo
email: email
name: FIRSTNAME
company: COMPANY
phone: SMS
score: LEAD_SCORE
quiz_result: QUIZ_SCORE
nps_rating: NPS_SCORE
feedback: LAST_FEEDBACK

Koncové body API

Koncový bodMetodaPopis
https://api.typeform.com/formsGETVýpis všech formulářů
https://api.typeform.com/forms/{form_id}GETNačtení formuláře
https://api.typeform.com/formsPOSTVytvoření formuláře
https://api.typeform.com/forms/{form_id}PUTAktualizace formuláře
https://api.typeform.com/forms/{form_id}/responsesGETNačtení odpovědí
https://api.typeform.com/forms/{form_id}/responsesDELETESmazání odpovědí
https://api.typeform.com/forms/{form_id}/webhooks/{tag}PUTVytvoření/aktualizace webhooku
https://api.typeform.com/forms/{form_id}/webhooks/{tag}GETNačtení webhooku
https://api.typeform.com/forms/{form_id}/webhooksGETVýpis webhooků

Příklady kódu

Inicializace konektoru

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

Načtení odpovědí formuláře

// Načtení odpovědí pomocí 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();
// Synchronizace každé odpovědi do 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]
});
}
}

Nastavení webhooků

// Registrace webhooku pro notifikace o odpovědích v reálném čase
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
})
}
);

Zpracování webhookových událostí

app.post('/webhooks/typeform', async (req, res) => {
// Ověření podpisu webhooku
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');
});

Omezení rychlosti

Koncový bodLimit rychlostiPoznámky
Create API2 požadavky/sVytváření a aktualizace formulářů
Responses API2 požadavky/sNačítání odpovědí
Webhooks API2 požadavky/sSpráva webhooků
Všechny koncové body120 požadavků/minGlobální limit rychlosti

Stránkování odpovědí

Responses API vrací maximálně 1 000 odpovědí na požadavek. Pro stránkování při načítání velkých sad odpovědí používejte parametry kurzoru before nebo after.

Řešení problémů

ProblémPříčinaŘešení
Webhook nebyl přijatWebhook zakázánPovolte webhook v řídicím panelu Typeform
Chybějící odpovědiAplikován filtrZkontrolujte parametry since/until a completed
Chyba ověření 401Vypršelý tokenVygenerujte nový osobní přístupový token
Limit rychlosti 429Příliš mnoho požadavkůImplementujte omezování požadavků
Prázdné odpovědiVolitelná poleOšetřete hodnoty odpovědí null/undefined

Režim ladění

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

Osvědčené postupy

  1. Používejte webhooky – Upřednostňujte webhooky před pollováním pro zachytávání odpovědí v reálném čase
  2. Ověřujte podpisy – Vždy ověřujte podpisy webhooků pro bezpečnost
  3. Používejte skrytá pole – Předvyplňujte známá zákaznická data ve formulářích
  4. Mapujte reference polí – Používejte stabilní hodnoty ref polí místo ID polí
  5. Ošetřujte částečné odpovědi – Počítejte s volitelnými a přeskočenými otázkami
  6. Nastavte logiku opakování – Implementujte idempotentní zpracování webhooků

Zabezpečení

  • OAuth 2.0 – Ověřování na základě tokenů s vymezením rozsahu
  • Podpisy webhooků – Ověření podpisu SHA-256 HMAC
  • Pouze HTTPS – Všechny koncové body API vyžadují TLS
  • Vymezení tokenů – Požadujte minimální potřebné rozsahy OAuth
  • Správa tajných klíčů – Ukládejte tokeny v proměnných prostředí nebo manažerech tajných klíčů
  • Soulad s GDPR – Používejte Delete Responses API pro žádosti o vymazání dat

Související zdroje

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AI asistent

Ahoj! Zeptejte se mě na dokumentaci.