الرسائل
إرسال رسالة#
يضيف POST /v1/messages رسالة SMS إلى الطابور ويردّ فورًا، ثم يرسلها هاتف خلال ثوانٍ.
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
to | string | نعم | المستلم. يُنصح بصيغة E.164؛ راجع أرقام الهواتف. |
text | string | نعم | نص الرسالة. 6 أجزاء SMS و2000 حرف على الأكثر؛ راجع الحدود. |
requestId | string | لا | معرّفك الخاص لهذه الرسالة، من 1 إلى 100 حرف. إرسال requestId نفسه مرة أخرى لا يُنشئ رسالة ثانية أبدًا. |
ttlSec | integer | لا | عدد الثواني التي يمكن أن تنتظرها الرسالة قبل إرسالها، من 60 إلى 86400. الافتراضي 86400 (24 ساعة). بعدها تصبح expired. |
deviceId | string | لا | الإرسال من هذا الهاتف فقط (معرّف من GET /v1/devices). دونه يمكن لأي هاتف متصل من هواتفك أن يرسل. |
curl -X POST "https://sms.liscosolutions.com/v1/messages" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","text":"Your order #1042 has shipped.","requestId":"order-1042-shipped","ttlSec":3600}'const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
text: "Your order #1042 has shipped.",
requestId: "order-1042-shipped",
ttlSec: 3600
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"text" => "Your order #1042 has shipped.",
"requestId" => "order-1042-shipped",
"ttlSec" => 3600,
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/messages",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"text": "Your order #1042 has shipped.",
"requestId": "order-1042-shipped",
"ttlSec": 3600,
},
)
print(res.status_code, res.json()){
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Your order #1042 has shipped.",
"status": "pending",
"deviceId": null,
"sim": null,
"error": null,
"requestId": "order-1042-shipped",
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-20T10:15:02.481Z"
}الرسالة الجديدة تعيد 201.
منع التكرار عبر requestId#
الشبكات تنقطع، وإعادة المحاولة تحدث. أرسل requestId (مثل رقم طلبك أو حدثك) وأعد المحاولة بحرية: إذا وُجدت في مساحة عملك رسالة بالمعرّف requestId نفسه، تتلقى 200 مع تلك الرسالة بدل رسالة جديدة. ولا يُقارن أي شيء آخر في جسم الطلب.
curl -X POST "https://sms.liscosolutions.com/v1/messages" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","text":"Your order #1042 has shipped.","requestId":"order-1042-shipped","ttlSec":3600}'const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
text: "Your order #1042 has shipped.",
requestId: "order-1042-shipped",
ttlSec: 3600
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"text" => "Your order #1042 has shipped.",
"requestId" => "order-1042-shipped",
"ttlSec" => 3600,
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/messages",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"text": "Your order #1042 has shipped.",
"requestId": "order-1042-shipped",
"ttlSec": 3600,
},
)
print(res.status_code, res.json()){
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Your order #1042 has shipped.",
"status": "sent",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 1,
"error": null,
"requestId": "order-1042-shipped",
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-20T10:15:02.481Z"
}اختيار الهاتف#
مع deviceId لا يأخذ الرسالة إلا ذلك الهاتف، ولا تنتقل إلى هاتف آخر إذا فشل، فتفشل الرسالة أو تنتهي صلاحيتها بدلًا من ذلك. والمعرّف deviceId الذي لا يخص هاتفًا نشطًا في مساحة عملك يتلقى 422 device_not_found.
curl -X POST "https://sms.liscosolutions.com/v1/messages" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","text":"Sent from a chosen phone.","deviceId":"6650e0a1e4b0a1b2c3d4e500"}'const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
text: "Sent from a chosen phone.",
deviceId: "6650e0a1e4b0a1b2c3d4e500"
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"text" => "Sent from a chosen phone.",
"deviceId" => "6650e0a1e4b0a1b2c3d4e500",
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/messages",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"text": "Sent from a chosen phone.",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
},
)
print(res.status_code, res.json()){
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Sent from a chosen phone.",
"status": "pending",
"deviceId": null,
"sim": null,
"error": null,
"requestId": null,
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-21T09:15:02.481Z"
}قراءة رسالة#
يعيد GET /v1/messages/{id} الرسالة مع مسارها الزمني في events. ومعرّف مساحة عمل أخرى يعيد 404 not_found تمامًا كمعرّف غير موجود.
curl "https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"const res = await fetch("https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6", {
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
],
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.get(
"https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
)
print(res.status_code, res.json()){
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Order #1042 is ready for pickup.",
"status": "delivered",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 2,
"error": null,
"requestId": null,
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:14.020Z",
"expiresAt": "2026-11-21T09:15:02.481Z",
"events": [
{
"at": "2026-11-20T09:15:02.481Z",
"type": "queued",
"deviceId": null,
"sim": null,
"detail": null
},
{
"at": "2026-11-20T09:15:03.902Z",
"type": "claimed",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": null,
"detail": null
},
{
"at": "2026-11-20T09:15:08.377Z",
"type": "attempt_failed",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 1,
"detail": "no_service"
},
{
"at": "2026-11-20T09:15:10.651Z",
"type": "sent",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 2,
"detail": null
},
{
"at": "2026-11-20T09:15:14.020Z",
"type": "delivered",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 2,
"detail": null
}
]
}لكل حدث وقته at ونوعه type والهاتف deviceId والشريحة sim المعنيّان (إن وُجدا)، وتفصيل detail مثل رمز خطأ:
type | المعنى |
|---|---|
queued | قبلتها الواجهة. |
claimed | أخذها هاتف. |
attempt_failed | فشل الإرسال على هاتف؛ تعود إلى الطابور لهاتف آخر. |
requeued | أُعيدت إلى الطابور لأن الهاتف الذي يحملها انقطع أو أُلغي ربطه. |
sent | أرسلها الهاتف. |
delivered | أكّدت الشبكة التسليم. |
failed | فشلت كل المحاولات المسموح بها؛ يحمل detail الخطأ. |
expired | انقضت ttlSec قبل الإرسال. |
سرد الرسائل#
يعيد GET /v1/messages رسائل مساحة عملك، الأحدث أولًا.
| معامل الاستعلام | النوع | الوصف |
|---|---|---|
status | string | هذه الحالة فقط: pending أو claimed أو sent أو delivered أو failed أو expired. |
limit | integer | من 1 إلى 100، الافتراضي 20. |
cursor | string | قيمة nextCursor من الصفحة السابقة. |
curl "https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"const res = await fetch("https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2", {
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
],
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.get(
"https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
)
print(res.status_code, res.json()){
"data": [
{
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Order #1042 is ready for pickup.",
"status": "delivered",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 1,
"error": null,
"requestId": null,
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-21T09:15:02.481Z"
},
{
"id": "6650f0a8e4b0a1b2c3d4e5e1",
"to": "+905321234567",
"text": "Your appointment is confirmed.",
"status": "delivered",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 2,
"error": null,
"requestId": null,
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-21T09:15:02.481Z"
}
],
"nextCursor": "6650f0a8e4b0a1b2c3d4e5e1"
}تكون nextCursor مساوية null في الصفحة الأخيرة. وتشمل القائمة كل رسائل مساحة العمل: ما أرسلته عبر الواجهة، ورموز /v1/otp/send، والرسائل التجريبية المرسلة من لوحة التحكم.
كائن الرسالة#
| الحقل | النوع | الوصف |
|---|---|---|
id | string | معرّف الرسالة. |
to | string | المستلم بصيغة E.164. |
text | string | النص. في رسائل رموز التحقق يظهر الرمز دائمًا على شكل •. |
status | string | pending أو claimed أو sent أو delivered أو failed أو expired؛ راجع حالات الرسائل. |
deviceId | string أو null | الهاتف الذي يحملها أو أرسلها. |
sim | integer أو null | خانة الشريحة التي أُرسلت منها (1 أو 2). |
error | string أو null | سبب الفشل أو انتهاء الصلاحية (مثل no_service أو generic_failure أو expired). |
requestId | string أو null | معرّفك requestId إن أرسلته. |
createdAt | string | وقت إضافتها إلى الطابور (ISO 8601، UTC). |
updatedAt | string | آخر تغيير. |
expiresAt | string | وقت انتهاء صلاحيتها إن لم تُرسل قبله. |