واتساب API بلغة بايثون: إرسال رسالة واتساب من Python بمثال كامل
إرسال رسالة واتساب بلغة بايثون عبر API الرسمي: دالة واحدة بمكتبة requests، وإرسال قالب معتمد ومعرفة حالته، وسكربت يرسل تذكيرات الدفع من ملف CSV، والأخطاء الشائعة.
في هذه الصفحة 7
الإجابة المختصرة
لإرسال رسالة واتساب من بايثون استخدم مكتبة requests ونداءً واحدًا إلى POST https://app.arabybot.com/api/v1/messages/template بمفتاحك في ترويسة Authorization، وجسمه رقم المستلم بكود الدولة واسم القالب المعتمد ومتغيراته. هذا هو الطريق الرسمي عبر واجهة واتساب للأعمال؛ أما المكتبات التي تتحكم في واتساب ويب فغير رسمية وتعرّض الرقم للحظر.
يُسأل عنها أيضًا: «whatsapp api python» · «ارسال رسالة واتساب بايثون» · «سكربت بايثون يرسل واتساب» · «ارسال واتساب من ملف اكسل بايثون»
الطريق الرسمي لا أتمتة واتساب ويب
أول ما يظهر لمن يبحث عن إرسال واتساب من بايثون مكتبات تفتح واتساب ويب في متصفح وتكتب الرسالة كأنها إنسان. تعمل في التجربة، ثم تكلّفك الرقم: واتساب يقيّد الحسابات التي يبدو نشاطها آليًّا أو جماعيًّا ثم يحظرها. الكود هنا يرسل عبر واجهة واتساب للأعمال الرسمية من رقمك المتصل بعربي بوت، بقوالب معتمدة من ميتا.
مدة حظر الواتساب وأنواعه · برامج الإرسال الجماعي: أيها لا يحظر رقمك؟
ما تحتاجه
- رقم واتساب متصل بعربي بوت وعليه قالب معتمد واحد على الأقل.
- باقة تشمل «أدوات المطورين»: «WhatsApp Pro» أو «WhatsApp Premium» أو «Complete Plan» أو «Ultimate Plan».
- مفتاح من صفحة «أدوات المطورين»، يبدأ بـ
abk_ويظهر مرة واحدة. ضعه في متغير البيئةARABYBOT_API_KEY.
دالة واحدة بمكتبة requests
# pip install requests
import os
import requests
BASE = "https://app.arabybot.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["ARABYBOT_API_KEY"]}
def arabybot(method, path, body=None):
"""One helper for every call. Returns the API's JSON answer as a dict."""
try:
res = requests.request(method, f"{BASE}/{path}", headers=HEADERS, json=body, timeout=20)
return res.json()
except (requests.RequestException, ValueError):
return {"success": False, "error_code": "NETWORK"}
me = arabybot("GET", "me") # does the key work, and which numbers does it send from?
templates = arabybot("GET", "templates") # each template comes with a ready body in "example" المعامل json= يحوّل القاموس إلى JSON ويضبط ترويسة المحتوى، فلا تحتاج إلى json.dumps. والمهلة ضرورية: بدونها ينتظر السكربت إلى ما لا نهاية إن انقطع الاتصال.
إرسال قالب ومعرفة حالته
sent = arabybot("POST", "messages/template", {
"to": "201012345678", # with the country code
"template": "order_shipped",
"language": "ar",
"variables": ["Ahmed", "1042"], # the template's {{1}}, {{2}} in order
"reference": "order-1042-shipped", # the same reference is never sent twice
})
if sent.get("success"):
message_id = sent["id"] # "accepted", or "queued": it goes out by itself
elif sent.get("error_code") in ("TRY_AGAIN", "NETWORK"):
retry_later(order_id) # same request, same reference
elif sent.get("error_code") == "UNCERTAIN":
check_later(sent.get("id")) # ask GET messages/{id} before sending again
else:
print(sent.get("error_code"), sent.get("message_en"))
status = arabybot("GET", "messages/512") # queued · accepted · sent · delivered · read · failed الرد الناجح يحمل status بإحدى قيمتين: accepted أي قبلتها واتساب، أو queued أي تنتظر دورها وتُرسل وحدها. وفي الحالتين احفظ id لتسأل به عن التسليم لاحقًا.
كل الحقول ورموز الرفض والحدود في مرجع واجهة الإرسال
مثال عملي: تذكير بالدفع من ملف CSV
أكثر ما يُطلب من بايثون سكربت يقرأ قائمة ويرسل لكل صف رسالته. المرجع المبني من رقم الفاتورة يجعل تشغيل السكربت مرتين آمنًا: من وصلته الرسالة لا تصله ثانية.
import csv
import time
with open("customers.csv", newline="", encoding="utf-8") as f:
for row in csv.DictReader(f): # columns: phone, name, invoice
sent = arabybot("POST", "messages/template", {
"to": row["phone"],
"template": "payment_reminder",
"language": "ar",
"variables": [row["name"], row["invoice"]],
"reference": "reminder-" + row["invoice"],
})
if not sent.get("success"):
print(row["phone"], sent.get("error_code"), sent.get("message_en"))
time.sleep(0.2) # five a second is plenty; the queue paces the rest الواجهة تقبل ٦٠٠ طلب في الدقيقة لكل مفتاح، وما يزيد على سرعة رقمك عند واتساب ينتظر في الطابور ولا يضيع. ومن أوقف الرسائل التسويقية من واتساب يعود عنه الرمز OPTED_OUT إن كان القالب تسويقيًّا، فاحذفه من قائمتك.
أخطاء شائعة في بايثون
| الخطأ | ما يحدث | الحل |
|---|---|---|
| المفتاح داخل السكربت | يتسرب مع أول مشاركة للملف | os.environ |
data= بدل json= | القوائم داخل variables لا تصل كما كتبتها | json=body |
| قراءة الملف بترميز غير UTF-8 | الأسماء العربية تصل مشوّهة | encoding="utf-8" |
| أرقام بصفر في أولها بلا كود الدولة | BAD_PHONE | خزّنها بالصيغة الدولية |
| إعادة كل رفض | طلبات بلا فائدة | أعد TRY_AGAIN وحده |
الشرح نفسه بلغة PHP · ومن Node.js · واجهة رموز التحقق OTP
الأسئلة الشائعة
هل أستخدم مكتبات تتحكم في واتساب ويب من بايثون؟
لا ننصح بها لرقم نشاط. هذه المكتبات تفتح واتساب ويب وتكتب فيه آليًا، وواتساب يعدّ الإرسال الآلي والجماعي من التطبيق مخالفة تنتهي إلى تقييد الحساب أو حظره. الطريق الرسمي واجهة واتساب للأعمال بقوالب معتمدة، وهو ما يفعله الكود في هذه الصفحة.
أي إصدار من بايثون أحتاجه؟
بايثون ٣٫٦ أو أحدث، ومكتبة requests. الكود لا يستخدم شيئًا آخر.
كيف أرسل من Django أو Flask؟
بالدالة نفسها، لكن من مهمة في الخلفية لا من العرض. إن أرسلت من العرض انتظر المستخدم رد الواجهة، وإعادة تحميل الصفحة تعيد الطلب. المهمة تعيد المحاولة وحدها عند TRY_AGAIN، وحقل reference يجعل إعادتها آمنة.
هل أستطيع إرسال صورة أو ملف PDF مع الرسالة؟
نعم إن كان للقالب المعتمد رأس من صورة أو ملف: ضع رابط الملف في حقل header. والملف يجب أن يكون على رابط عام يستطيع واتساب تنزيله.
اقرأ بعدها
جرّب الوكيل قبل أن تدفع شيئًا
الوكيل الذي يرد على عملائك هو نفسه الذي يرد عليك الآن: اسأله من زر الدردشة هنا أو على واتساب. وحسابك مجاني بلا بطاقة ائتمان، والتجربة المجانية على رقمك أو صفحتك تُفعَّل بعد التواصل مع الإدارة على واتساب خدمة العملاء.