تخطَّ إلى المحتوى

جهات الاتصال

جهة الاتصال شخص ترسل إليه الحملات: واحدة لكل رقم هاتف في كل مؤسسة، مع الأسماء والوسوم والحقول المخصصة والموافقة وحالة إلغاء الاشتراك. تُحفظ الأرقام مشفرة. أضف جهات الاتصال إلى مجموعات أو استورد ملف CSV.

الحقل النوع الوصف
id string con_…
phone string E.164.
country string أو null دولة الرقم بصيغة ISO 3166-1 alpha-2.
firstName وlastName وemail string أو null
timeZone string أو null منطقة IANA. تتقدم على منطقة الرقم في ساعات هدوء الحملات.
tags string[] مرتبة.
customFields object مفاتيح مسطحة بصيغة snake_case بقيم نصية أو رقمية أو منطقية أو null، وتُستخدم كـ {{custom.<key>}}.
consent object أو null { source, at, text }: أين ومتى وافق الشخص.
optedOut object أو null { at, source }. قيمة source هي sms_keyword (رد بكلمة STOP) أو api أو web. تتخطى الحملات جهات الاتصال الملغية للاشتراك.
groups object[] { id, name } لكل مجموعة تنتمي إليها جهة الاتصال.
createdAt وupdatedAt string
POST/v1/contactscontacts:manage

يعيد 201 مع جهة الاتصال. يدعم Idempotency-Key.

حقل المحتوى النوع إلزامي الوصف القيود
phone string نعم الرقم. E.164، وجهة اتصال واحدة لكل رقم.
firstName string لا حتى 120 حرفا.
lastName string لا حتى 120 حرفا.
email string لا بريد صالح حتى 254 حرفا.
timeZone string لا منطقة IANA مثل Africa/Cairo.
tags string[] لا حتى 20، كل منها من 1 إلى 40 حرفا من الأحرف والأرقام والمسافات و_ و-، ويبدأ بحرف أو رقم.
customFields object لا حتى 50 مفتاحا بصيغة snake_case و4 KB، والقيم نصوص حتى 500 حرف أو أرقام أو قيم منطقية أو null، دون تداخل.
consent object لا source (web_form أو import أو api أو in_person أو paper أو sms_keyword أو other)، وat (ISO 8601، الافتراضي الآن)، وtext (حتى 500).
groupIds string[] لا أضفها إلى هذه المجموعات. حتى 20.
نافذة طرفيّة
curl https://api.smsfabric.com/v1/contacts \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+201001234567",
"firstName": "Mona",
"lastName": "Hassan",
"tags": ["vip", "cairo"],
"customFields": { "branch": "Nasr City", "loyalty_points": 1250 },
"consent": { "source": "web_form", "text": "I agree to receive offers by SMS." },
"groupIds": ["grp_t6w9z2c5f8i1l4o7r0u3x6a9"]
}'
{
"id": "con_a8d1g4j7m0p3s6v9y2b5e8h1",
"phone": "+201001234567",
"country": "EG",
"firstName": "Mona",
"lastName": "Hassan",
"email": null,
"timeZone": null,
"tags": ["cairo", "vip"],
"customFields": { "branch": "Nasr City", "loyalty_points": 1250 },
"consent": { "source": "web_form", "at": "2026-11-19T10:40:00.000Z", "text": "I agree to receive offers by SMS." },
"optedOut": null,
"groups": [{ "id": "grp_t6w9z2c5f8i1l4o7r0u3x6a9", "name": "Newsletter" }],
"createdAt": "2026-11-19T10:40:00.000Z",
"updatedAt": "2026-11-19T10:40:00.000Z"
}
الخطأ متى
409 contact_exists توجد جهة اتصال بهذا الرقم.
404 not_found أحد عناصر groupIds لا يتبع مؤسستك.
400 validation_failed حقل غير صالح.
GET/v1/contactscontacts:read

من الأحدث إلى الأقدم، مقسمة إلى صفحات.

الاستعلام النوع الوصف
q string رقم كامل (تطابق تام، بأي صيغة تبدأ بـ +)، أو آخر 4 أرقام، أو نص يرد في الاسم الأول أو اسم العائلة أو البريد.
tag string جهات الاتصال التي تحمل هذا الوسم.
groupId string جهات الاتصال في هذه المجموعة.
optedOut string true أو false.
limit integer من 1 إلى 200، والافتراضي 50.
cursor string nextCursor من الصفحة السابقة.
نافذة طرفيّة
curl "https://api.smsfabric.com/v1/contacts?tag=vip&optedOut=false&limit=100" \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

يعيد { "data": [Contact, …], "nextCursor": "…" | null }.

GET/v1/contacts/tagscontacts:read

الوسوم المستخدمة وعدد جهات الاتصال لكل منها، الأكثر استخداما أولا، بحد أقصى 200. لا يفرق الوسم بين الأحرف الكبيرة والصغيرة.

الاستعلام النوع الوصف
q string بداية الوسم.
نافذة طرفيّة
curl "https://api.smsfabric.com/v1/contacts/tags?q=ca" \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{ "data": [{ "tag": "cairo", "contacts": 1840 }, { "tag": "campaign-2025", "contacts": 312 }] }

تصدير جهات الاتصال بصيغة CSV

Section titled “تصدير جهات الاتصال بصيغة CSV”
GET/v1/contacts/export.csvcontacts:read, logs:export

يبث جهات الاتصال بصيغة text/csv بالأعمدة id, phone, firstName, lastName, email, country, timeZone, tags, groups, customFields, consentSource, consentAt, optedOutAt, createdAt. تُحمى الخلايا من حقن المعادلات. يحتاج الصلاحيتين معا، ويُحتسب ضمن حد العمليات المجمعة (20 في الدقيقة)، ويُسجل في التدقيق باسم contacts.exported مع عدد الصفوف.

الاستعلام النوع الوصف
tag string فقط جهات الاتصال التي تحمل هذا الوسم.
groupId string فقط جهات الاتصال في هذه المجموعة.
نافذة طرفيّة
curl "https://api.smsfabric.com/v1/contacts/export.csv?groupId=grp_t6w9z2c5f8i1l4o7r0u3x6a9" \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-o newsletter.csv
GET/v1/contacts/:idcontacts:read
نافذة طرفيّة
curl https://api.smsfabric.com/v1/contacts/con_a8d1g4j7m0p3s6v9y2b5e8h1 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

يعيد جهة الاتصال، أو 404 not_found إذا لم تكن في مؤسستك.

PATCH/v1/contacts/:idcontacts:manage

يقبل كل حقول الإنشاء عدا groupIds. الحقلان tags وcustomFields يستبدلان القيم الحالية. ويقبل أيضا optedOut: القيمة true تعلّم جهة الاتصال ملغية للاشتراك (المصدر api للمفاتيح وweb لمستخدمي البوابة)، وfalse تزيل ذلك. يعيد جهة الاتصال.

نافذة طرفيّة
curl -X PATCH https://api.smsfabric.com/v1/contacts/con_a8d1g4j7m0p3s6v9y2b5e8h1 \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"timeZone": "Africa/Cairo", "optedOut": true}'
الخطأ متى
409 contact_exists الرقم الجديد في phone يخص جهة اتصال أخرى.
404 not_found لا توجد جهة الاتصال.
DELETE/v1/contacts/:idcontacts:manage

يمحو جهة الاتصال مع وسومها وعضوياتها في المجموعات (حق المحو). تبقى الرسائل المرسلة سابقا في سجل الرسائل. يعيد 204. يُسجل في التدقيق باسم contact.deleted.

نافذة طرفيّة
curl -X DELETE https://api.smsfabric.com/v1/contacts/con_a8d1g4j7m0p3s6v9y2b5e8h1 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"