موصل Typeform

اربط Typeform بـ Brevo من خلال Tajo لمزامنة إجابات النماذج تلقائيًا، والتقاط العملاء المحتملين من النماذج التحادثية، وتشغيل أتمتة تسويقية بناءً على إرسال الاستبيانات ونتائج الاختبارات.

نظرة عامة

الخاصيةالقيمة
المنصةTypeform
الفئةالنماذج والاستبيانات (مخصص)
تعقيد الإعدادسهل
تكامل رسميلا
البيانات المُزامَنةإجابات، جهات اتصال، أحداث، نماذج
طريقة المصادقةOAuth 2.0 / رمز وصول شخصي

الميزات

  • مزامنة الإجابات الآنية - التقاط تلقائي لإرسال النماذج عبر webhooks
  • إنشاء جهات الاتصال - إنشاء أو تحديث جهات اتصال Brevo من إجابات النماذج
  • تسجيل العملاء المحتملين - استخدام درجات الاختبار وبيانات النموذج لتأهيل العملاء المحتملين
  • الحقول المخفية - تمرير بيانات العملاء عبر الحقول المخفية للنماذج المخصصة
  • التعيين الشرطي - تعيين حقول نماذج مختلفة بناءً على منطق الإجابة
  • دعم نماذج متعددة - ربط typeforms متعددة بقوائم Brevo مختلفة

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

  1. حساب Typeform (خطة Basic أو أعلى للـ webhooks)
  2. رمز وصول شخصي من إعدادات حساب Typeform
  3. حساب Brevo مع وصول إلى API
  4. حساب Tajo مع صلاحيات الموصلات

المصادقة

رمز الوصول الشخصي

Terminal window
# Generate a token at 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 Authorization Flow
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()
});
// Exchange authorization code for access token
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:
# 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_FEEDBACK

نقاط نهاية واجهة البرمجة

نقطة النهايةالطريقةالوصف
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إنشاء/تحديث webhook
https://api.typeform.com/forms/{form_id}/webhooks/{tag}GETالحصول على webhook
https://api.typeform.com/forms/{form_id}/webhooksGETسرد webhooks

أمثلة على الكود

تهيئة الموصل

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]
});
}
}

إعداد Webhooks

// تسجيل webhook لإشعارات الإجابات الآنية
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
})
}
);

التعامل مع أحداث Webhook

app.post('/webhooks/typeform', async (req, res) => {
// التحقق من توقيع webhook
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طلبان/ثانيةإنشاء النماذج وتحديثها
Responses APIطلبان/ثانيةاسترجاع الإجابات
Webhooks APIطلبان/ثانيةإدارة webhooks
جميع نقاط النهاية120 طلب/دقيقةحد معدل عام

تقسيم الإجابات

تُعيد واجهة Responses API 1,000 إجابة كحد أقصى لكل طلب. استخدم معاملات المؤشر before أو after للتقسيم عند استرجاع مجموعات إجابات كبيرة.

استكشاف الأخطاء وإصلاحها

المشكلةالسببالحل
Webhook لم يُستلمWebhook معطَّلفعّل webhook في لوحة Typeform
إجابات مفقودةتطبيق تصفيةتحقق من معاملات since/until وcompleted
خطأ مصادقة 401الرمز منتهيأنشئ رمز وصول شخصي جديد
حد المعدل 429طلبات كثيرة جدًاطبّق تقييد الطلبات
إجابات فارغةحقول اختياريةتعامل مع قيم الإجابات null/undefined

وضع التصحيح

connectors:
typeform:
debug: true
log_level: verbose
log_webhooks: true
log_responses: true

أفضل الممارسات

  1. استخدم webhooks - فضّل webhooks على الاستطلاع لالتقاط الإجابات في الوقت الفعلي
  2. تحقق من التواقيع - تحقق دائمًا من توقيعات webhook للأمان
  3. استخدم الحقول المخفية - املأ بيانات العملاء المعروفة مسبقًا في النماذج
  4. عيّن مراجع الحقول - استخدم قيم ref مستقرة بدلاً من معرّفات الحقول
  5. تعامل مع الإجابات الجزئية - خذ في الحسبان الأسئلة الاختيارية والمتخطاة
  6. إعداد منطق إعادة المحاولة - طبّق معالجة webhook مستقلة عن التكرار

الأمان

  • OAuth 2.0 - مصادقة قائمة على رموز مقيدة النطاق
  • توقيعات Webhook - التحقق من توقيع SHA-256 HMAC
  • HTTPS فقط - تتطلب جميع نقاط نهاية API تشفير TLS
  • تحديد نطاق الرمز - اطلب أدنى نطاقات OAuth المطلوبة
  • إدارة الأسرار - خزّن الرموز في متغيرات البيئة أو مديري الأسرار
  • الامتثال لـ 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

مرحباً! اسألني أي شيء عن الوثائق.