جهات الاتصال
sms.contacts هو دفتر عناوينك: جهة اتصال واحدة لكل رقم، مع الوسوم والحقول المخصصة والموافقة. ويدير sms.contacts.groups وsms.contacts.imports المجموعات الثابتة واستيراد ملفات CSV. أما sms.templates فيحفظ نصوص الرسائل مع {{variables}} لاستخدامها في الحملات.
جهات الاتصال والمجموعات والاستيراد تحتاج إلى contacts:read للقراءة وcontacts:manage للتعديل. والقوالب تحتاج إلى campaigns:read وcampaigns:manage.
| الدالة | طلب HTTP | القيمة المعادة |
|---|---|---|
contacts.create(params, options?) |
POST /v1/contacts |
Contact |
contacts.list(params?) |
GET /v1/contacts |
Paginated<Contact> |
contacts.listAll(params?) |
GET /v1/contacts (كل الصفحات) |
AsyncGenerator<Contact> |
contacts.get(id) |
GET /v1/contacts/:id |
Contact |
contacts.update(id, params) |
PATCH /v1/contacts/:id |
Contact |
contacts.delete(id) |
DELETE /v1/contacts/:id |
void |
contacts.tags(q?) |
GET /v1/contacts/tags |
Array<{ tag, contacts }> |
contacts.exportCsv(params?) |
GET /v1/contacts/export.csv |
string |
contacts.groups.create(params, options?) |
POST /v1/contact-groups |
ContactGroup |
contacts.groups.list(params?) |
GET /v1/contact-groups |
Paginated<ContactGroup> |
contacts.groups.listAll(params?) |
GET /v1/contact-groups (كل الصفحات) |
AsyncGenerator<ContactGroup> |
contacts.groups.get(id) |
GET /v1/contact-groups/:id |
ContactGroup |
contacts.groups.update(id, params) |
PATCH /v1/contact-groups/:id |
ContactGroup |
contacts.groups.delete(id) |
DELETE /v1/contact-groups/:id |
void |
contacts.groups.addMembers(id, contactIds) |
POST /v1/contact-groups/:id/members |
{ changed, notFound, memberCount } |
contacts.groups.removeMembers(id, contactIds) |
POST /v1/contact-groups/:id/members/remove |
{ changed, notFound, memberCount } |
contacts.imports.upload(csv, fileName?) |
POST /v1/contact-imports |
ContactImport |
contacts.imports.start(id, params) |
POST /v1/contact-imports/:id/start |
ContactImport |
contacts.imports.get(id) |
GET /v1/contact-imports/:id |
ContactImport |
contacts.imports.list(params?) |
GET /v1/contact-imports |
Paginated<ContactImport> |
contacts.imports.listAll(params?) |
GET /v1/contact-imports (كل الصفحات) |
AsyncGenerator<ContactImport> |
templates.create(params, options?) |
POST /v1/templates |
Template |
templates.list(params?) |
GET /v1/templates |
Paginated<Template> |
templates.listAll(params?) |
GET /v1/templates (كل الصفحات) |
AsyncGenerator<Template> |
templates.get(id) |
GET /v1/templates/:id |
Template |
templates.update(id, params) |
PATCH /v1/templates/:id |
Template |
templates.delete(id) |
DELETE /v1/templates/:id |
void |
templates.preview(params) |
POST /v1/templates/preview |
TemplatePreview |
contacts.create
Section titled “contacts.create”تضيف جهة اتصال. الحقل phone بصيغة E.164 وفريد في مؤسستك: إضافة جهة ثانية بالرقم نفسه تعيد 409 contact_exists.
| المعامل | النوع | ملاحظات |
|---|---|---|
phone |
string |
بصيغة E.164. |
firstName وlastName وemail |
string | null |
|
timeZone |
string | null |
منطقة IANA. تتقدم على منطقة دولة الرقم في حساب ساعات الهدوء. |
tags |
string[] |
حتى 20 وسمًا، كل منها من 1 إلى 40 حرفًا من الحروف والأرقام والمسافات و_ و-. |
customFields |
Record<string, string | number | boolean | null> |
مفاتيح بصيغة snake_case، حتى 50 مفتاحًا و4 كيلوبايت، دون تداخل. |
consent |
{ source, at?, text? } |
مصدر موافقة الشخص على استقبال الرسائل: web_form أو import أو api أو in_person أو paper أو sms_keyword أو other. |
groupIds |
string[] |
حتى 20 مجموعة تضاف إليها جهة الاتصال. |
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const contact = await sms.contacts.create({ phone: '+201001234567', firstName: 'Mona', tags: ['vip', 'cairo'], customFields: { loyalty_tier: 'gold', visits: 12 }, consent: { source: 'web_form', text: 'I agree to receive appointment reminders by SMS.' }, groupIds: ['grp_…'],});console.log(contact.id, contact.country); // con_… EGcontacts.list
Section titled “contacts.list”صفحة واحدة من جهات الاتصال، الأحدث أولًا. يطابق q رقمًا كاملًا (تطابق تام) أو آخر 4 أرقام منه أو الاسم الأول أو الأخير أو البريد (احتواء). صفّ حسب tag أو groupId أو optedOut.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sms.contacts.list({ q: '4567', optedOut: false, limit: 10 });for (const c of page.data) console.log(c.id, c.phone, c.firstName);contacts.listAll
Section titled “contacts.listAll”كل جهات الاتصال المطابقة، مع تتبع المؤشرات.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
let count = 0;for await (const contact of sms.contacts.listAll({ tag: 'vip', limit: 200 })) { if (!contact.optedOut) count += 1;}console.log(`${count} reachable VIP contacts`);contacts.get
Section titled “contacts.get”جهة اتصال واحدة مع مجموعاتها وموافقتها وحالة إلغاء اشتراكها.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const contact = await sms.contacts.get('con_…');console.log(contact.groups.map((g) => g.name), contact.optedOut?.source ?? 'subscribed');contacts.update
Section titled “contacts.update”تغيّر أي حقل عدا groupIds. القيم الجديدة في tags وcustomFields تحل محل القيم المحفوظة. والقيمة optedOut: true تسجل إلغاء الاشتراك، وfalse تزيله.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.contacts.update('con_…', { tags: ['vip'], timeZone: 'Africa/Cairo' });await sms.contacts.update('con_…', { optedOut: true }); // the person asked to stopcontacts.delete
Section titled “contacts.delete”تمحو جهة الاتصال مع وسومها وعضويتها في المجموعات. استخدمها لتنفيذ طلب محو البيانات.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.contacts.delete('con_…');contacts.tags
Section titled “contacts.tags”وسومك مرتبة من الأكثر استخدامًا (أول 200)، مع عدد جهات الاتصال في كل وسم. مرّر بادئة للتصفية.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for (const { tag, contacts } of await sms.contacts.tags('ca')) console.log(tag, contacts);contacts.exportCsv
Section titled “contacts.exportCsv”كل جهات الاتصال، أو التي تحمل tag أو تنتمي إلى groupId، كنص CSV. تحتاج إلى contacts:read وlogs:export، وتسجل في سجل التدقيق.
import { writeFile } from 'node:fs/promises';import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await writeFile('vip.csv', await sms.contacts.exportCsv({ tag: 'vip' }));المجموعات
Section titled “المجموعات”المجموعات قوائم ثابتة: لا يتغير أعضاؤها إلا عندما تضيفهم أو تزيلهم، أو عندما يذكر الاستيراد المجموعة.
groups.create
Section titled “groups.create”مجموعة لها name (حتى 120 حرفًا، فريد: 409 group_exists) وdescription اختياري (حتى 500).
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const group = await sms.contacts.groups.create({ name: 'Newsletter', description: 'Monthly offers' });console.log(group.id, group.memberCount);groups.list
Section titled “groups.list”صفحة واحدة من المجموعات (list) أو كلها (listAll). يطابق q جزءًا من الاسم.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for await (const g of sms.contacts.groups.listAll({ q: 'news' })) console.log(g.name, g.memberCount);groups.get, update, delete
Section titled “groups.get, update, delete”اقرأ مجموعة واحدة أو غيّر اسمها أو احذفها. حذف المجموعة يبقي جهات الاتصال.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const group = await sms.contacts.groups.get('grp_…');await sms.contacts.groups.update(group.id, { name: 'Newsletter (EN)', description: null });await sms.contacts.groups.delete(group.id);groups.addMembers and removeMembers
Section titled “groups.addMembers and removeMembers”أضف أو أزل حتى 1,000 جهة اتصال في كل استدعاء. المعرفات التي لا تخص جهات اتصالك تحسب في notFound ولا تربط أبدًا.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const added = await sms.contacts.groups.addMembers('grp_…', ['con_…', 'con_…']);console.log(added.changed, added.notFound, added.memberCount);
await sms.contacts.groups.removeMembers('grp_…', ['con_…']);الاستيراد
Section titled “الاستيراد”لاستيراد CSV خطوتان: ارفع الملف، ثم أكد كيف تقابل أعمدته حقول جهات الاتصال. تعالج الصفوف في الخلفية، 500 صف في كل دفعة.
imports.upload
Section titled “imports.upload”ترفع ملف CSV بترميز UTF-8 (حتى 5 ميغابايت و100,000 صف؛ تفصل الأعمدة فاصلة أو فاصلة منقوطة أو مسافة جدولة) كنص أو بايتات. تحتوي النتيجة على columns وsample لأول 5 صفوف وsuggestedMapping مستنتج من عناوين الأعمدة بالإنجليزية والعربية.
import { readFile } from 'node:fs/promises';import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const upload = await sms.contacts.imports.upload(await readFile('customers.csv'), 'customers.csv');console.log(upload.id, upload.rowCount, upload.columns, upload.suggestedMapping);الملف الذي لا يمكن تحليله يعيد 400 csv_<reason>، والملف الأكبر من 5 ميغابايت يعيد 413، ونوع الملف غير المدعوم يعيد 415 unsupported_file_type.
imports.start
Section titled “imports.start”تؤكد المقابلة وتبدأ الاستيراد. يحدد mapping.phone عمود الهاتف؛ وبقية الحقول وcustom (مفتاح snake_case ← عمود) اختيارية. اضبط defaultCountry للأرقام المحلية مثل 0100 123 4567، وأضف كل صف إلى groupId وtags، وسجّل consent، واختر هل تحدّث جهات الاتصال الموجودة (updateExisting، الافتراضي true).
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const started = await sms.contacts.imports.start('imp_…', { mapping: { phone: 'Mobile', firstName: 'First name', email: 'Email', custom: { city: 'City' } }, defaultCountry: 'EG', groupId: 'grp_…', tags: ['import-nov'], consent: { source: 'import', text: 'Collected at checkout' },});console.log(started.status); // queuedimports.get and list
Section titled “imports.get and list”استعلم عبر get حتى تصبح status بالقيمة completed أو failed. يعد report الصفوف المتجاوزة حسب السبب (invalid_phone وduplicate_in_file وblacklisted…) ويسرد أول 500 منها مع أرقام أسطرها.
import { setTimeout as sleep } from 'node:timers/promises';import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
let job = await sms.contacts.imports.get('imp_…');while (job.status === 'queued' || job.status === 'processing') { await sleep(2_000); job = await sms.contacts.imports.get(job.id);}console.log(job.status, job.created, job.updated, job.skipped, job.report?.skipped);
const recent = await sms.contacts.imports.list({ limit: 5 });console.log(recent.data.map((i) => `${i.fileName}: ${i.status}`));القوالب
Section titled “القوالب”يمكن أن يستخدم نص القالب {{first_name}} و{{last_name}} و{{custom.<key>}}، ولكل منها قيمة بديلة اختيارية: {{first_name|there}}. أي شيء آخر بين قوسين مزدوجين يعيد 400 template_invalid.
templates.create
Section titled “templates.create”name (حتى 120 حرفًا، فريد) وbody (حتى 1,600). تحتوي النتيجة على المتغيرات المستخدمة ومعاينة الأجزاء لجهة اتصال نموذجية.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const template = await sms.templates.create({ name: 'Appointment reminder', body: 'Hi {{first_name|there}}, see you tomorrow at {{custom.time}}. Reply STOP to opt out.',});console.log(template.variables, template.preview.segments, template.preview.encoding);templates.list
Section titled “templates.list”صفحة واحدة (list) أو كل القوالب (listAll). يطابق q جزءًا من الاسم.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sms.templates.list({ q: 'reminder' });for (const t of page.data) console.log(t.id, t.name);templates.get, update, delete
Section titled “templates.get, update, delete”اقرأ قالبًا واحدًا أو عدّله أو احذفه. تحتفظ الحملات بنسختها الخاصة من النص، فتعديل القالب أو حذفه لا يغير حملة استخدمته.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const template = await sms.templates.get('tpl_…');await sms.templates.update(template.id, { body: `${template.body} See you soon.` });await sms.templates.delete(template.id);templates.preview
Section titled “templates.preview”تعرض نصًا كما سيظهر لإحدى جهات اتصالك، أو لجهة اتصال نموذجية، دون حفظ أي شيء. مشكلات القالب تعود في issues لا كخطأ، فيمكنك عرضها أثناء الكتابة.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const preview = await sms.templates.preview({ body: 'Hi {{first_name}}, your code is {{custom.code}}', contactId: 'con_…' });console.log(preview.rendered);console.log(preview.segments); // { encoding: 'GSM7', segments: 1, characters: 31 }for (const issue of preview.issues) console.log(issue.code, issue.token);