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
| Vlastnost | Hodnota |
|---|---|
| Platforma | Typeform |
| Kategorie | Formuláře a průzkumy (Vlastní) |
| Složitost nastavení | Snadná |
| Oficiální integrace | Ne |
| Synchronizovaná data | Odpově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:
- Účet Typeform (plán Basic nebo vyšší pro webhooky)
- Osobní přístupový token z Nastavení účtu Typeform
- Účet Brevo s přístupem k API
- Účet Tajo s oprávněními ke konektoru
Ověření
Osobní přístupový token
# Vygenerujte token na https://admin.typeform.com/account#/section/tokensexport TYPEFORM_ACCESS_TOKEN=tfp_your_personal_access_tokenexport TAJO_API_KEY=your_tajo_api_keyexport BREVO_API_KEY=your_brevo_api_keyOAuth 2.0
// Autorizační tok OAuth 2.0const 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ý tokenconst 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_FEEDBACKKoncové body API
| Koncový bod | Metoda | Popis |
|---|---|---|
https://api.typeform.com/forms | GET | Výpis všech formulářů |
https://api.typeform.com/forms/{form_id} | GET | Načtení formuláře |
https://api.typeform.com/forms | POST | Vytvoření formuláře |
https://api.typeform.com/forms/{form_id} | PUT | Aktualizace formuláře |
https://api.typeform.com/forms/{form_id}/responses | GET | Načtení odpovědí |
https://api.typeform.com/forms/{form_id}/responses | DELETE | Smazání odpovědí |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | PUT | Vytvoření/aktualizace webhooku |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | GET | Načtení webhooku |
https://api.typeform.com/forms/{form_id}/webhooks | GET | Vý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 APIconst 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 Brevofor (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 časeawait 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ý bod | Limit rychlosti | Poznámky |
|---|---|---|
| Create API | 2 požadavky/s | Vytváření a aktualizace formulářů |
| Responses API | 2 požadavky/s | Načítání odpovědí |
| Webhooks API | 2 požadavky/s | Správa webhooků |
| Všechny koncové body | 120 požadavků/min | Globá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ém | Příčina | Řešení |
|---|---|---|
| Webhook nebyl přijat | Webhook zakázán | Povolte webhook v řídicím panelu Typeform |
| Chybějící odpovědi | Aplikován filtr | Zkontrolujte parametry since/until a completed |
| Chyba ověření 401 | Vypršelý token | Vygenerujte nový osobní přístupový token |
| Limit rychlosti 429 | Příliš mnoho požadavků | Implementujte omezování požadavků |
| Prázdné odpovědi | Volitelná pole | Ošetřete hodnoty odpovědí null/undefined |
Režim ladění
connectors: typeform: debug: true log_level: verbose log_webhooks: true log_responses: trueOsvědčené postupy
- Používejte webhooky – Upřednostňujte webhooky před pollováním pro zachytávání odpovědí v reálném čase
- Ověřujte podpisy – Vždy ověřujte podpisy webhooků pro bezpečnost
- Používejte skrytá pole – Předvyplňujte známá zákaznická data ve formulářích
- Mapujte reference polí – Používejte stabilní hodnoty
refpolí místo ID polí - Ošetřujte částečné odpovědi – Počítejte s volitelnými a přeskočenými otázkami
- 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