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

جهات الاتصال

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

تضيف جهة اتصال. الحقل 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 مجموعة تضاف إليها جهة الاتصال.
create-contact.ts
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_… EG

صفحة واحدة من جهات الاتصال، الأحدث أولًا. يطابق q رقمًا كاملًا (تطابق تام) أو آخر 4 أرقام منه أو الاسم الأول أو الأخير أو البريد (احتواء). صفّ حسب tag أو groupId أو optedOut.

find-contact.ts
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);

كل جهات الاتصال المطابقة، مع تتبع المؤشرات.

vip-count.ts
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`);

جهة اتصال واحدة مع مجموعاتها وموافقتها وحالة إلغاء اشتراكها.

get-contact.ts
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');

تغيّر أي حقل عدا groupIds. القيم الجديدة في tags وcustomFields تحل محل القيم المحفوظة. والقيمة optedOut: true تسجل إلغاء الاشتراك، وfalse تزيله.

update-contact.ts
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 stop

تمحو جهة الاتصال مع وسومها وعضويتها في المجموعات. استخدمها لتنفيذ طلب محو البيانات.

delete-contact.ts
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.contacts.delete('con_…');

وسومك مرتبة من الأكثر استخدامًا (أول 200)، مع عدد جهات الاتصال في كل وسم. مرّر بادئة للتصفية.

tags.ts
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);

كل جهات الاتصال، أو التي تحمل tag أو تنتمي إلى groupId، كنص CSV. تحتاج إلى contacts:read وlogs:export، وتسجل في سجل التدقيق.

export-contacts.ts
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' }));

المجموعات قوائم ثابتة: لا يتغير أعضاؤها إلا عندما تضيفهم أو تزيلهم، أو عندما يذكر الاستيراد المجموعة.

مجموعة لها name (حتى 120 حرفًا، فريد: 409 group_exists) وdescription اختياري (حتى 500).

create-group.ts
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);

صفحة واحدة من المجموعات (list) أو كلها (listAll). يطابق q جزءًا من الاسم.

list-groups.ts
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);

اقرأ مجموعة واحدة أو غيّر اسمها أو احذفها. حذف المجموعة يبقي جهات الاتصال.

group-crud.ts
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);

أضف أو أزل حتى 1,000 جهة اتصال في كل استدعاء. المعرفات التي لا تخص جهات اتصالك تحسب في notFound ولا تربط أبدًا.

group-members.ts
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_…']);

لاستيراد CSV خطوتان: ارفع الملف، ثم أكد كيف تقابل أعمدته حقول جهات الاتصال. تعالج الصفوف في الخلفية، 500 صف في كل دفعة.

ترفع ملف CSV بترميز UTF-8 (حتى 5 ميغابايت و100,000 صف؛ تفصل الأعمدة فاصلة أو فاصلة منقوطة أو مسافة جدولة) كنص أو بايتات. تحتوي النتيجة على columns وsample لأول 5 صفوف وsuggestedMapping مستنتج من عناوين الأعمدة بالإنجليزية والعربية.

upload-import.ts
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.

تؤكد المقابلة وتبدأ الاستيراد. يحدد mapping.phone عمود الهاتف؛ وبقية الحقول وcustom (مفتاح snake_case ← عمود) اختيارية. اضبط defaultCountry للأرقام المحلية مثل 0100 123 4567، وأضف كل صف إلى groupId وtags، وسجّل consent، واختر هل تحدّث جهات الاتصال الموجودة (updateExisting، الافتراضي true).

start-import.ts
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); // queued

استعلم عبر get حتى تصبح status بالقيمة completed أو failed. يعد report الصفوف المتجاوزة حسب السبب (invalid_phone وduplicate_in_file وblacklisted…) ويسرد أول 500 منها مع أرقام أسطرها.

wait-for-import.ts
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}`));

يمكن أن يستخدم نص القالب {{first_name}} و{{last_name}} و{{custom.<key>}}، ولكل منها قيمة بديلة اختيارية: {{first_name|there}}. أي شيء آخر بين قوسين مزدوجين يعيد 400 template_invalid.

name (حتى 120 حرفًا، فريد) وbody (حتى 1,600). تحتوي النتيجة على المتغيرات المستخدمة ومعاينة الأجزاء لجهة اتصال نموذجية.

create-template.ts
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);

صفحة واحدة (list) أو كل القوالب (listAll). يطابق q جزءًا من الاسم.

list-templates.ts
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);

اقرأ قالبًا واحدًا أو عدّله أو احذفه. تحتفظ الحملات بنسختها الخاصة من النص، فتعديل القالب أو حذفه لا يغير حملة استخدمته.

template-crud.ts
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);

تعرض نصًا كما سيظهر لإحدى جهات اتصالك، أو لجهة اتصال نموذجية، دون حفظ أي شيء. مشكلات القالب تعود في issues لا كخطأ، فيمكنك عرضها أثناء الكتابة.

preview.ts
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);