إجراء مكالمات الذكاء الاصطناعي وإدارة Astra عبر الـ API

يمكن للـ API تكوين ونشر Astra (وكيل الذكاء الاصطناعي الخاص بك)، وربط رقم به، وجعله يجري مكالمات صادرة: POST /v1/api/calls يجعل وكيلك المنشور يتصل برقم، ويجري المحادثة، ويسجل المكالمة — مع تسجيل، ونسخة مكتوبة، وملخص — على الجدول الزمني لجهة الاتصال في صندوق الوارد الخاص بك، ويتم احتساب التكلفة بأرصدة الذكاء الاصطناعي تمامًا مثل مكالمة واردة يجيب عليها الذكاء الاصطناعي.

قبل أن تبدأ

• يحتاج مفتاح API الخاص بك إلى النطاقات الصحيحة — الشرائح في الإعدادات ← API المطور: إدارة وكيل الذكاء الاصطناعي (agent:manage) لتكوين الوكيل وتوجيه الأرقام، وإجراء مكالمات الذكاء الاصطناعي (calls:place) للمكالمات الصادرة. تتضمن مفاتيح الوصول الكامل كلاهما. انظر الحصول على مفتاح Ody API الخاص بك.
• تتطلب المكالمات الصادرة خطة نشطة، ووكيل منشور ومفعل، ورقمًا نشطًا واحدًا على الأقل في مساحة عملك.
• تعمل الأرصدة كالمعتاد تمامًا: 100 رصيد لكل مكالمة يجيب عليها الذكاء الاصطناعي، والمكالمات التي تقل مدتها عن 15 ثانية مجانية، وكل خطة تتضمن 1,000 رصيد شهريًا. انظر أرصدة واستخدام Astra.

تكوين ونشر وكيلك

GET /v1/api/agent يعيد تكوين الوكيل بالإضافة إلى استخدام رصيدك للدورة الحالية — وهو مفيد للتحقق من الميزانية قبل مجموعة من المكالمات. PATCH /v1/api/agent يقوم بتحديثه: name، greeting، tone، voice، language، timezone، inHoursAction/offHoursAction (agent، voicemail، app، أو forward)، enabled، وjobs. تتغير فقط الحقول التي ترسلها، باستثناء jobs، والتي يتم استبدالها بالكامل عند توفيرها:

curl -X PATCH https://api.ody.co/v1/api/agent \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Desk",
    "greeting": "Thanks for calling Acme Plumbing!",
    "tone": "Friendly",
    "jobs": [{"name": "Take a message", "instructions": "Collect the name, number, and reason for calling."}]
  }'

يتم حفظ التغييرات كـ مسودة — نفس المسودة التي تراها على شاشة وكيل الذكاء الاصطناعي في التطبيق. انشرها مباشرة باستخدام:

curl -X POST https://api.ody.co/v1/api/agent/publish \
  -H "Authorization: Bearer ody_live_…"

ربط رقم بالوكيل

POST /v1/api/numbers/{number}/connect يوجه أحد أرقامك إلى الوكيل ليجيب على المكالمات الواردة (قم بترميز + في URL كـ %2B):

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/connect" \
  -H "Authorization: Bearer ody_live_…"

لإعادة توجيهه إلى فريقك، استخدم …/disconnect مع mode من app (يرن على فريقك — الافتراضي)، voicemail، أو forward (مع رقم forwardTo):

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/disconnect" \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"mode":"app"}'

إجراء مكالمة ذكاء اصطناعي صادرة

POST /v1/api/calls يجعل وكيلك المنشور يتصل ويجري المحادثة:

curl https://api.ody.co/v1/api/calls \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15125550199"}'

• to مطلوب (E.164). from اختياري — يفضل Ody رقمك المتصل بالوكيل، ثم رقمك النشط الأول؛ مرر from لاختيار خط معين تملكه.
• تتبع الوجهات الدولية قواعد الاتصال الدولي المعتادة لمساحة عملك — انظر الاتصال الدولي والحدود.
• عند انتهاء المكالمة، تظهر على الجدول الزمني لجهة الاتصال في صندوق الوارد الخاص بك مع تسجيل، ونسخة مكتوبة، وملخص — نفس بطاقة "وكيل الذكاء الاصطناعي تعامل مع هذه المكالمة" مثل مكالمة الذكاء الاصطناعي الواردة.
• الفوترة: 100 رصيد عند الرد على المكالمة، مجانية إذا كانت أقل من 15 ثانية — والمكالمة التي لا يتم الرد عليها مجانية دائمًا.

يمكنك تولي الأمر في أي وقت

أي شيء يتم إجراؤه عبر الـ API هو حالة حسابك الحقيقية — وليس بيئة تطوير معزولة منفصلة. الوكيل الذي ينشره رمزك هو نفسه الموجود على شاشة وكيل الذكاء الاصطناعي؛ الرقم الذي يربطه موجود في الإعدادات ← الأرقام؛ المكالمات التي يجريها تهبط في صندوق الوارد المشترك الخاص بك. هذا يعني أنه يمكنك التدخل متى أردت: تعديل التحية في التطبيق، أو الرد في محادثة بنفسك، أو النقر على شرائح توجيه الرقم لإعادة توجيه المكالمات إلى فريقك — دون الحاجة إلى API.

من مساعد الذكاء الاصطناعي (MCP)

تحصل مساعدات الذكاء الاصطناعي المتصلة على نفس صلاحيات أدوات MCP: get_agent، configure_agent (مرر publish: true للبدء مباشرة في خطوة واحدة)، connect_agent_to_number، وplace_call. انظر ربط أدوات الذكاء الاصطناعي بـ MCP.

وضع الاختبار

باستخدام مفتاح ody_test_…، يعيد POST /calls مكالمة محاكاة (معرف sim_…، لا يوجد اتصال، لا توجد أرصدة مستخدمة) ويتم محاكاة POST /agent/publish (يبقى تكوينك مسودة). عمليات حفظ المسودة عبر PATCH /agent حقيقية على كلا نوعي المفاتيح. انظر الإنشاء بأمان باستخدام وضع الاختبار.

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

• تعرف على Astra، موظفة الاستقبال بالذكاء الاصطناعي الخاصة بك
• أرصدة واستخدام Astra
• شراء الأرقام وتسجيل الرسائل النصية عبر الـ API
• ربط أدوات الذكاء الاصطناعي بـ MCP

---