جهات الاتصال
جهة الاتصال شخص ترسل إليه الحملات: واحدة لكل رقم هاتف في كل مؤسسة، مع الأسماء والوسوم والحقول المخصصة والموافقة وحالة إلغاء الاشتراك. تُحفظ الأرقام مشفرة. أضف جهات الاتصال إلى مجموعات أو استورد ملف CSV.
كائن جهة الاتصال
Section titled “كائن جهة الاتصال”| الحقل | النوع | الوصف |
|---|---|---|
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 |
إنشاء جهة اتصال
Section titled “إنشاء جهة اتصال”/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 |
حقل غير صالح. |
عرض جهات الاتصال
Section titled “عرض جهات الاتصال”/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 }.
عرض الوسوم
Section titled “عرض الوسوم”/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”/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قراءة جهة اتصال
Section titled “قراءة جهة اتصال”/v1/contacts/:idcontacts:readcurl https://api.smsfabric.com/v1/contacts/con_a8d1g4j7m0p3s6v9y2b5e8h1 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"يعيد جهة الاتصال، أو 404 not_found إذا لم تكن في مؤسستك.
تحديث جهة اتصال
Section titled “تحديث جهة اتصال”/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 |
لا توجد جهة الاتصال. |
حذف جهة اتصال
Section titled “حذف جهة اتصال”/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"