الدوال

استخدم عقد OpenAPI لتوليد عميل للتكامل. تعمل الواجهة البرمجية العامة ولوحة التحكم ونقطة نهاية إدارة MCP على موارد مساحة العمل وصلاحياتها نفسها.

القدرة	نقطة النهاية
أدوات قابلة لإعادة الاستخدام	GET / POST /api/v1/voice/tools
قراءة أداة / تحديثها / حذفها	GET / PATCH / DELETE /api/v1/voice/tools/{id}
معاينة أداة أو اختبارها	POST /api/v1/voice/tools/{id}/test
ربط الأدوات بوكيل	PUT /api/v1/voice/agents/{id}/tools
قواعد المعرفة	GET / POST /api/v1/voice/knowledge-bases
قراءة قاعدة معرفة / تحديثها / حذفها	GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id}
إضافة المستندات / عرضها	POST / GET /api/v1/voice/knowledge-bases/{id}/documents
قراءة مستند / حذفه	GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id}
الاشتراكات في أحداث المكالمات	GET / POST /api/v1/voice/webhooks
قراءة اشتراك / تحديثه / حذفه	GET / PATCH / DELETE /api/v1/voice/webhooks/{id}
إرسال حدث اختبار موقَّع	POST /api/v1/voice/webhooks/{id}/test
اكتشاف أدوات MCP البعيدة	POST /api/v1/voice/mcp/discover
نقطة نهاية إدارة MCP	/api/v1/voice/mcp

سجّل أداة HTTP تستعلم عن مهايئ CRM لديك:

{
  "name": "lookup_customer",
  "description": "Find a customer after confirming their customer ID.",
  "kind": "http",
  "url": "https://crm.example.com/customers/{{customer_id}}",
  "method": "GET",
  "read_only": true,
  "credential_ref": "crm",
  "input_schema": {
    "type": "object",
    "properties": { "customer_id": { "type": "string" } },
    "required": ["customer_id"],
    "additionalProperties": false
  },
  "response_path": "data"
}

يُرجع POST /tools القيمة { "data": { "id": "TOOL_ID", ... } }. اربط تعريفها بوكيل عبر PUT /agents/AGENT_ID/tools مع { "tool_ids": ["TOOL_ID"] }. يستبدل هذا قائمة الأدوات كلها بلقطات؛ فأعد الربط عندما تتغير أداة في المكتبة. وحذف تعريف من المكتبة يُبقي اللقطات الموجودة. ويمكنك أيضًا قراءة التعريفات المضمَّنة واستبدالها عبر الحقل tools في واجهة الوكيل. استخدم analysis_config وwidget_config لضبط التحليل والودجت عبر واجهة الوكيل.

يمكن للأداة استخدام GET أو POST أو PUT أو PATCH أو DELETE. يقبل query وrequest_body قوالب JSON متداخلة مثل { "customer": { "id": "{{customer_id}}" } }. العنصر النائب الكامل يحافظ على نوع JSON الأصلي. تُرمَّز العناصر النائبة في عنوان URL ولا يجوز أن تظهر إلا بعد مضيف HTTPS عام ثابت. وبدون request_body تتلقى الأدوات غير GET القيمة { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }. يختار response_path حقلًا بصيغة النقاط. ما زالت parameters البسيطة مقبولة؛ ويدعم input_schema كذلك الكائنات المتداخلة والمصفوفات والتعدادات والحدود الرقمية. لا تُقبل مراجع المخططات الخارجية ولا التعبيرات النمطية.

القيم الثابتة وتمرير القيم وقواعد الرفض

• static_args: قيم تُرسل مع كل استدعاء مهما كتب النموذج، مثل معرّف متجر؛ وتملأ أيضًا {{name}} في العنوان والمحتوى.
• extract: يحتفظ [{name, path}] بحقول من إجابة دالة (data.id) لتُستخدم في {{name}} للدوال اللاحقة، فيمكن لـcustomer_id من استعلام أن يدخل في الطلب التالي دون أن يكرّره النموذج. وتُحفظ حقول استعلام البدء بالطريقة نفسها.
• reject_when: حتى 5 قواعد {on: caller|agent, pattern, negate}؛ ما دامت كلها متحققة على آخر الكلمات، لا تُشغَّل الدالة ويتلقى الوكيل reject_message.
• model_says: في كل استدعاء يكتب النموذج جملة واحدة تُقال أثناء تشغيل الدالة، بدل speak_before الثابتة.

الدوال الجاهزة: الحجز والجداول وSlack

اربط تطبيقًا من التكاملات ← Webhooks والإشعارات ← التطبيقات المتصلة، ثم استخدم «إضافة دالة جاهزة» في تبويب المعرفة والأدوات للوكيل؛ ولا تحتاج إلى نقطة نهاية خاصة بك:

• الحجز (Google Calendar / Cal.com): يضيف check_availability (الأوقات الفارغة في تاريخ ما) وbook_appointment (يحجز الوقت الذي اختاره المتصل). تتبع أوقات Google Calendar المنطقة الزمنية وأيام الدوام والساعات ومدة الموعد التي تضبطها؛ ويستخدم Cal.com توافر نوع الحدث نفسه، وبريدًا إلكترونيًا احتياطيًا تضبطه لحالة ألّا يعطي المتصل بريدًا.
• الحفظ في Google Sheets: يضيف save_to_sheet، وهي تُلحق صفًّا بالأعمدة التي تذكرها، إضافةً إلى معرّف المكالمة ووقتها.
• إشعار الفريق (Slack): يضيف notify_team، وهي تنشر في قناة Slack (incoming webhook) رسالة يكتبها الوكيل.

يشغّل مستوى التحكم في EvaSay هذه الدوال بالحساب الذي ربطته؛ فلا يحتفظ الـworker ولا تعريف الوكيل ببيانات اعتماد التطبيق. وعند قراءة وكيل عبر الواجهة البرمجية تظهر بصيغة kind: "app" (مع app وaction وconnection_id وapp_config)؛ أعِدها كما هي عند استبدال tools لتبقى. تُربَط التطبيقات من لوحة التحكم فقط.

التعرّف على المتصل عند بدء المكالمة

اضبط run_at_start: true على إحدى أدوات الوكيل فتُستدعى عند بدء كل مكالمة، قبل أن يُلقي الوكيل التحية أو يرد. تُملأ له المعاملات المسمّاة caller_number وcalled_number وdirection وchannel وcall_id. وتملأ الحقول التي تُرجعها {{variables}} في first_message وsystem_prompt وidle_messages (والحقول المتداخلة بمستوى واحد مثل {{customer.name}})، وتُعطى الإجابة كلها للوكيل كخلفية. تنتظر التحية التي تحوي متغيرات الإجابة حتى 3 ثوان؛ وما لا يُعثر عليه يُترك فارغًا. يمكن لأداة واحدة لكل وكيل أن تعمل عند البدء.

تُضبط بيانات الاعتماد في بيئة الخادم لمساحة عملك ووجهتك؛ اطلب من support@evasay.com تهيئة credential_ref. لا تضع مفاتيح API في تعريفات الوكلاء أو الترويسات أو التعليمات أو معاملات الأدوات. يمكن لمهايئك أن يحتفظ ببيانات اعتماد CRM في بيئته الخاصة.

عاين أداة قبل إرسال الطلبات إلى نظام الأعمال:

{
  "arguments": { "customer_id": "customer-123" },
  "dry_run": true,
  "mock_result": { "name": "Alex", "order_status": "shipped" }
}

تتحقق المعاينة من المعاملات وتعرض الطلب الناتج؛ ولا تُجري محادثة ولا تتصل بنظام الأعمال. اضبط dry_run=false للتنفيذ الفعلي. ويتطلب اختبار الكتابة الحي أيضًا confirmed=true وidempotency_key (من 8 إلى 128 حرفًا أو رقمًا أو نقطة أو شرطة سفلية أو نقطتين رأسيتين أو شرطة). تتضمن ردود الاختبار ok وstatus وduration_ms ونتيجة محدودة الحجم. ولا تُرجع بيانات اعتماد. تتطلب اختبارات القراءة والكتابة صلاحية الكتابة في مساحة العمل.

أثناء المكالمة تحمل طلبات الأعمال Idempotency-Key ثابتًا. يجب أن تحترمه نقطة نهاية الأعمال لديك. تُزال تكرارات عمليات الكتابة المتطابقة داخل المكالمة، بما في ذلك العمليات المجهولة النتيجة بعد انتهاء المهلة. أما العملية المختلفة المقصودة فتحتاج إلى معامل أعمال مميّز، مثل operation_id. لا تعيد EvaSay تشغيل عمليات الكتابة تلقائيًا. تتضمن أحداث تنفيذ الأدوات الحالة والمدة؛ وتبقى ميزة اختبار المحادثة محاكاة نصية، لا اختبارًا لتنفيذ الأدوات.

السماح للوكيل الصوتي باستدعاء خادم MCP خارجي

يقبل POST /mcp/discover القيمة { "url": "https://crm.example.com/mcp", "credential_ref": "crm" } ويُرجع أدوات الخادم ومخططاته. سجّل الأداة المحددة فقط:

{
  "name": "lookup_customer",
  "description": "Find a CRM customer by confirmed ID.",
  "kind": "mcp",
  "url": "https://crm.example.com/mcp",
  "mcp_tool": "get_customer",
  "credential_ref": "crm",
  "read_only": true,
  "input_schema": {
    "type": "object",
    "properties": { "customer_id": { "type": "string" } },
    "required": ["customer_id"]
  }
}

لا تتاح للوكيل إلا الأدوات المسجَّلة. تدعم الاتصالات البعيدة Streamable HTTP مع ردود JSON أو SSE على الطلبات، ووجهات HTTPS العامة، وبيانات الاعتماد المهيَّأة مسبقًا. لا تُدعم نقاط نهاية SSE القديمة، ولا التفاوض عبر OAuth، ولا sampling/elicitation التي يبدؤها الخادم، ولا المرفقات الثنائية. ولا يمنح الاكتشاف تلقائيًا إمكانية الوصول إلى كل أدوات الخادم. ويجب أن يكون مخطط الأداة البعيدة مضمَّنًا ويستخدم المجموعة الفرعية المدعومة من JSON Schema.