موصل Typeform
اربط Typeform بـ Brevo من خلال Tajo لمزامنة إجابات النماذج تلقائيًا، والتقاط العملاء المحتملين من النماذج التحادثية، وتشغيل أتمتة تسويقية بناءً على إرسال الاستبيانات ونتائج الاختبارات.
نظرة عامة
| الخاصية | القيمة |
|---|---|
| المنصة | Typeform |
| الفئة | النماذج والاستبيانات (مخصص) |
| تعقيد الإعداد | سهل |
| تكامل رسمي | لا |
| البيانات المُزامَنة | إجابات، جهات اتصال، أحداث، نماذج |
| طريقة المصادقة | OAuth 2.0 / رمز وصول شخصي |
الميزات
- مزامنة الإجابات الآنية - التقاط تلقائي لإرسال النماذج عبر webhooks
- إنشاء جهات الاتصال - إنشاء أو تحديث جهات اتصال Brevo من إجابات النماذج
- تسجيل العملاء المحتملين - استخدام درجات الاختبار وبيانات النموذج لتأهيل العملاء المحتملين
- الحقول المخفية - تمرير بيانات العملاء عبر الحقول المخفية للنماذج المخصصة
- التعيين الشرطي - تعيين حقول نماذج مختلفة بناءً على منطق الإجابة
- دعم نماذج متعددة - ربط typeforms متعددة بقوائم Brevo مختلفة
المتطلبات الأساسية
قبل البدء، تأكد من توفر ما يلي:
- حساب Typeform (خطة Basic أو أعلى للـ webhooks)
- رمز وصول شخصي من إعدادات حساب Typeform
- حساب Brevo مع وصول إلى API
- حساب Tajo مع صلاحيات الموصلات
المصادقة
رمز الوصول الشخصي
# 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_FEEDBACKنقاط نهاية واجهة البرمجة
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
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 | إنشاء/تحديث webhook |
https://api.typeform.com/forms/{form_id}/webhooks/{tag} | GET | الحصول على webhook |
https://api.typeform.com/forms/{form_id}/webhooks | GET | سرد 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 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] }); }}إعداد 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أفضل الممارسات
- استخدم webhooks - فضّل webhooks على الاستطلاع لالتقاط الإجابات في الوقت الفعلي
- تحقق من التواقيع - تحقق دائمًا من توقيعات webhook للأمان
- استخدم الحقول المخفية - املأ بيانات العملاء المعروفة مسبقًا في النماذج
- عيّن مراجع الحقول - استخدم قيم
refمستقرة بدلاً من معرّفات الحقول - تعامل مع الإجابات الجزئية - خذ في الحسبان الأسئلة الاختيارية والمتخطاة
- إعداد منطق إعادة المحاولة - طبّق معالجة webhook مستقلة عن التكرار
الأمان
- OAuth 2.0 - مصادقة قائمة على رموز مقيدة النطاق
- توقيعات Webhook - التحقق من توقيع SHA-256 HMAC
- HTTPS فقط - تتطلب جميع نقاط نهاية API تشفير TLS
- تحديد نطاق الرمز - اطلب أدنى نطاقات OAuth المطلوبة
- إدارة الأسرار - خزّن الرموز في متغيرات البيئة أو مديري الأسرار
- الامتثال لـ GDPR - استخدم Delete Responses API لطلبات محو البيانات