نانوپ
مستندات n8n
74+ نود

مستندات n8n

74+ نود مستند شده · ۰ بازدید

📞

تویلیو

Twilio

ارتباطات ابری Twilio: ارسال SMS، تماس صوتی، WhatsApp، تأیید هویت 2FA و سیستم IVR

ارتباطات
متوسط
۰ بازدید
n8n 1.0+

نمای کلی

نود Twilio یکی از مهم‌ترین نودهای n8n برای ارتباطات پیامکی و صوتی است و به خصوص برای کسب‌وکارهایی که بازار بین‌المللی دارند بسیار کاربردی است.

Twilio چیست؟

Twilio یک پلتفرم ارتباطات ابری (Cloud Communications Platform as a Service - CPaaS) است که APIهای قدرتمندی برای SMS، تماس صوتی، ویدیو، WhatsApp، ایمیل و احراز هویت ارائه می‌دهد. بیش از ۱۵۰,۰۰۰ کسب‌وکار در جهان از Twilio استفاده می‌کنند.

قابلیت‌های کلیدی:

  • ارسال و دریافت SMS به بیش از ۱۸۰ کشور
  • ارسال پیام WhatsApp از طریق Twilio API
  • برقراری تماس صوتی برنامه‌ریزی شده
  • ساخت سیستم IVR (پاسخگوی صوتی خودکار) با TwiML
  • احراز هویت دو مرحله‌ای (2FA) با Twilio Verify
  • ارسال کد تأیید از طریق SMS، تماس، ایمیل یا WhatsApp
  • مدیریت شماره‌های تلفن (خرید، جستجو، حذف)
  • ضبط و ذخیره مکالمات تلفنی
  • ارسال MMS (تصویر و ویدیو در پیامک)
  • استفاده از MessagingService برای ارسال انبوه

سرویس‌های اصلی Twilio:

  • Programmable SMS: ارسال و دریافت پیامک
  • Programmable Voice: تماس صوتی و IVR
  • Twilio Verify: احراز هویت و OTP
  • WhatsApp Business API: پیام‌رسانی واتساپ
  • MessagingService: مدیریت ارسال انبوه پیامک
  • Phone Numbers: خرید و مدیریت شماره‌های مجازی

نکته مهم برای بازار ایران:

Twilio به صورت مستقیم از ارسال SMS به شماره‌های ایرانی (+98) پشتیبانی محدود دارد و ممکن است خرید شماره ایرانی امکان‌پذیر نباشد. برای بازار داخلی ایران، از جایگزین‌های محلی با الگوی مشابه استفاده کنید:

  • Kavenegar (kavenegar.com): محبوب‌ترین سرویس SMS ایرانی، API مشابه Twilio
  • SMS.ir: سرویس پیامک ایرانی با پنل ارسال انبوه
  • Ghasedak (ghasedak.me): سرویس پیامک با قابلیت OTP
  • Melipayamak: سرویس پیامک با خطوط اختصاصی

محدودیت‌های API:

  • Rate Limit SMS: حداکثر ۱ پیام در ثانیه به هر شماره (با MessagingService بیشتر)
  • Rate Limit Voice: حداکثر ۱ تماس همزمان به هر شماره
  • SMS Length: حداکثر ۱۶۰۰ کاراکتر (۱۰ segment)
  • MMS Size: حداکثر ۵ مگابایت
  • Verify Code: اعتبار ۱۰ دقیقه‌ای کد تأیید

احراز هویت

احراز هویت Twilio

پیش‌نیازها:

  1. 1ثبت‌نام در Twilio (twilio.com)
  2. 2تأیید ایمیل و شماره تلفن
  3. 3دریافت Account SID و Auth Token
  4. 4خرید یا دریافت شماره Twilio (Trial شامل یک شماره رایگان)

مرحله ۱: ساخت اکانت Twilio

  1. 1به [twilio.com/try-twilio](https://www.twilio.com/try-twilio) بروید
  2. 2اطلاعات خود را وارد کنید (نام، ایمیل، رمز عبور)
  3. 3شماره تلفن خود را تأیید کنید (کد SMS)
  4. 4در صفحه خوش‌آمدگویی، هدف خود را انتخاب کنید

مرحله ۲: دریافت Account SID و Auth Token

  1. 1به Twilio Console بروید (console.twilio.com)
  2. 2در Dashboard اصلی، دو مقدار کلیدی را ببینید:
code
Account SID: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   Auth Token:  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  1. 1Account SID همیشه با AC شروع می‌شود
  2. 2Auth Token را با کلیک روی "Show" مشاهده و کپی کنید

مرحله ۳: دریافت شماره Twilio

  1. 1به Phone Numbers > Manage > Buy a Number بروید
  2. 2کشور و قابلیت‌ها را انتخاب کنید:
  • Voice: قابلیت تماس صوتی
  • SMS: قابلیت ارسال/دریافت پیامک
  • MMS: قابلیت ارسال تصویر
  1. 1شماره مورد نظر را خریداری کنید
  2. 2شماره خریداری شده:
code
+1234567890 (فرمت E.164)

مرحله ۴: تنظیم در n8n

  1. 1به Credentials بروید
  2. 2Twilio API را انتخاب کنید
  3. 3فیلدها:
code
Account SID:  ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   Auth Token:   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  1. 1Test Connection بزنید

تنظیم MessagingService (اختیاری اما توصیه‌شده):

  1. 1به Messaging > Services بروید
  2. 2Create Messaging Service کلیک کنید
  3. 3نام سرویس: مثلاً "My Business SMS"
  4. 4شماره‌های Twilio را به سرویس اضافه کنید
  5. 5Messaging Service SID را یادداشت کنید:
code
MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  1. 1مزایا:
  • ارسال از چند شماره (Auto-routing)
  • مقیاس‌پذیری بالاتر
  • Opt-out خودکار (STOP/START)
  • ارسال انبوه با سرعت بیشتر

تنظیم Twilio Verify (برای OTP/2FA):

  1. 1به Verify > Services بروید
  2. 2Create new کلیک کنید
  3. 3نام سرویس: مثلاً "My App Verification"
  4. 4کانال‌ها را فعال کنید: SMS, Call, Email, WhatsApp
  5. 5Verify Service SID را یادداشت کنید:
code
VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

تنظیم WhatsApp Sandbox (تست):

  1. 1به Messaging > Try it out > Send a WhatsApp message بروید
  2. 2از گوشی خود به شماره نمایش داده شده پیام ارسال کنید:
code
join <sandbox-keyword>
  1. 1پس از اتصال، می‌توانید پیام WhatsApp تست ارسال کنید
  2. 2برای Production: درخواست WhatsApp Business Profile بدهید

Trial Account vs Paid Account:

  • Trial: فقط به شماره‌های تأیید شده ارسال می‌شود، پیام شامل پیشوند "Sent from your Twilio trial account" است
  • Paid: ارسال به هر شماره، بدون محدودیت پیشوند، قابلیت ارسال انبوه

نکات امنیتی:

  • Auth Token را هرگز در frontend یا repository عمومی قرار ندهید
  • از Environment Variables برای ذخیره credentials استفاده کنید
  • API Key و Secret (جایگزین Auth Token) برای امنیت بیشتر بسازید
  • دسترسی‌های Sub-account برای تیم‌ها ایجاد کنید
  • Webhook URL‌ها را با Signature Validation محافظت کنید

عملیات‌های موجود

1

sendSms

ارسال پیام کوتاه (SMS) به شماره تلفن مقصد از طریق Twilio

2

sendWhatsApp

ارسال پیام واتساپ از طریق Twilio WhatsApp API

3

makeCall

برقراری تماس تلفنی و پخش پیام صوتی یا اتصال به IVR

4

getMessage

دریافت جزئیات یک پیام ارسال شده شامل وضعیت تحویل و هزینه

5

listMessages

دریافت لیست پیام‌های ارسال/دریافت شده با فیلتر

6

getCall

دریافت جزئیات یک تماس صوتی شامل مدت، وضعیت و هزینه

7

listCalls

دریافت لیست تماس‌های انجام شده با فیلتر

8

createVoiceResponse

ساخت دستورات TwiML برای سیستم IVR، پخش پیام صوتی، هدایت تماس و منوی تلفنی

9

listPhoneNumbers

مشاهده شماره‌های Twilio خریداری شده در اکانت

10

buyPhoneNumber

جستجو و خرید شماره تلفن جدید از Twilio

11

sendVerificationCode

ارسال کد تأیید OTP از طریق Twilio Verify API برای احراز هویت دو مرحله‌ای

12

checkVerificationCode

بررسی صحت کد تأیید وارد شده توسط کاربر

13

lookupPhoneNumber

دریافت اطلاعات درباره یک شماره تلفن: نوع خط، اپراتور، کشور و اعتبارسنجی فرمت

کاربردهای متداول

1. احراز هویت دو مرحله‌ای (2FA/OTP)

ارسال کد تأیید هنگام ورود یا ثبت‌نام:

code
Webhook (درخواست ورود/ثبت‌نام)
  → Code (اعتبارسنجی شماره)
  → Twilio (sendVerificationCode)
    ServiceSid: VA_YOUR_VERIFY_SERVICE
    To: {{$json.phoneNumber}}
    Channel: sms
    Locale: fa
  → Response ("کد تأیید ارسال شد")

Webhook (ارسال کد توسط کاربر)
  → Twilio (checkVerificationCode)
    ServiceSid: VA_YOUR_VERIFY_SERVICE
    To: {{$json.phoneNumber}}
    Code: {{$json.code}}
  → IF (status === "approved")
    → Database (فعال‌سازی کاربر / ورود)
    → Response ("تأیید موفق")
  → ELSE
    → Response ("کد نامعتبر، مجدداً تلاش کنید")

2. یادآوری نوبت و قرار ملاقات (Appointment Reminder)

ارسال SMS یادآوری ۲۴ ساعت و ۱ ساعت قبل:

code
Schedule (هر ساعت)
  → MySQL (نوبت‌های فردا/ساعت بعد)
  → Loop
    → Twilio (sendSms)
      From: +1234567890
      To: {{$json.patientPhone}}
      Body: "{{$json.patientName}} عزیز، نوبت شما با {{$json.doctorName}} فردا ساعت {{$json.time}} تأیید شده است. برای لغو عدد 0 ارسال کنید."
    → Wait (200ms)  // رعایت Rate Limit
  → MySQL (ثبت لاگ ارسال)

3. اعلان سفارش و وضعیت ارسال

اطلاع‌رسانی مراحل سفارش به مشتری:

code
Webhook (تغییر وضعیت سفارش)
  → Switch (وضعیت)
    Case "confirmed":
      → Twilio (sendSms)
        Body: "سفارش شماره {{$json.orderId}} ثبت شد. مبلغ: {{$json.amount}} تومان. کد پیگیری: {{$json.trackingCode}}"
    Case "shipped":
      → Twilio (sendSms)
        Body: "مرسوله شما ارسال شد. کد رهگیری پست: {{$json.postalCode}}. پیگیری: post.ir"
    Case "delivered":
      → Twilio (sendSms)
        Body: "سفارش تحویل داده شد. از خرید شما ممنونیم! نظرسنجی: {{$json.surveyLink}}"

4. هشدار اضطراری و مانیتورینگ سرور

ارسال SMS فوری هنگام Down شدن سرور:

code
Schedule (هر 3 دقیقه)
  → HTTP Request (health check سرور)
  → IF (status !== 200 OR timeout)
    → Twilio (sendSms)
      To: +ADMIN_PHONE
      Body: "هشدار بحرانی: سرور {{$json.serverName}} از دسترس خارج شد! Status: {{$json.statusCode}}. زمان: {{$now.toFormat('HH:mm:ss')}}"
    → Twilio (makeCall)
      To: +ONCALL_ENGINEER
      Twiml: "<Response><Say language='fa-IR'>هشدار: سرور {{$json.serverName}} قطع شده. لطفاً فوراً بررسی کنید.</Say><Pause length='2'/><Say language='fa-IR'>تکرار: سرور قطع شده.</Say></Response>"
    → Slack (ارسال هشدار به کانال DevOps)

5. سیستم پاسخگوی صوتی خودکار (IVR)

منوی تلفنی برای راهنمایی مشتریان:

code
Twilio Webhook (تماس ورودی)
  → Response (TwiML):
    <Response>
      <Gather numDigits="1" action="/api/ivr/handle" language="fa-IR">
        <Say language="fa-IR">
          به شرکت ما خوش آمدید.
          برای پیگیری سفارش عدد 1 را بزنید.
          برای واحد فروش عدد 2 را بزنید.
          برای پشتیبانی عدد 3 را بزنید.
        </Say>
      </Gather>
      <Say language="fa-IR">ورودی دریافت نشد. خداحافظ.</Say>
    </Response>

Webhook (/api/ivr/handle - Digit=1)
  → Twilio (Gather: "کد سفارش خود را وارد کنید")
  → MySQL (جستجوی سفارش)
  → Twilio (Say: "وضعیت سفارش شما: {{status}}")

Webhook (/api/ivr/handle - Digit=2)
  → Twilio (Dial: +SALES_TEAM_NUMBER)

Webhook (/api/ivr/handle - Digit=3)
  → Twilio (Dial: +SUPPORT_NUMBER)
    → IF (no answer after 30s)
      → Twilio (Record: "پیام خود را بگذارید")

6. بازاریابی پیامکی با Opt-in/Opt-out

ارسال پیامک تبلیغاتی به مشتریان فعال:

code
Schedule (شنبه ساعت 10 صبح)
  → MySQL (مشتریان با sms_consent = true)
  → Loop
    → Twilio (sendSms)
      MessagingServiceSid: MG_YOUR_SERVICE
      To: {{$json.phone}}
      Body: "{{$json.name}} عزیز، تخفیف ویژه! {{$json.discount}}% تخفیف روی همه محصولات تا پایان هفته. کد: {{$json.promoCode}}. لغو اشتراک: STOP ارسال کنید."
    → Wait (100ms)
  → MySQL (ثبت لاگ ارسال)

Webhook (پیام دریافتی SMS)
  → IF (body === "STOP")
    → MySQL (sms_consent = false)
    → Twilio (sendSms)
      Body: "اشتراک شما لغو شد. دیگر پیامکی دریافت نخواهید کرد."

7. تأیید شماره تلفن هنگام ثبت‌نام

اعتبارسنجی شماره واقعی کاربر:

code
Webhook (ثبت‌نام کاربر)
  → Twilio (lookupPhoneNumber)
    PhoneNumber: {{$json.phone}}
    Type: carrier
  → IF (valid && type !== "voip")
    → Twilio (sendVerificationCode)
      Channel: sms
      To: {{$json.phone}}
    → Response ("کد تأیید ارسال شد")
  → ELSE
    → Response ("شماره نامعتبر یا مجازی است")

Webhook (تأیید کد)
  → Twilio (checkVerificationCode)
    Code: {{$json.verifyCode}}
  → IF (approved)
    → Database (ثبت کاربر با phone_verified = true)

8. اعلان پرداخت و فاکتور

اطلاع‌رسانی مالی به مشتریان:

code
Webhook (پرداخت موفق)
  → Twilio (sendSms)
    To: {{$json.customerPhone}}
    Body: "پرداخت تأیید شد. فاکتور: {{$json.invoiceId}}. مبلغ: {{$json.amount}} تومان. کد رهگیری: {{$json.refCode}}"
  → Twilio (sendWhatsApp)
    To: whatsapp:{{$json.customerPhone}}
    Body: "رسید پرداخت شما آماده است."
    MediaUrl: {{$json.invoicePdfUrl}}

Webhook (فاکتور معوقه)
  → Twilio (sendSms)
    Body: "یادآوری: فاکتور شماره {{$json.invoiceId}} به مبلغ {{$json.amount}} تومان منتظر پرداخت است. سررسید: {{$json.dueDate}}"
  → Wait (48 hours)
  → IF (still unpaid)
    → Twilio (makeCall)
      Twiml: "<Response><Say language='fa-IR'>فاکتور معوقه شماره {{$json.invoiceId}} منتظر پرداخت است.</Say></Response>"

9. سیستم اعلان چند کاناله (SMS + WhatsApp + Voice)

ارسال پیام مهم از همه کانال‌ها:

code
Webhook (هشدار حیاتی)
  → Twilio (sendSms)
    To: {{$json.phone}}
    Body: "هشدار فوری: {{$json.alertMessage}}"
  → Wait (5 minutes)
  → IF (not acknowledged)
    → Twilio (sendWhatsApp)
      To: whatsapp:{{$json.phone}}
      Body: "هشدار فوری (تکرار): {{$json.alertMessage}}"
  → Wait (10 minutes)
  → IF (still not acknowledged)
    → Twilio (makeCall)
      Twiml: "<Response><Say language='fa-IR'>{{$json.alertMessage}}</Say><Gather numDigits='1'><Say>برای تأیید عدد 1 را بزنید.</Say></Gather></Response>"
    → IF (digit === "1")
      → Database (acknowledged = true)

10. ردیابی تحویل پیام و گزارش‌گیری

پایش وضعیت ارسال پیامک‌ها:

code
// ارسال با StatusCallback
Twilio (sendSms)
  StatusCallback: "https://your-n8n.com/webhook/sms-status"

// دریافت وضعیت
Webhook (/webhook/sms-status)
  → MySQL (بروزرسانی وضعیت پیام)
    MessageSid: {{$json.MessageSid}}
    Status: {{$json.MessageStatus}}   // queued → sent → delivered/failed/undelivered
    ErrorCode: {{$json.ErrorCode}}

// گزارش روزانه
Schedule (هر شب ساعت 23)
  → MySQL (آمار ارسال روز)
  → Telegram (ارسال گزارش)
    Text: "گزارش SMS امروز:\nارسال: {{$json.total}}\nتحویل: {{$json.delivered}}\nخطا: {{$json.failed}}\nنرخ تحویل: {{$json.rate}}%"

11. ربات پاسخگوی SMS

پاسخ خودکار به پیامک‌های دریافتی:

code
Webhook (SMS دریافتی از Twilio)
  → Switch (بررسی محتوا)
    Case "INFO" یا "راهنما":
      → Twilio (sendSms)
        Body: "خدمات ما:\n1- ثبت سفارش: ORDER ارسال کنید\n2- پیگیری: TRACK [کد سفارش]\n3- پشتیبانی: HELP"
    Case شروع با "TRACK":
      → Code (استخراج کد سفارش)
      → MySQL (جستجوی سفارش)
      → Twilio (sendSms)
        Body: "سفارش {{$json.orderId}}: {{$json.status}}"
    Case "HELP":
      → Twilio (sendSms)
        Body: "تیم پشتیبانی به زودی با شما تماس می‌گیرد."
      → MySQL (ایجاد تیکت پشتیبانی)
    Default:
      → OpenAI (Chat)
      → Twilio (sendSms)
        Body: {{$json.aiResponse}}

12. الگوی مشابه با Kavenegar (بازار ایران)

پیاده‌سازی الگوی Twilio با سرویس ایرانی:

code
// ارسال SMS با Kavenegar (جایگزین Twilio برای ایران)
Webhook (درخواست ارسال)
  → HTTP Request (POST)
    URL: https://api.kavenegar.com/v1/{API-KEY}/sms/send.json
    Body: {
      receptor: "09121234567",
      message: "کد تأیید شما: 123456",
      sender: "10004346"
    }

// ارسال OTP با Kavenegar
Webhook (درخواست کد)
  → Code (تولید کد 6 رقمی)
  → HTTP Request (POST)
    URL: https://api.kavenegar.com/v1/{API-KEY}/verify/lookup.json
    Body: {
      receptor: "09121234567",
      token: "{{$json.otpCode}}",
      template: "verify-template"
    }
  → Redis (ذخیره کد با TTL 5 دقیقه)

نکات حرفه‌ای

نکات حرفه‌ای

  1. 1فرمت شماره E.164: همیشه شماره‌ها را با + و کد کشور وارد کنید:
code
ایران: +989121234567 (نه 09121234567)
   آمریکا: +12025551234
   انگلیس: +447911123456
   امارات: +971501234567

از Twilio Lookup API برای اعتبارسنجی و فرمت‌دهی خودکار استفاده کنید.

  1. 1MessagingService بجای شماره مستقیم: برای ارسال انبوه حتماً از MessagingService استفاده کنید:
code
مزایا:
   - Auto-routing: انتخاب بهترین شماره برای هر مقصد
   - Opt-out: مدیریت خودکار STOP/START
   - Rate Limit بالاتر
   - چند شماره برای یک سرویس
   - Sticky Sender: ارسال از شماره ثابت به هر مخاطب
  1. 1Twilio Verify بجای ارسال دستی OTP: برای احراز هویت از Verify API استفاده کنید:
code
مزایا Verify نسبت به ارسال دستی:
   - تولید خودکار کد امن
   - مدیریت خودکار انقضا (10 دقیقه)
   - جلوگیری از Brute Force (Rate Limit)
   - پشتیبانی از چند کانال (SMS, Call, WhatsApp, Email)
   - داشبورد آنالیتیکس
   - Fraud Guard (تشخیص تقلب)
  1. 1StatusCallback برای ردیابی تحویل: همیشه StatusCallback تنظیم کنید:
code
وضعیت‌های SMS:
   queued → sending → sent → delivered ✓
   queued → sending → sent → undelivered ✗
   queued → failed ✗

   وضعیت‌های Call:
   queued → ringing → in-progress → completed ✓
   queued → ringing → no-answer ✗
   queued → busy ✗
   queued → failed ✗
  1. 1TwiML برای IVR حرفه‌ای: ساختار منوی تلفنی:
xml
<Response>
     <Gather numDigits="1" action="/handle-key" timeout="10">
       <Say language="fa-IR" voice="alice">
         برای فروش عدد 1، برای پشتیبانی عدد 2 را بزنید.
       </Say>
     </Gather>
     <Say language="fa-IR">ورودی دریافت نشد.</Say>
     <Redirect>/welcome</Redirect>
   </Response>

نکته: از voice="alice" یا voice="Polly.XXX" برای کیفیت بهتر استفاده کنید.

  1. 1Error Handling حرفه‌ای برای ارسال انبوه:
code
Loop (لیست مخاطبین)
     → Twilio (sendSms)
       → On Error:
         → IF (21608: Trial limit)
           → Log ("شماره تأیید نشده")
         → IF (21211: Invalid number)
           → MySQL (علامت شماره نامعتبر)
         → IF (30001: Queue overflow)
           → Wait (5 seconds) → Retry
         → IF (21610: Blacklisted)
           → MySQL (opt-out = true)
         → Default:
           → Telegram (هشدار ادمین)
     → Wait (200ms) → Next
  1. 1جایگزین‌های ایرانی Twilio: الگوی یکسان با سرویس‌های داخلی:
code
Kavenegar:
   - API: https://api.kavenegar.com/v1/{API_KEY}/sms/send.json
   - OTP: https://api.kavenegar.com/v1/{API_KEY}/verify/lookup.json
   - وضعیت: https://api.kavenegar.com/v1/{API_KEY}/sms/status.json

   SMS.ir:
   - API: https://api.sms.ir/v1/send
   - OTP: https://api.sms.ir/v1/send/verify
   - از HTTP Request Node در n8n استفاده کنید

   Ghasedak:
   - API: https://api.ghasedak.me/v2/sms/send/simple
   - OTP: https://api.ghasedak.me/v2/verification/send/simple
  1. 1بهینه‌سازی هزینه SMS:
code
- پیام فارسی از UCS-2 استفاده می‌کند: 70 کاراکتر = 1 segment
   - پیام انگلیسی GSM-7: 160 کاراکتر = 1 segment
   - هر segment هزینه جداگانه دارد
   - پیام 150 کاراکتر فارسی = 3 segment!

   نکات صرفه‌جویی:
   - متن را کوتاه نگه دارید (زیر 70 کاراکتر اگر ممکن است)
   - از لینک کوتاه استفاده کنید
   - اطلاعات غیرضروری را حذف کنید
   - ترکیب فارسی/انگلیسی: کل پیام UCS-2 می‌شود
  1. 1ضبط مکالمات (Call Recording):
xml
<Response>
     <Say language="fa-IR">این مکالمه ضبط می‌شود.</Say>
     <Dial record="record-from-ringing-dual" recordingStatusCallback="/recording-done">
       +1234567890
     </Dial>
   </Response>

   // دریافت فایل ضبط شده:
   Webhook (/recording-done)
     → RecordingUrl: {{$json.RecordingUrl}}.mp3
     → Google Drive (آپلود فایل)
     → MySQL (ذخیره لینک ضبط)
  1. 1محدودیت‌های مهم Twilio:
code
SMS:
    - طول پیام: حداکثر 1600 کاراکتر
    - Segment فارسی: 70 کاراکتر (UCS-2)
    - Segment انگلیسی: 160 کاراکتر (GSM-7)
    - MMS: حداکثر 5MB (فقط US/CA)
    - Rate: 1 msg/sec بدون MessagingService

    Voice:
    - TwiML timeout: 15 ثانیه
    - Call duration: بدون محدودیت عملی
    - Recording: حداکثر 2 ساعت
    - Gather digits: حداکثر 65535 رقم
    - Conference: حداکثر 250 شرکت‌کننده

    Verify:
    - کد: اعتبار 10 دقیقه
    - حداکثر 5 تلاش ارسال در 10 دقیقه
    - حداکثر 5 تلاش بررسی کد
    - کانال‌ها: SMS, Call, Email, WhatsApp
  1. 1Sub-account برای مشتریان مختلف: اگر چند پروژه یا مشتری دارید:
code
- برای هر مشتری یک Sub-account بسازید
    - جداسازی هزینه‌ها و گزارش‌ها
    - هر Sub-account SID و Auth Token مجزا دارد
    - Master Account می‌تواند همه را مدیریت کند
  1. 1Webhook Security: محافظت از Webhook URLها:
code
// بررسی امضای Twilio:
    Code Node:
    const crypto = require('crypto');
    const twilioSignature = $headers['x-twilio-signature'];
    const url = 'https://your-n8n.com/webhook/twilio';
    const params = $json; // sorted params
    const authToken = 'YOUR_AUTH_TOKEN';

    const data = url + Object.keys(params).sort()
      .reduce((acc, key) => acc + key + params[key], '');
    const expected = crypto.createHmac('sha1', authToken)
      .update(Buffer.from(data, 'utf-8'))
      .digest('base64');

    if (twilioSignature !== expected) {
      throw new Error('Invalid Twilio signature');
    }
  1. 1Sticky Sender (MessagingService): ارسال همیشگی از یک شماره به هر مخاطب:
  • MessagingService به صورت خودکار شماره فرستنده را برای هر مخاطب ثابت نگه می‌دارد
  • مشتری همیشه از یک شماره پیام دریافت می‌کند
  • اعتماد بیشتر و نرخ پاسخ بالاتر
  1. 1تست با شماره‌های مجیک Twilio: برای تست بدون هزینه:
code
+15005550001: شماره نامعتبر (Invalid)
    +15005550006: شماره معتبر (Valid)
    +15005550009: Cannot route to number
  1. 1Scheduling SMS: ارسال SMS زمان‌بندی شده:
code
Twilio (sendSms)
      MessagingServiceSid: MG_YOUR_SERVICE
      SendAt: "2025-01-15T10:00:00Z"  // حداکثر 7 روز آینده
      ScheduleType: "fixed"

    نکته: فقط با MessagingService قابل استفاده است

رفع مشکلات

خطاهای رایج و راه‌حل‌ها

1. خطای "Authenticate" (401)

علت: Account SID یا Auth Token نامعتبر

راه‌حل

  • Account SID باید با AC شروع شود
  • Auth Token را از Console > Dashboard مجدداً کپی کنید
  • مطمئن شوید از API Key/Secret (SK...) بجای Auth Token اشتباه استفاده نمی‌کنید
  • اکانت Suspended نباشد (بررسی ایمیل)
  • Credential در n8n را بروز کنید

2. خطای "The 'To' number is not a valid phone number" (21211)

علت: فرمت شماره مقصد نادرست

راه‌حل

  • فرمت E.164 استفاده کنید: + + کد کشور + شماره
  • مثال: +989121234567 (نه 09121234567)
  • صفر اول شماره محلی را حذف کنید
  • اطمینان از وجود کد کشور صحیح
  • از Twilio Lookup برای اعتبارسنجی استفاده کنید

3. خطای "The 'From' number is not a valid" (21212)

علت: شماره فرستنده معتبر نیست

راه‌حل

  • شماره باید متعلق به اکانت Twilio شما باشد
  • فرمت E.164: +1234567890
  • برای WhatsApp: whatsapp:+1234567890
  • شماره باید SMS/Voice enabled باشد
  • شماره Trial فقط به شماره‌های تأیید شده ارسال می‌شود
  • MessagingService SID (MG...) هم قابل استفاده است

4. خطای "Permission to send an SMS has not been enabled" (21606)

علت: شماره قابلیت SMS ندارد

راه‌حل

  • مطمئن شوید شماره SMS-enabled است (در Phone Numbers بررسی کنید)
  • برخی شماره‌ها فقط Voice هستند
  • برای ارسال بین‌المللی، Geographic Permissions فعال باشد:
  • Console > Messaging > Settings > Geo Permissions
  • کشور مقصد را فعال کنید

5. خطای "Trial account - not verified number" (21608)

علت: در Trial Account فقط به شماره‌های تأیید شده ارسال می‌شود

راه‌حل

  • شماره مقصد را در Verified Caller IDs اضافه کنید:
  • Console > Phone Numbers > Verified Caller IDs > Add
  • یا اکانت را به Paid ارتقا دهید
  • Trial فقط اجازه ارسال به شماره‌های ثبت شده را دارد

6. خطای "Queue overflow" (30001) / Rate Limit

علت: ارسال بیش از حد مجاز پیامک

راه‌حل

  • محدودیت: ۱ پیام/ثانیه به هر شماره (بدون MessagingService)
  • از MessagingService استفاده کنید (سرعت ارسال بالاتر)
  • بین ارسال‌ها Wait اضافه کنید:
code
Loop → Twilio (sendSms) → Wait (200ms) → Next
  • ارسال انبوه را در بازه زمانی پخش کنید

7. خطای "Message body is required" (21602)

علت: فیلد body خالی است

راه‌حل

  • پیام باید حداقل ۱ کاراکتر داشته باشد
  • فیلد body خالی یا null نباشد
  • از Expression {{}} مطمئن شوید مقدار برمی‌گرداند
  • حداکثر طول: ۱۶۰۰ کاراکتر

8. پیام WhatsApp ارسال نمی‌شود

علت: مشکل تنظیمات WhatsApp

راه‌حل

  • فرمت شماره: whatsapp:+989121234567
  • در Sandbox: مقصد باید قبلاً join ارسال کرده باشد
  • قانون پنجره ۲۴ ساعته: خارج از پنجره فقط Template مجاز است
  • مطمئن شوید WhatsApp Sandbox یا Business Profile فعال است
  • برای Production: تأیید WhatsApp Business Profile لازم است

9. کد تأیید Verify دریافت نمی‌شود

علت: مشکل در Verify Service

راه‌حل

  • Verify Service SID (VA...) را بررسی کنید
  • شماره مقصد فرمت E.164 داشته باشد
  • کد ارسال شده ۱۰ دقیقه اعتبار دارد
  • حداکثر ۵ تلاش ارسال کد در ۱۰ دقیقه
  • کانال (sms/call/whatsapp) در Service فعال باشد
  • بررسی Verify Logs در Console

10. تماس صوتی برقرار نمی‌شود

علت: مشکل Voice یا TwiML

راه‌حل

  • شماره باید Voice-enabled باشد
  • Geographic Permissions برای کشور مقصد فعال باشد
  • TwiML باید XML معتبر باشد:
xml
<Response>
    <Say language="fa-IR">متن پیام</Say>
  </Response>
  • URL تأخیر TwiML نباید بیش از ۱۵ ثانیه باشد
  • تماس‌های بین‌المللی ممکن است توسط اپراتور مقصد مسدود شوند

11. خطای Encoding فارسی در SMS

علت: کاراکترهای فارسی بیش از حد segment مصرف می‌کنند

راه‌حل

  • SMS فارسی از UCS-2 encoding استفاده می‌کند
  • هر segment فارسی: ۷۰ کاراکتر (بجای ۱۶۰ لاتین)
  • پیام ۱۴۰ کاراکتری فارسی = ۲ segment = هزینه دوبرابر
  • متن پیام را کوتاه نگه دارید
  • از لینک کوتاه بجای URL بلند استفاده کنید
اشتراک‌گذاری:

آیا این مستندات مفید بود؟