SMS: الإرسال
إرسال رسالة أو أكثر عبر SMS باستخدام واجهة برمجة تطبيقات Mersal.
3 دقيقة قراءة
أرسل رسالة SMS واحدة أو أكثر في طلب واحد. مرّر عدة عناصر في مصفوفة contact لتنفيذ إرسال جماعي، مع إمكانية جدولة كل رسالة لوقت لاحق أو استهداف بوابة إرسال محددة.
النقطة الطرفية
POSThttps://mersal.it/api/sms/send
المصادقة
يتطلب مفتاح API الشخصي الخاص بك عبر ترويسة Api-key (أو بديل api_key في معامل الرابط/نص الطلب). راجع المصادقة.
معاملات الطلب
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
contact | array | نعم | مصفوفة المستلمين. يجب أن تحتوي على عنصر واحد على الأقل. |
contact.*.number | string | نعم | رقم هاتف المستلم. |
contact.*.message | string | نعم | نص رسالة SMS. |
contact.*.gateway_identifier | string | لا | معرّف UID لبوابة SMS محددة للإرسال عبرها. احذف هذا الحقل لاستخدام بوابة SMS الافتراضية/النشطة في حسابك. مرّر معرّف بوابة محدد لفرض استخدامها — مثلاً لتوجيه الرسالة عبر Android SIM Gateway بدلاً من مزود SMS API. |
contact.*.schedule_at | string | لا | جدولة التسليم لوقت لاحق، بصيغة Y-m-d H:i:s. احذف هذا الحقل للإرسال الفوري. |
مثال على الطلب
curl -X POST https://mersal.it/api/sms/send \
-H "Api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact": [
{
"number": "+201234567890",
"message": "Your order has shipped!"
},
{
"number": "+201098765432",
"message": "Reminder: your appointment is tomorrow at 10am.",
"schedule_at": "2026-08-01 10:00:00"
}
]
}'<?php
$response = Http::withHeaders([
'Api-key' => 'YOUR_API_KEY',
'Content-Type' => 'application/json',
])->post('https://mersal.it/api/sms/send', [
'contact' => [
[
'number' => '+201234567890',
'message' => 'Your order has shipped!',
],
[
'number' => '+201098765432',
'message' => 'Reminder: your appointment is tomorrow at 10am.',
'schedule_at' => '2026-08-01 10:00:00',
],
],
]);
$data = $response->json();<?php
$payload = [
'contact' => [
[
'number' => '+201234567890',
'message' => 'Your order has shipped!',
],
],
];
$ch = curl_init('https://mersal.it/api/sms/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Api-key: YOUR_API_KEY',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);const response = await fetch("https://mersal.it/api/sms/send", {
method: "POST",
headers: {
"Api-key": process.env.MERSAL_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
contact: [
{ number: "+201234567890", message: "Your order has shipped!" },
{
number: "+201098765432",
message: "Reminder: your appointment is tomorrow at 10am.",
schedule_at: "2026-08-01 10:00:00",
},
],
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://mersal.it/api/sms/send",
headers={"Api-key": os.environ["MERSAL_API_KEY"]},
json={
"contact": [
{"number": "+201234567890", "message": "Your order has shipped!"},
{
"number": "+201098765432",
"message": "Reminder: your appointment is tomorrow at 10am.",
"schedule_at": "2026-08-01 10:00:00",
},
]
},
)
data = response.json()مثال على الاستجابة
{
"success": true,
"message": "SMS queued successfully",
"data": {
"contact": [
{
"number": "+201234567890",
"status": "queued"
},
{
"number": "+201098765432",
"status": "scheduled"
}
]
}
}عند فشل التحقق من صحة البيانات، تُرجع Mersal الحالة 422:
{
"success": false,
"message": "Validation failed",
"errors": {
"contact.0.number": ["The contact.0.number field is required."]
}
}جدولة الرسائل
حقل schedule_at يقبل التوقيت بصيغة Y-m-d H:i:s بتوقيت حسابك. الرسائل المجدولة تظهر بحالة scheduled في الاستجابة وتقدر تتابعها من لوحة التحكم أو عبر GET /api/get/sms.
الأخطاء
أكثر حالات الفشل شيوعًا هي مفتاح API مفقود أو غير صالح، أو اشتراك منتهي الصلاحية، أو خطأ تحقق 422 في مصفوفة contact. راجع الأخطاء ورموز الحالة للمرجع الكامل.
هل ساعدتك هذه الصفحة؟
