موصل Typeform
موصل 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 لطلبات محو البيانات