Typeform konnektor
Csatlakoztasd a Typeformet a Brevóhoz a Tajo segítségével, hogy automatikusan szinkronizáld az űrlapválaszokat, érdeklődőket rögzíts társalgási űrlapokból, és marketingautomatizálásokat indíts felmérés-beküldések és kvíz-eredmények alapján.
Áttekintés
| Tulajdonság | Érték |
|---|---|
| Platform | Typeform |
| Kategória | Űrlapok és felmérések (Egyéni) |
| Telepítés bonyolultsága | Könnyű |
| Hivatalos integráció | Nem |
| Szinkronizált adatok | Válaszok, Kapcsolatok, Események, Űrlapok |
| Hitelesítési módszer | OAuth 2.0 / Személyes hozzáférési token |
Funkciók
- Valós idejű válasz-szinkronizáció – Automatikusan rögzíti az űrlapbeküldéseket webhookokon keresztül
- Kapcsolat létrehozás – Brevo kapcsolatok létrehozása vagy frissítése az űrlapválaszokból
- Érdeklődő-pontozás – Kvíz pontszámok és űrlapadatok használata az érdeklődők minősítéséhez
- Rejtett mezők – Ügyféladatok átadása rejtett mezőkön keresztül személyre szabott űrlapokhoz
- Feltételes leképezés – Különböző mezők leképezése a válasz logikája alapján
- Több-űrlap támogatás – Több typeform csatlakoztatása különböző Brevo listákhoz
Előfeltételek
Mielőtt elkezdenéd, győződj meg róla, hogy rendelkezel:
- Egy Typeform fiókkal (Basic vagy magasabb csomag webhookokhoz)
- Egy személyes hozzáférési tokennel a Typeform Fiókbeállításokból
- Egy Brevo fiókkal API-hozzáféréssel
- Egy Tajo fiókkal konnektor engedélyekkel
Hitelesítés
Személyes hozzáférési 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áció
Alapbeállítás
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}"Mezőleképezés
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 végpontok
| Végpont | Módszer | Leírás |
|---|---|---|
https://api.typeform.com/forms | GET | Összes űrlap listázása |
https://api.typeform.com/forms/{form_id} | GET | Egy űrlap lekérése |
https://api.typeform.com/forms | POST | Űrlap létrehozása |
https://api.typeform.com/forms/{form_id} | PUT | Űrlap frissítése |
https://api.typeform.com/forms/{form_id}/responses | GET | Válaszok lekérése |
https://api.typeform.com/forms/{form_id}/responses | DELETE | Válaszok törlése |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | PUT | Webhook létrehozása/frissítése |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | GET | Webhook lekérése |
https://api.typeform.com/forms/{form_id}/webhooks | GET | Webhookok listázása |
Kódpéldák
A konnektor inicializálása
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']});Űrlapválaszok lekérése
// 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] }); }}Webhookok beállítása
// 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 }) });Webhook események kezelése
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');});Ráta-korlátok
| Végpont | Ráta-korlát | Megjegyzések |
|---|---|---|
| Create API | 2 kérés/mp | Űrlap létrehozás és frissítések |
| Responses API | 2 kérés/mp | Válaszok lekérése |
| Webhooks API | 2 kérés/mp | Webhook kezelés |
| Összes végpont | 120 kérés/perc | Globális ráta-korlát |
Válasz-oldalazás
A Responses API kérésenként legfeljebb 1 000 választ ad vissza. Nagy válaszkészletek lekérésekor használd a before vagy after kurzor paramétereket az oldalazáshoz.
Hibaelhárítás
| Probléma | Ok | Megoldás |
|---|---|---|
| Webhook nem érkezik | Webhook letiltva | Engedélyezd a webhookot a Typeform dashboardon |
| Hiányzó válaszok | Szűrő alkalmazva | Ellenőrizd a since/until és completed paramétereket |
| Auth hiba 401 | Token lejárt | Generálj új személyes hozzáférési tokent |
| Ráta-korlát 429 | Túl sok kérés | Implementálj kérés-korlátozást |
| Üres válaszok | Opcionális mezők | Kezelj null/undefined válasz értékeket |
Hibakeresési mód
connectors: typeform: debug: true log_level: verbose log_webhooks: true log_responses: trueLegjobb gyakorlatok
- Használj webhookokat – A webhookokat részesítsd előnyben a lekérdezéssel szemben a valós idejű válasz-rögzítéshez
- Validáld az aláírásokat – Mindig ellenőrizd a webhook aláírásokat a biztonságért
- Használj rejtett mezőket – Töltsd előre az ismert ügyféladatokat az űrlapokban
- Képezd le a mező hivatkozásokat – Használj stabil mező
refértékeket a mező azonosítók helyett - Kezelj részleges válaszokat – Vedd figyelembe az opcionális és kihagyott kérdéseket
- Állíts be újrapróbálkozási logikát – Implementálj idempotens webhook-feldolgozást
Biztonság
- OAuth 2.0 – Hatókörrel korlátozott token alapú hitelesítés
- Webhook aláírások – SHA-256 HMAC aláírás-ellenőrzés
- Csak HTTPS – Minden API végpont TLS-t igényel
- Token hatókörök – Kérj minimálisan szükséges OAuth hatóköröket
- Titokkezelés – Tárold a tokeneket környezeti változókban vagy titkos kezelőkben
- GDPR megfelelőség – Használd a Delete Responses API-t az adattörlési kérelmekhez