نظرة عامة على API والمصادقة

يتواجد Ody REST API على https://api.ody.co/v1/api ويصادق على كل طلب باستخدام مفتاح API يتم إرساله كرمز Bearer — أنشئ واحدًا في الإعدادات ← API المطورين، ثم استدعِ نقاط النهاية أدناه.

المصادقة

أرسل مفتاحك في ترويسة Authorization مع كل طلب:

curl https://api.ody.co/v1/api/contacts \
  -H "Authorization: Bearer ody_live_…"

• تأتي المفاتيح في وضعين: مفاتيح ody_live_… هي مفاتيح حية، ومفاتيح ody_test_… تتصرف بشكل متطابق ولكن إرسال الرسائل يكون محاكيًا (يتم تسجيله بـ deliveryStatus: "simulated"، ولا يتم إرساله أبدًا). راجع الإنشاء بأمان باستخدام وضع الاختبار.
• يعيد المفتاح المفقود أو غير الصالح أو الملغى 401 unauthenticated.
• يعيد المفتاح المقيد بالنطاقات 403 permission_denied — مع تسمية النطاق المفقود — عندما يستدعي نقطة نهاية خارج صلاحياته.
• يتم تشغيل كل استدعاء بأذونات العضو الذي أنشأ المفتاح، داخل مساحة العمل تلك فقط.

نقاط النهاية

Method & path	ماذا يفعل	النطاق المطلوب
GET /v1/api/contacts	سرد أو البحث عن جهات الاتصال (?q=، مع ترقيم الصفحات)	contacts:read
POST /v1/api/contacts	إنشاء جهة اتصال	contacts:write
GET /v1/api/contacts/:id	جلب التفاصيل الكاملة لجهة اتصال	contacts:read
PATCH /v1/api/contacts/:id	تحديث جهة اتصال (تتغير الحقول المقدمة فقط)	contacts:write
DELETE /v1/api/contacts/:id	حذف جهة اتصال	contacts:write
GET /v1/api/conversations	سرد المحادثات (?status=open|done، مع ترقيم الصفحات)	conversations:read
GET /v1/api/conversations/:id	جلب سلسلة محادثات كاملة	conversations:read
PATCH /v1/api/conversations/:id	تعيين الحالة — النص {"status":"open"} أو {"status":"done"}	conversations:write
POST /v1/api/messages	إرسال SMS/MMS (يدعم Idempotency-Key)	messages:send
GET /v1/api/messages/search	البحث في نصوص الرسائل والنسخ (?q=)	conversations:read
GET /v1/api/calls	سرد سجل المكالمات والبريد الصوتي	conversations:read
POST /v1/api/calls	إجراء مكالمة ذكاء اصطناعي صادرة — وكيلك المنشور يتصل	calls:place
GET /v1/api/numbers	سرد أرقام مساحة عملك	numbers:read
GET /v1/api/numbers/available	البحث عن أرقام يمكنك شراؤها (?country=، ?startsWith=، ?contains=، ?locality=، ?state=، ?limit=)	numbers:manage
POST /v1/api/numbers	شراء رقم — يتم فوترته كشراء داخل التطبيق (يدعم Idempotency-Key)	numbers:manage
POST /v1/api/numbers/:e164/connect and …/disconnect	توجيه رقم إلى وكيل الذكاء الاصطناعي الخاص بك أو بعيدًا عنه	agent:manage
GET /v1/api/messaging	حالة تسجيل 10DLC (step، canText)	numbers:manage
POST /v1/api/messaging/registration	إرسال عملك + حملتك لـ 10DLC (مدفوعة)	numbers:manage
POST /v1/api/messaging/refresh	إعادة التحقق وتقديم مراجعة 10DLC للناقل	numbers:manage
GET/PATCH /v1/api/agent	قراءة أو تحديث تهيئة وكيل الذكاء الاصطناعي الخاص بك (مسودة)	agent:manage
POST /v1/api/agent/publish	نشر تهيئة وكيلك مباشرة	agent:manage
GET /v1/api/webhook-events	سرد أنواع أحداث الخطافات الشبكية القابلة للاشتراك	webhooks:manage
GET/POST /v1/api/webhooks and /v1/api/webhooks/:id…	إدارة نقاط نهاية الخطافات الشبكية الصادرة	webhooks:manage
GET /v1/api/openapi.json	مواصفات OpenAPI 3.1	none

نقاط نهاية القائمة ترقم الصفحات باستخدام ?limit= و ?cursor= — راجع ترقيم الصفحات، الثبات، ومعالجة الأخطاء.

جهات الاتصال

يتطلب POST /v1/api/contacts حقل هوية واحدًا على الأقل: firstName، lastName، company، رقم هاتف، أو بريد إلكتروني. تقبل الهواتف ورسائل البريد الإلكتروني سلسلة نصية بسيطة ("phone": "+15125550123") أو مصفوفات كاملة ذات تسميات ("phones": [{"value": "+15125550123", "label": "work"}]). عند PATCH، تتغير الحقول التي تقدمها فقط؛ يتم استبدال phones وemails وnotes وproperties وtags بالكامل عند توفيرها.

إرسال رسالة

يقبل POST /v1/api/messages إما conversationId موجودًا أو رقم هاتف مستلم في to (بتنسيق E.164). مع to، يختار Ody رقم الإرسال الخاص بمساحة عملك (أو يحترم رقم from الذي تملكه)، وينشئ المحادثة إذا لزم الأمر، ويربط الرسالة. أضف ما يصل إلى 10 mediaUrls قابلة للجلب علنًا لرسائل MMS:

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

مساحة العمل التي لا تحتوي على رقم هاتف نشط تحصل على 409 failed_precondition. عمليات إعادة المحاولة بنفس Idempotency-Key في غضون 24 ساعة تعيد تشغيل الاستجابة الأولى بدلاً من الإرسال المزدوج.

الأرقام، الرسائل النصية، مكالمات الذكاء الاصطناعي، ووكيلك

يمكن لـ API أيضًا تشغيل خط هاتف من البداية إلى النهاية: البحث وشراء الأرقام، تسجيل 10DLC للرسائل النصية، تهيئة ونشر وكيل الذكاء الاصطناعي الخاص بك، توجيه الأرقام إليه، وإجراء مكالمات ذكاء اصطناعي صادرة. تستخدم نقاط النهاية هذه ثلاثة نطاقات خاصة بها — numbers:manage (شراء الأرقام و10DLC)، calls:place (إجراء مكالمات الذكاء الاصطناعي)، وagent:manage (إدارة وكيل الذكاء الاصطناعي) — وكل ما تفعله يظهر في حسابك تمامًا كما لو كنت قد فعلته في التطبيق، بنفس الفواتير والقواعد. راجع شراء الأرقام وتسجيل الرسائل النصية عبر API و إجراء مكالمات الذكاء الاصطناعي وإدارة Astra عبر API.

الأخطاء، معرفات الطلبات، وحدود المعدل

يستخدم كل خطأ غلافًا موحدًا، وتحمل كل استجابة (نجاح أو خطأ) ترويسة X-Request-Id — اذكرها عند الاتصال بالدعم:

{ "error": { "code": "not_found", "message": "Contact not found", "requestId": "req_…" } }

يحصل كل مفتاح على 600 طلب/دقيقة مع ترويسات RateLimit-* القياسية. التفاصيل في حدود معدل API وأفضل الممارسات و ترقيم الصفحات، الثبات، ومعالجة الأخطاء.

مقالات ذات صلة

• احصل على مفتاح Ody API الخاص بك
• استقبال الخطافات الشبكية والتحقق من التوقيعات
• ترقيم الصفحات، الثبات، ومعالجة الأخطاء
• بدء سريع لـ SDK: TypeScript و Python

---