ارسال پیامک پایتون؛ از اسکریپت یک‌خطی تا کار زمان‌بندی‌شده‌ای که نیمه‌راه گم نمی‌شود

ارسال پیامک پایتون معمولاً با یک اسکریپت شروع می‌شود: چند خط کد با کتابخانه‌ی requests که به وب‌سرویس شرکت پیامکی درخواست می‌زند. برای یک بار امتحان کافی است، ولی وقتی همان اسکریپت هر شب از روی فایل مشتری‌ها پیام می‌فرستد، سؤال‌های تازه‌ای پیدا می‌شود: اگر وسط کار اینترنت قطع شد چه؟ اگر اسکریپت دوباره اجرا شود، نفر اول دوباره پیام می‌گیرد؟ متن فارسی چند بخش حساب می‌شود؟ این صفحه یک ماژول کوچک برای ارسال پیامک پایتون و یک کار دسته‌ای ساده می‌سازد که به این سؤال‌ها جواب می‌دهد و با تست قابل بررسی است. در پایان هم نشان می‌دهد کدام پیامک‌ها را می‌توان اصلاً نفرستاد.

بروزرسانی: زمان مطالعه حدود ۱۰ دقیقه نوشته‌ی تیم فنی فینگت

ارسال پیامک پایتون؛ چرا اسکریپت اول معمولاً کافی نیست؟

اکثر مثال‌های اینترنتی برای ارسال پیامک پایتون به همین شکل‌اند: requests.post با چند فیلد، چاپ پاسخ و تمام. این کد کار می‌کند و برای آشنایی با وب‌سرویس خوب است. ولی دو عادت در آن هست که در تولید گران تمام می‌شود. اولی نبودن timeout است؛ requests به‌طور پیش‌فرض برای همیشه منتظر می‌ماند، و یک سرویس‌دهنده‌ی کند اسکریپت شما را ساعت‌ها قفل می‌کند. دومی نادیده گرفتن وضعیت پاسخ است؛ اگر شماره اشتباه باشد یا اعتبار تمام شده باشد، اسکریپت بی‌صدا ادامه می‌دهد.

هدف این صفحه ساختن پایه‌ای محکم برای ارسال پیامک پایتون است که در اجرای شبانه هم قابل‌اعتماد بماند. اول یک ماژول با تابع send_sms که مهلت، تلاش دوباره و دسته‌بندی خطا دارد. بعد یک اسکریپت دسته‌ای که از فایل CSV پیام می‌فرستد و هر نتیجه را در یک فایل می‌نویسد تا اجرای دوباره، پیام تکراری نسازد.

مثال‌ها عمداً آدرس و نام فیلد واقعی هیچ شرکتی را نشان نمی‌دهند. قالب دقیق درخواست، نام فیلدها و کد خطاها را فقط مستندات سرویس‌دهنده‌ی شما مشخص می‌کند. ساختار کد را نگه دارید و جزئیات را جایگزین کنید.

اگر ساختار کلی یک وب‌سرویس پیامکی و مفاهیمی مثل خط ارسال را هنوز نمی‌شناسید، ابتدا وب سرویس پیامک و خط خدماتی پیامک را بخوانید.

ماژول پایه؛ کتابخانه requests با مهلت و تلاش دوباره

کتابخانه requests معمولاً انتخاب اول است چون در هر محیط پایتون نصب‌شدنی و آشناست. نکته‌ی مهم این است که یک Session بسازید و دوباره از آن استفاده کنید؛ این کار اتصال‌ها را نگه می‌دارد و در ارسال‌های پشت‌سرهم زمان کمتری می‌گیرد.

در کد زیر خطاها به دو دسته تقسیم شده‌اند: موقت (قطع شبکه، مهلت، وضعیت ۴۲۹ و ۵xx) و دائمی (شماره‌ی نادرست، کلید نامعتبر). فقط دسته‌ی اول دوباره تلاش می‌شود. چون sms api در پایتون هر بار از Session مشترک استفاده می‌کند، در تست هم می‌توانیم فقط همین یک نقطه را جایگزین کنیم.

sms.py؛ ارسال تک‌پیام
import os
import random
import re
import time

import requests

# آدرس، کلید و خط فرستنده را از متغیر محیطی بخوانید؛ مقدارشان در مستندات سرویس‌دهنده‌ی شماست
API_URL = os.environ["SMS_API_URL"]
API_KEY = os.environ["SMS_API_KEY"]
SENDER = os.environ["SMS_SENDER"]

_session = requests.Session()
_FA = str.maketrans("۰۱۲۳۴۵۶۷۸۹", "0123456789")


class SmsError(Exception):
    def __init__(self, message, status=0, retryable=False):
        super().__init__(message)
        self.status = status
        self.retryable = retryable


def normalize_phone(raw):
    """هر ورودی را به قالب 09xxxxxxxxx برمی‌گرداند؛ در غیر این صورت None."""
    digits = re.sub(r"\D+", "", str(raw).translate(_FA))
    if digits.startswith("98"):
        digits = "0" + digits[2:]
    return digits if re.fullmatch(r"09\d{9}", digits) else None


def send_sms(phone, text, retries=2, timeout=8):
    to = normalize_phone(phone)
    if not to:
        raise SmsError("شماره نامعتبر است")
    body = {"sender": SENDER, "to": to, "text": text}
    headers = {"Authorization": "Bearer " + API_KEY}

    for attempt in range(retries + 1):
        try:
            r = _session.post(API_URL, json=body, headers=headers, timeout=timeout)
        except (requests.Timeout, requests.ConnectionError) as exc:
            err = SmsError(type(exc).__name__, retryable=True)
        else:
            if r.ok:
                try:
                    return r.json()
                except ValueError:
                    return {}
            err = SmsError(
                "HTTP %d" % r.status_code,
                status=r.status_code,
                retryable=r.status_code == 429 or r.status_code >= 500,
            )
        if not err.retryable or attempt == retries:
            raise err
        time.sleep(0.4 * 2 ** attempt + random.random() * 0.2)

مقدار timeout را همیشه مشخص کنید. عدد هشت ثانیه برای اتصال و پاسخ معقول است؛ اگر لازم شد می‌توانید یک جفت (اتصال، خواندن) مثل (3, 8) بدهید. در ارسال از وب‌اپ مثل Flask یا FastAPI هم همین تابع قابل استفاده است، ولی پیامک را از مسیر پاسخ به کاربر جدا کنید تا کندی سرویس‌دهنده صفحه‌ی او را نگه ندارد.

ارسال پیامک از csv؛ کاری که وسط راه قطع شود و دوباره ادامه یابد

ارسال پیامک از csv رایج‌ترین کار دسته‌ای است: فایلی با ستون شماره و نام دارید و می‌خواهید به همه یک متن شخصی‌سازی‌شده بفرستید. مشکل ماجرا در اجرای دوباره است. اگر اسکریپت بعد از ارسال به هزار نفر بمیرد و شما از اول اجرایش کنید، آن هزار نفر پیام تکراری می‌گیرند.

راه حل ساده یک «دفتر ثبت» است: هر پیامی که با موفقیت رفت، شماره‌اش در یک فایل جداگانه نوشته می‌شود و اسکریپت هنگام شروع، شماره‌های ثبت‌شده را رد می‌کند. این الگو را اسکریپت‌های مهاجرت داده هم به کار می‌برند و به آن «idempotent» می‌گویند: چند بار اجرا کنید، اثرش یک بار است.

run_batch.py؛ ارسال از CSV با دفتر ثبت
import csv
import sys
from pathlib import Path

from sms import SmsError, normalize_phone, send_sms

TEMPLATE = "{name} عزیز، سفارش شما آماده‌ی تحویل است."  # نمونه؛ متن واقعی خودتان
LEDGER = Path("sent.log")


def load_done():
    return set(LEDGER.read_text(encoding="utf-8").split()) if LEDGER.exists() else set()


def main(path):
    done = load_done()
    sent = skipped = failed = 0
    with open(path, newline="", encoding="utf-8") as src, open(LEDGER, "a", encoding="utf-8") as ledger:
        for row in csv.DictReader(src):
            phone = normalize_phone(row.get("phone", ""))
            if not phone:
                failed += 1
                print("شماره نامعتبر:", row.get("phone"))
                continue
            if phone in done:
                skipped += 1
                continue
            try:
                send_sms(phone, TEMPLATE.format(name=row.get("name", "").strip() or "کاربر"))
            except SmsError as exc:
                failed += 1
                print("خطا برای", phone[:4] + "***" + phone[-2:], exc)
                continue
            ledger.write(phone + "\n")
            ledger.flush()  # حتی با از کار افتادن بعدی اسکریپت، این شماره ثبت شده می‌ماند
            sent += 1
    print("ارسال‌شده:", sent, "ردشده:", skipped, "ناموفق:", failed)


if __name__ == "__main__":
    main(sys.argv[1])

دقت کنید شماره‌ی کامل کاربران در خروجی خطا چاپ نمی‌شود و فقط ابتدا و انتهای آن می‌آید. فایل دفتر ثبت هم داده‌ی شخصی است؛ آن را در مخزن کد نگذارید. اگر پیام‌ها تبلیغاتی‌اند، پیش از اجرا حتماً قوانین ارسال پیامک تبلیغاتی و لغو ۱۱ را بررسی کنید و گیرنده‌های منصرف را از فایل حذف کنید. ارسال از اکسل و فایل‌های ساده بدون کدنویسی هم در ارسال پیامک از اکسل شرح داده شده است.

سرعت بیشتر؛ ارسال همزمان با ThreadPoolExecutor

حلقه‌ی بالا پیام‌ها را یکی‌یکی می‌فرستد. اگر هر درخواست نیم ثانیه طول بکشد، برای ده هزار پیام حدود یک ساعت و نیم زمان لازم است. چون کار اصلی اینجا «انتظار برای شبکه» است، چند رشته کمک می‌کند. ماژول concurrent.futures در کتابخانه‌ی استاندارد یک ThreadPoolExecutor دارد که کار را با چند رشته‌ی ثابت پخش می‌کند، و Session کتابخانه‌ی requests برای این‌کار مناسب است.

دو احتیاط هست. اول اینکه تعداد رشته‌ها را کم نگه دارید، مثلاً پنج یا ده، و سقف درخواست در ثانیه‌ی سرویس‌دهنده را رعایت کنید؛ تعداد زیاد فقط ۴۲۹ می‌سازد. دوم اینکه نوشتن در دفتر ثبت را در رشته‌ی اصلی انجام دهید، نه داخل کارگرها، تا دو رشته هم‌زمان در یک فایل ننویسند. الگوی ساده این است که send_sms را به executor.submit بدهید و نتیجه‌ها را با as_completed بخوانید و آنجا دفتر را به‌روز کنید.

اگر برنامه‌ی شما از قبل با asyncio و کتابخانه‌ای مثل httpx نوشته شده، همین ساختار را با یک semaphore برای سقف همزمانی بنویسید. منطق ماژول، یعنی مهلت، دسته‌بندی خطا و تلاش دوباره، یکسان می‌ماند و فقط ابزار ارسال عوض می‌شود.

پیام را قبل از ارسال بسنجید

پیش از اینکه هزار پیام را بفرستید، با یک اجرای آزمایشی روی ده شماره‌ی خودتان و همکارانتان مطمئن شوید متن درست رندر می‌شود، نام‌های خالی جایگزین دارند و پیوندها کار می‌کنند. اجرای اشتباه روی کل فهرست بازگشت ندارد.

متن فارسی؛ هر پیامک چند بخش حساب می‌شود؟

یک نکته‌ی هزینه‌ای که در نمونه‌کد نمی‌آید ولی روی قبض اثر دارد: طول پیام. پیام‌هایی که نویسه‌ی غیرلاتین دارند، از جمله فارسی، معمولاً با رمزگذاری یونیکد فرستاده می‌شوند و هر بخش آنها کوتاه‌تر از پیام لاتین است؛ رقم رایج برای یک بخش حدود ۷۰ نویسه است و بعد از آن پیام به چند بخش تقسیم و بخش‌ها جداگانه حساب می‌شوند. این عدد را مستندات و قرارداد سرویس‌دهنده‌ی خودتان دقیق می‌کند، پس آن را مطابق مقررات و قیمت‌گذاری همان شرکت حساب کنید.

نتیجه‌ی عملی ساده است: متن را کوتاه بنویسید، تکرار و شعار اضافه نکنید و اگر یک نویسه‌ی خاص مثل یک ایموجی در انتهای پیام باشد، ممکن است کل پیام را به بخش‌های بیشتری تبدیل کند. در اسکریپت هم می‌توانید یک تابع کوچک بنویسید که طول متن رندر‌شده را بسنجد و برای پیام‌های بلندتر از حد دلخواه شما هشدار بدهد.

برای یادآوری، هزینه‌ی هر بخش پیام در ضرب‌ شدن با تعداد گیرنده‌ها، همان چیزی است که در هزینه پیامک سایت و قیمت پنل پیامکی به آن پرداخته‌ایم. یک کاراکتر اضافه در پیامی که برای ده هزار نفر می‌رود، می‌تواند هزینه را دوبرابر کند.

اشتباه‌های رایج در اسکریپت پیامک

این چهار اشتباه را در بسیاری از اسکریپت‌های کوچک می‌بینیم و هر چهار با چند خط کد قابل‌پیشگیری‌اند.

کلید در خود فایل کد

کلیدی که داخل متن اسکریپت نوشته شود، با اولین commit یا اشتراک‌گذاری فایل لو می‌رود. از os.environ یا یک مدیر رازها بخوانید و فایل env را در gitignore بگذارید.

بلعیدن خطا با except خالی

نوشتن except Exception و pass همه‌چیز را ساکت می‌کند. بنویسید چه شماره‌ای و چرا شکست خورد، ولی بدون چاپ کلید و متن کامل پیام.

اجرای دوباره‌ی کور

بدون دفتر ثبت یا ستون وضعیت در پایگاه‌داده، هر اجرای دوباره یعنی پیام تکراری و هزینه‌ی تکراری برای مشتری و شما.

ارسال در ساعت نامناسب

اسکریپت زمان‌بندی‌شده‌ای که ساعت سه بامداد پیام تبلیغاتی می‌فرستد، حتی اگر درست کار کند، به اعتبار شما لطمه می‌زند. ساعت اجرا را از قوانین و عرف رایج در بهترین زمان ارسال پیامک بگیرید.

تست بدون پیامک واقعی؛ جایگزین‌کردن Session

برای تست یک ماژول پیامک لازم نیست چیزی ارسال شود. چون همه‌ی درخواست‌های ما از _session.post عبور می‌کنند، کافی است همان را در تست با یک شیء ساختگی عوض کنید و پاسخ‌ها را کنترل کنید. کتابخانه‌ی unittest.mock داخل پایتون همین کار را می‌کند و بسته‌ی اضافه نمی‌خواهد.

تست زیر دو چیز را بررسی می‌کند: بعد از وضعیت ۵۰۳ یک بار دیگر تلاش می‌شود، و برای وضعیت ۴۰۱ هیچ تلاش دوباره‌ای نمی‌شود. تابع sleep هم جایگزین شده تا تست‌ها منتظر نمانند.

test_sms.py؛ تقلید پاسخ سرویس‌دهنده
import os
import unittest
from unittest.mock import MagicMock, patch

os.environ.update(SMS_API_URL="http://sms.invalid/send", SMS_API_KEY="k", SMS_SENDER="1000")
import sms  # noqa: E402  (متغیرها باید پیش از import مقدار بگیرند)


def fake(status):
    r = MagicMock()
    r.status_code = status
    r.ok = status < 400
    r.json.return_value = {"id": "t1"}
    return r


class SendSmsTest(unittest.TestCase):
    @patch("sms.time.sleep")
    @patch.object(sms._session, "post")
    def test_retries_on_503(self, post, _sleep):
        post.side_effect = [fake(503), fake(200)]
        self.assertEqual(sms.send_sms("09120000000", "نمونه")["id"], "t1")
        self.assertEqual(post.call_count, 2)

    @patch("sms.time.sleep")
    @patch.object(sms._session, "post")
    def test_no_retry_on_401(self, post, _sleep):
        post.return_value = fake(401)
        with self.assertRaises(sms.SmsError):
            sms.send_sms("09120000000", "نمونه")
        self.assertEqual(post.call_count, 1)

    def test_bad_phone(self):
        with self.assertRaises(sms.SmsError):
            sms.send_sms("123", "نمونه")


if __name__ == "__main__":
    unittest.main()

با دستور python -m unittest اجرایش کنید. اگر pytest دارید، همین فایل بدون تغییر کار می‌کند. چنین تست‌هایی چند میلی‌ثانیه‌اند و هر وقت تابع ارسال را دست بزنید، جلوی برگشت خطاهای قدیمی را می‌گیرند.

کدام پیام‌ها را اصلاً نباید با پیامک فرستاد؟

ارسال پیامک با python ساده است و برای همین وسوسه‌انگیز: هر اتفاقی را می‌شود یک پیامک کرد. اما هر پیامک هزینه دارد، ممکن است فیلتر شود و کاربر هم از انبوه پیام‌های تکراری خسته می‌شود. پیش از اینکه سرویس تازه‌ای را به send_sms وصل کنید، بپرسید گیرنده این پیام را در چه کانالی بهتر می‌پذیرد.

پیامک وقتی لازم است که فقط شماره‌ی کاربر را دارید یا او اپ و وب‌سایت شما را باز نمی‌کند: تأیید اولیه‌ی شماره، هشدار فوری و مواردی که قانوناً یا قراردادی به پیامک نیاز دارند. در عوض، ورود موفق، تأیید سفارش، وضعیت ارسال و یادآوری‌های روزمره برای کسی که اپ را نصب کرده، با اعلان رایگان هم رسانده می‌شود. مقایسه‌ی این دو راه در پیامک یا نوتیفیکیشن آمده است.

فینگت و کم‌کردن پیامک ورود

فینگت سرویس‌دهنده‌ی پیامک نیست؛ خط، پنل یا بسته‌ی پیامکی نمی‌فروشد و اسکریپت‌های بالا برای خطی‌اند که خودتان از شرکت پیامکی می‌گیرید. نقش فینگت کاهش نیاز به پیامک ورود است.

در ورود با فینگت، کاربر دارنده‌ی اپ، ورود را در گوشی تأیید می‌کند و مرورگرش با یک کد کوتاه‌عمر به آدرس بازگشت سایت شما برمی‌گردد. سرور شما آن کد را با یک درخواست POST تبدیل به نام، شماره‌ی تأییدشده و یک شناسه‌ی ثابت می‌کند. نه کدی ساخته می‌شود، نه پیامکی می‌رود و نه حساب هزینه‌ی هر ورود لازم است. اپ فعلاً برای اندروید است؛ پس ورود پیامکی برای بقیه‌ی کاربران همچنان لازم می‌ماند و گزینه‌ی فینگت کنار آن قرار می‌گیرد.

نمونه‌ی ورود با فینگت در Python با Flask

نمونه‌ی زیر با Flask است و SITE_ID و کلید API را از متغیر محیطی می‌خواند. این دو را از پنل سرویس‌دهندگان فینگت می‌گیرید و همان‌جا آدرس بازگشت را ثبت می‌کنید. state یک مقدار تصادفی است تا بازگشتی که به سایت شما می‌رسد حتماً از درخواستی باشد که خودتان شروع کرده‌اید.

app.py؛ ورود با فینگت
import hmac
import os
import secrets

import requests
from flask import Flask, abort, redirect, request, session

app = Flask(__name__)
app.secret_key = os.environ["FLASK_SECRET"]


@app.get("/login/finget")
def login():
    session["fg_state"] = secrets.token_hex(16)
    return redirect(
        "https://finget.ir/auth?client_id=" + os.environ["FINGET_SITE_ID"] + "&state=" + session["fg_state"]
    )


# همین آدرس را در پنل سرویس‌دهندگان به‌عنوان آدرس بازگشت ثبت کنید
@app.get("/login/finget/callback")
def callback():
    expected = session.pop("fg_state", "")
    if not expected or not hmac.compare_digest(expected, request.args.get("state", "")):
        abort(400)

    r = requests.post(
        "https://finget.ir/api/v1/auth/token",
        json={"code": request.args.get("code", "")},
        headers={"Authorization": "Bearer " + os.environ["FINGET_API_KEY"]},
        timeout=8,
    )
    data = r.json() if r.ok else {}
    user = data.get("user")
    if not user or "id" not in user:
        abort(401)

    # user شامل id، name و phone است؛ data["isNew"] می‌گوید کاربر تازه است
    session.clear()
    session["finget_id"] = user["id"]
    return redirect("/")

این کد هیچ تابع ارسال پیامک، دفتر ثبت یا تلاش دوباره‌ای ندارد، چون پیامکی در کار نیست. مفهوم کلی‌اش را در ورود بدون رمز عبور ببینید و اگر می‌خواهید ورود پیامکی خودتان را در Django بسازید، otp django راهنمای مفصل آن است. برای نصب اپ هم صفحه‌ی دانلود را باز کنید.

پرسش‌های متداول درباره ارسال پیامک پایتون

برای ارسال پیامک پایتون کدام کتابخانه بهتر است؟

برای بیشتر کارها requests کافی و ساده است. اگر برنامه‌ی شما ناهمگام است، httpx یا aiohttp را به همین منطق وصل کنید. مهم‌تر از انتخاب کتابخانه این است که مهلت زمانی بدهید، وضعیت پاسخ را بررسی کنید و خطای موقت را از دائمی جدا کنید.

چطور از ارسال تکراری هنگام اجرای دوباره‌ی اسکریپت جلوگیری کنم؟

یک دفتر ثبت نگه دارید: بعد از هر ارسال موفق، شماره یا شناسه‌ی پیام را در فایل یا جدول بنویسید و هنگام شروع، موارد ثبت‌شده را رد کنید. این کار اجرای دوباره را بی‌خطر می‌کند.

ارسال پیامک از csv با فایل‌های فارسی مشکل رمزگذاری ندارد؟

در ارسال پیامک پایتون از روی فایل، اگر فایل را با UTF-8 ذخیره کنید و هنگام باز کردن encoding را مشخص کنید، مشکلی نیست. فایل‌هایی که اکسل با رمزگذاری قدیمی ذخیره می‌کند را پیش از استفاده به UTF-8 تبدیل کنید و ارقام فارسی شماره را با تابع normalize_phone یکدست کنید.

هر پیامک فارسی چند بخش حساب می‌شود؟

معمولاً متن فارسی با یونیکد فرستاده می‌شود و طول هر بخش کمتر از پیام لاتین است؛ رقم رایج حدود ۷۰ نویسه است. دقیقش را از مستندات و قرارداد سرویس‌دهنده‌ی خودتان بپرسید، چون قیمت‌گذاری هر شرکت فرق می‌کند.

تست را چطور بدون ارسال واقعی بنویسم؟

نقطه‌ای را که درخواست از آن می‌گذرد، در اینجا Session، با unittest.mock عوض کنید و پاسخ‌های ساختگی بدهید: موفق، ۵۰۳، ۴۰۱ و قطع شبکه. هیچ پیامی نمی‌رود و نتیجه‌ی تست هر بار یکسان است.

فینگت می‌تواند جای پنل پیامکی را بگیرد؟

نه. فینگت پیامک نمی‌فروشد و پنل پیامکی ندارد. فقط برای کاربرانی که اپ اندروید دارند، ورود بدون پیامک و اعلان از طریق اپ را فراهم می‌کند و این کار تعداد پیامک‌های لازم شما را کم می‌کند.