Typeform konektor
Prepoj Typeform s Brevo cez Tajo na automatickú synchronizáciu odpovedí formulárov, zachytávanie leadov z konverzačných formulárov a spúšťanie marketingových automatizácií na základe odovzdaní prieskumov a výsledkov kvízov.
Prehľad
| Vlastnosť | Hodnota |
|---|---|
| Platforma | Typeform |
| Kategória | Formuláre a prieskumy (Vlastná) |
| Zložitosť nastavenia | Ľahké |
| Oficiálna integrácia | Nie |
| Synchronizované dáta | Odpovede, Kontakty, Udalosti, Formuláre |
| Metóda autentifikácie | OAuth 2.0 / Personal Access Token |
Funkcie
- Synchronizácia odpovedí v reálnom čase - Automaticky zachytávaj odovzdania formulárov cez webhooky
- Vytvorenie kontaktov - Vytváraj alebo aktualizuj kontakty Brevo z odpovedí formulárov
- Skórovanie leadov - Použi skóre kvízu a dáta formulára pre kvalifikáciu leadov
- Skryté polia - Prenášaj dáta zákazníkov cez Skryté polia pre personalizované formuláre
- Podmienené mapovanie - Mapuj rôzne polia formulára na základe logiky odpovedí
- Podpora viacerých formulárov - Prepoj viacero typeformulárov s rôznymi zoznamami Brevo
Predpoklady
Predtým, než začneš, uisti sa, že máš:
- Typeform účet (plán Basic alebo vyšší pre webhooky)
- Personal Access Token z Typeform Account Settings
- Brevo účet s API prístupom
- Tajo účet s oprávneniami pre konektory
Autentifikácia
Personal Access Token
# Generate a token at 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
// OAuth 2.0 Authorization Flowconst 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 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' })});Konfigurácia
Základné nastavenie
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}"Mapovanie polí
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_FEEDBACKAPI endpointy
| Endpoint | Metóda | Popis |
|---|---|---|
https://api.typeform.com/forms | GET | Zoznam všetkých formulárov |
https://api.typeform.com/forms/{form_id} | GET | Načítanie formulára |
https://api.typeform.com/forms | POST | Vytvorenie formulára |
https://api.typeform.com/forms/{form_id} | PUT | Aktualizácia formulára |
https://api.typeform.com/forms/{form_id}/responses | GET | Načítanie odpovedí |
https://api.typeform.com/forms/{form_id}/responses | DELETE | Odstránenie odpovedí |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | PUT | Vytvorenie/aktualizácia webhooku |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | GET | Získanie webhooku |
https://api.typeform.com/forms/{form_id}/webhooks | GET | Zoznam webhookov |
Ukážky kódu
Inicializácia konektora
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čítanie odpovedí formulára
// Fetch responses using the 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();
// Sync each response to 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] }); }}Nastavenie webhookov
// Register a webhook for real-time response notificationsawait 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 }) });Spracovanie webhookových udalostí
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');});Obmedzenia rýchlosti
| Endpoint | Limit rýchlosti | Poznámky |
|---|---|---|
| Create API | 2 požiadavky/sek | Vytvorenie a aktualizácia formulárov |
| Responses API | 2 požiadavky/sek | Načítanie odpovedí |
| Webhooks API | 2 požiadavky/sek | Správa webhookov |
| Všetky endpointy | 120 požiadaviek/min | Globálny limit rýchlosti |
Stránkovanie odpovedí
Responses API vracia maximálne 1 000 odpovedí na požiadavku. Pre stránkovanie pri načítaní veľkých sád odpovedí použi parametre kurzora before alebo after.
Riešenie problémov
| Problém | Príčina | Riešenie |
|---|---|---|
| Webhook nie je prijatý | Webhook je vypnutý | Povol webhook v dashboarde Typeform |
| Chýbajúce odpovede | Aplikovaný filter | Skontroluj parametre since/until a completed |
| Chyba autentifikácie 401 | Vypršaný token | Vygeneruj nový Personal Access Token |
| Limit rýchlosti 429 | Príliš veľa požiadaviek | Implementuj throttlovanie požiadaviek |
| Prázdne odpovede | Voliteľné polia | Spravuj nulové/nedefinované hodnoty odpovedí |
Debug režim
connectors: typeform: debug: true log_level: verbose log_webhooks: true log_responses: trueOdporúčané postupy
- Použi webhooky - Uprednostni webhooky pred pollingom pre zachytávanie odpovedí v reálnom čase
- Validuj podpisy - Vždy overuj podpisy webhookov pre bezpečnosť
- Použi Skryté polia - Pred-vyplňuj formuláre so známymi dátami zákazníka
- Mapuj referencie polí - Použi stabilné hodnoty
refpolí namiesto ID polí - Spravuj čiastočné odpovede - Zohľadni voliteľné a preskočené otázky
- Nastav logiku opakovania - Implementuj idempotentné spracovanie webhookov
Bezpečnosť
- OAuth 2.0 - Scoped autentifikácia na základe tokenov
- Podpisy webhookov - Validácia podpisu SHA-256 HMAC
- Iba HTTPS - Všetky API endpointy vyžadujú TLS
- Scoping tokenov - Požaduj minimálne potrebné OAuth scopy
- Správa tajomstiev - Uchovávaj tokeny v premenných prostredia alebo správcoch tajomstiev
- GDPR súlad - Použi Delete Responses API pre žiadosti o vymazanie dát