Typeform конектор
Свържи Typeform с Brevo през Tajo, за да синхронизираш автоматично отговори от форми, да улавяш lead-и от разговорни форми и да задействаш маркетингови автоматизации на базата на изпращания на анкети и резултати от quizове.
Преглед
| Свойство | Стойност |
|---|---|
| Платформа | Typeform |
| Категория | Форми и анкети (персонализирана) |
| Сложност на настройка | Лесна |
| Официална интеграция | Не |
| Синхронизирани данни | Отговори, контакти, събития, форми |
| Метод на автентикация | OAuth 2.0 / Personal Access Token |
Функции
- Синхронизация на отговори в реално време – Автоматично улавяй изпращания на форми чрез уебхуци
- Създаване на контакти – Създавай или обновявай контакти в Brevo от отговори на форми
- Lead scoring – Използвай резултати от quizове и данни от форми за квалификация на lead-и
- Hidden Fields – Предавай клиентски данни чрез Hidden Fields за персонализирани форми
- Условно мапване – Мапвай различни полета от форми на базата на логика на отговорите
- Поддръжка на множество форми – Свързвай множество typeform-и към различни списъци в Brevo
Предварителни условия
Преди да започнеш, увери се, че имаш:
- Акаунт в Typeform (Basic план или по-горе за уебхуци)
- Personal Access Token от Typeform Account Settings
- Акаунт в Brevo с API достъп
- Акаунт в Tajo с разрешения за конектори
Автентикация
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' })});Конфигурация
Основна настройка
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}"Мапване на полета
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 крайни точки
| Крайна точка | Метод | Описание |
|---|---|---|
https://api.typeform.com/forms | GET | Списък с всички форми |
https://api.typeform.com/forms/{form_id} | GET | Получаване на форма |
https://api.typeform.com/forms | POST | Създаване на форма |
https://api.typeform.com/forms/{form_id} | PUT | Обновяване на форма |
https://api.typeform.com/forms/{form_id}/responses | GET | Получаване на отговори |
https://api.typeform.com/forms/{form_id}/responses | DELETE | Изтриване на отговори |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | PUT | Създаване/обновяване на уебхук |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | GET | Получаване на уебхук |
https://api.typeform.com/forms/{form_id}/webhooks | GET | Списък с уебхуци |
Примери с код
Инициализация на конектора
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']});Получаване на отговори от форма
// 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] }); }}Настройка на уебхуци
// 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 }) });Обработка на уебхук събития
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');});Ограничения на заявките
| Крайна точка | Rate Limit | Бележки |
|---|---|---|
| Create API | 2 заявки/сек | Създаване и обновяване на форми |
| Responses API | 2 заявки/сек | Извличане на отговори |
| Webhooks API | 2 заявки/сек | Управление на уебхуци |
| Всички крайни точки | 120 заявки/мин | Глобален rate limit |
Пагинация на отговорите
Responses API връща максимум 1 000 отговора на заявка. Използвай параметрите за курсор before или after за пагинация при извличане на големи набори от отговори.
Отстраняване на проблеми
| Проблем | Причина | Решение |
|---|---|---|
| Уебхукът не се получава | Уебхукът е деактивиран | Активирай уебхука в Typeform dashboard |
| Липсващи отговори | Приложен филтър | Провери параметрите since/until и completed |
| Грешка 401 при автентикация | Token изтекъл | Генерирай нов Personal Access Token |
| Rate limit 429 | Твърде много заявки | Внедри throttling на заявките |
| Празни отговори | Опционални полета | Обработвай null/undefined стойности на отговорите |
Режим за дебъг
connectors: typeform: debug: true log_level: verbose log_webhooks: true log_responses: trueДобри практики
- Използвай уебхуци – Предпочитай уебхуци пред polling за улавяне на отговори в реално време
- Валидирай подписите – Винаги верифицирай подписите на уебхуци за сигурност
- Използвай Hidden Fields – Предварително попълни известни клиентски данни във формите
- Мапвай field references – Използвай стабилни стойности
refна полета вместо field IDs - Обработвай частични отговори – Съобрази се с опционални и пропуснати въпроси
- Настрой retry логика – Внедри идемпотентна обработка на уебхуци
Сигурност
- OAuth 2.0 – Scoped token-базирана автентикация
- Подписи на уебхуци – SHA-256 HMAC валидация на подпис
- Само HTTPS – Всички API крайни точки изискват TLS
- Token scoping – Заявявай минимално необходимите OAuth обхвати
- Управление на тайни – Съхранявай tokens в environment variables или secret managers
- GDPR съвместимост – Използвай Delete Responses API за заявки за изтриване на данни