Коннектор Typeform

Подключите Typeform к Brevo через Tajo для автоматической синхронизации ответов на формы, захвата лидов из диалоговых форм и запуска маркетинговых автоматизаций на основе отправок опросов и результатов квизов.

Обзор

СвойствоЗначение
ПлатформаTypeform
КатегорияForms & Surveys (Custom)
Сложность настройкиПростая
Официальная интеграцияНет
Синхронизируемые данныеОтветы, контакты, события, формы
Метод аутентификацииOAuth 2.0 / Personal Access Token

Возможности

  • Синхронизация ответов в реальном времени, автоматический захват отправок форм через вебхуки
  • Создание контактов, создание или обновление контактов Brevo из ответов на формы
  • Скоринг лидов, использование результатов квизов и данных форм для квалификации лидов
  • Hidden Fields, передача данных клиентов через скрытые поля для персонализированных форм
  • Условное сопоставление, сопоставление разных полей формы в зависимости от логики ответов
  • Поддержка нескольких форм, подключение нескольких typeform к разным листам Brevo

Предварительные требования

Прежде чем начать, убедитесь, что у вас есть:

  1. Аккаунт Typeform (тариф Basic и выше для вебхуков)
  2. Personal Access Token из настроек аккаунта Typeform
  3. Аккаунт Brevo с доступом к API
  4. Аккаунт Tajo с правами на управление коннекторами

Аутентификация

Personal Access Token

Terminal window
# Сгенерируйте на https://admin.typeform.com/account#/section/tokens
export TYPEFORM_ACCESS_TOKEN=tfp_your_personal_access_token
export TAJO_API_KEY=your_tajo_api_key
export BREVO_API_KEY=your_brevo_api_key

OAuth 2.0

// Поток авторизации OAuth 2.0
const 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/formsGETСписок всех форм
https://api.typeform.com/forms/{form_id}GETПолучить форму
https://api.typeform.com/formsPOSTСоздать форму
https://api.typeform.com/forms/{form_id}PUTОбновить форму
https://api.typeform.com/forms/{form_id}/responsesGETПолучить ответы
https://api.typeform.com/forms/{form_id}/responsesDELETEУдалить ответы
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}/webhooksGETСписок вебхуков

Примеры кода

Инициализация коннектора

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 API
const 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();
// Синхронизация каждого ответа с Brevo
for (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 API2 запроса/секСоздание и обновление форм
Responses API2 запроса/секПолучение ответов
Webhooks API2 запроса/секУправление вебхуками
Все эндпоинты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

Лучшие практики

  1. Используйте вебхуки, предпочтительнее опроса для захвата ответов в реальном времени
  2. Валидируйте подписи, всегда проверяйте подписи вебхуков для безопасности
  3. Используйте Hidden Fields, предзаполняйте известные данные о клиентах в формах
  4. Используйте ссылки на поля, применяйте стабильные значения ref полей вместо ID полей
  5. Обрабатывайте частичные ответы, учитывайте необязательные и пропущенные вопросы
  6. Настройте логику повтора, реализуйте идемпотентную обработку вебхуков

Безопасность

  • OAuth 2.0, токенная аутентификация с ограниченными правами
  • Подписи вебхуков, валидация подписи SHA-256 HMAC
  • Только HTTPS, все API-эндпоинты требуют TLS
  • Ограничение scope токенов, запрашивайте минимально необходимые OAuth scope
  • Управление секретами, храните токены в переменных окружения или менеджерах секретов
  • Соответствие GDPR, используйте Delete Responses API для запросов на удаление данных

Связанные ресурсы

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AI-ассистент

Привет! Спрашивайте меня о документации.