Коннектор Typeform
Подключите Typeform к Brevo через Tajo для автоматической синхронизации ответов на формы, захвата лидов из диалоговых форм и запуска маркетинговых автоматизаций на основе отправок опросов и результатов квизов.
Обзор
| Свойство | Значение |
|---|---|
| Платформа | Typeform |
| Категория | Forms & Surveys (Custom) |
| Сложность настройки | Простая |
| Официальная интеграция | Нет |
| Синхронизируемые данные | Ответы, контакты, события, формы |
| Метод аутентификации | OAuth 2.0 / Personal Access Token |
Возможности
- Синхронизация ответов в реальном времени, автоматический захват отправок форм через вебхуки
- Создание контактов, создание или обновление контактов Brevo из ответов на формы
- Скоринг лидов, использование результатов квизов и данных форм для квалификации лидов
- Hidden Fields, передача данных клиентов через скрытые поля для персонализированных форм
- Условное сопоставление, сопоставление разных полей формы в зависимости от логики ответов
- Поддержка нескольких форм, подключение нескольких typeform к разным листам Brevo
Предварительные требования
Прежде чем начать, убедитесь, что у вас есть:
- Аккаунт Typeform (тариф Basic и выше для вебхуков)
- Personal Access Token из настроек аккаунта Typeform
- Аккаунт Brevo с доступом к API
- Аккаунт Tajo с правами на управление коннекторами
Аутентификация
Personal Access Token
# Сгенерируйте на 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.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() });
// Обмен кода авторизации на токен доступа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' })});Конфигурация
Базовая настройка
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: # Сопоставление ссылок на поля Typeform с атрибутами Brevo email: email name: FIRSTNAME company: COMPANY phone: SMS score: LEAD_SCORE quiz_result: QUIZ_SCORE nps_rating: NPS_SCORE feedback: LAST_FEEDBACKЭндпоинты API
| Эндпоинт | Метод | Описание |
|---|---|---|
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']});Получение ответов на форму
// Получение ответов через 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();
// Синхронизация каждого ответа с 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] }); }}Настройка вебхуков
// Регистрация вебхука для уведомлений о новых ответах в реальном времени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 }) });Обработка событий вебхука
app.post('/webhooks/typeform', async (req, res) => { // Проверка подписи вебхука 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');});Ограничения скорости
| Эндпоинт | Ограничение скорости | Примечания |
|---|---|---|
| Create API | 2 запроса/сек | Создание и обновление форм |
| Responses API | 2 запроса/сек | Получение ответов |
| Webhooks API | 2 запроса/сек | Управление вебхуками |
| Все эндпоинты | 120 запросов/мин | Глобальный лимит |
Пагинация ответов
Responses API возвращает максимум 1 000 ответов на запрос. Используйте параметры курсора before или after для пагинации при извлечении больших наборов ответов.
Устранение неполадок
| Проблема | Причина | Решение |
|---|---|---|
| Вебхук не получен | Вебхук отключён | Включите вебхук в панели управления Typeform |
| Отсутствующие ответы | Применён фильтр | Проверьте параметры since/until и completed |
| Ошибка авторизации 401 | Истёкший токен | Сгенерируйте новый Personal Access Token |
| Лимит 429 | Слишком много запросов | Реализуйте регулирование запросов |
| Пустые ответы | Необязательные поля | Обрабатывайте null/undefined значения ответов |
Режим отладки
connectors: typeform: debug: true log_level: verbose log_webhooks: true log_responses: trueЛучшие практики
- Используйте вебхуки, предпочтительнее опроса для захвата ответов в реальном времени
- Валидируйте подписи, всегда проверяйте подписи вебхуков для безопасности
- Используйте Hidden Fields, предзаполняйте известные данные о клиентах в формах
- Используйте ссылки на поля, применяйте стабильные значения
refполей вместо ID полей - Обрабатывайте частичные ответы, учитывайте необязательные и пропущенные вопросы
- Настройте логику повтора, реализуйте идемпотентную обработку вебхуков
Безопасность
- OAuth 2.0, токенная аутентификация с ограниченными правами
- Подписи вебхуков, валидация подписи SHA-256 HMAC
- Только HTTPS, все API-эндпоинты требуют TLS
- Ограничение scope токенов, запрашивайте минимально необходимые OAuth scope
- Управление секретами, храните токены в переменных окружения или менеджерах секретов
- Соответствие GDPR, используйте Delete Responses API для запросов на удаление данных