وثائق API — REST v1 وwebhooks والبث

البداية السريعة: أول طلب لك في 60 ثانية

أنشئ مفتاح API في مساحة عملك، وصدِّره، واعرض قائمة محادثاتك. المفاتيح محصورة النطاق لكل مساحة عمل، ويمكن أن تكون للقراءة فقط أو للقراءة والكتابة.

curl https://api.inteligenciaviva.com/v1/workspaces/WORKSPACE_ID/conversations \
  -H "Authorization: Bearer sk_live_..."

كل استجابة هي JSON. تُرجع نقاط نهاية المجموعات مصفوفات `data`؛ وتُرجع الأخطاء كائن `error` يحمل `code` و`message` مع حالة HTTP مطابقة.

الواجهة البرمجية المجانية — بلا حساب وبلا مفتاح

الطبقة المجانية تتحدث API أيضًا. تستقبل `POST /v1/free/widget-snippet` الإعدادات نفسها بالضبط التي يبنيها المولِّد المرئي في صفحة مجانًا وتُرجع مقتطف HTML الجاهز للصق — بلا مصادقة وبلا تسجيل. استخدمها لتوليد أدوات لمواقع العملاء دفعة واحدة، أو لإعادة توليد التضمينات من CI عند تغيّر الجداول، أو ببساطة لتلمس الواجهة البرمجية قبل أن تدفع سنتًا واحدًا.

curl -X POST https://api.inteligenciaviva.com/v1/free/widget-snippet \
  -H "Content-Type: application/json" \
  -d @widget-config.json
# → { "snippet": "<link rel=\"stylesheet\" ..." }

المصادقة

تحمل كل الطلبات مفتاح API في ترويسة `Authorization` كرمز Bearer. تُنشأ المفاتيح وتُلغى من الواجهة البرمجية نفسها أو من لوحة التحكم، لكل مساحة عمل — وإلغاء مفتاح يقطع وصوله فورًا.

نقاط نهاية جلسات الحساب (التسجيل، وتسجيل الدخول، والدخول عبر Google، وتبادل التذاكر، والملف الشخصي، وحذف الحساب تحت `/v1/auth`) تشغّل تطبيقاتنا نحن؛ أما لتكاملات الخادم إلى الخادم فاستخدم دائمًا مفاتيح API الخاصة بمساحة العمل بدلًا من جلسات المستخدمين.

Authorization: Bearer sk_live_...

مرجع الموارد

كل المسارات أدناه تتفرع من `https://api.inteligenciaviva.com/v1/workspaces/{workspaceId}` ما لم يُذكر خلاف ذلك. هذا هو السطح الفعلي المركَّب في الخادم الخلفي الحالي — لا طموحات.

صندوق الوارد الموحّد `/inbox`

GET	/conversations	كل المحادثات من جميع مساحات العمل التي تخدمها بيانات الاعتماد، في قائمة واحدة مرتبة حسب النشاط.
GET	/conversations/{id}	محادثة يتم البحث عنها في كل مساحات عملك دون معرفة أيها. تُعيد workspace_id.
GET	/workspaces	مساحات العمل التي يمكن لبيانات الاعتماد هذه خدمتها، مع الدور في كل منها.
GET	/visitantes	من يتصفح الآن في جميع مساحات العمل لديك، مع الصفحة التي يقرؤها وهل يحادث بالفعل. لقطة للحظة وليست سجلًا: لا تُقسَّم إلى صفحات. مساحة العمل التي لا تجيب لا تُسقط القائمة: تُذكر في `casas_sin_responder`.

المحادثات `/conversations`

GET	/	عرض قائمة المحادثات، مع إمكانية التصفية بالحالة.
GET	/{id}	محادثة واحدة مع حالتها وقناتها وجهة اتصالها وإسنادها.
GET	/{id}/messages	سجل الرسائل (زائر، وكيل بشري، ذكاء اصطناعي، نظام).
POST	/{id}/messages	إرسال رسالة داخل المحادثة بصفة وكيل.
POST	/{id}/assign	إسناد المحادثة إلى وكيل بشري أو قسم.
POST	/{id}/resolve	إغلاق المحادثة. إذا أغلقها الذكاء الاصطناعي بمفرده، تُحتسب محادثة محلولة قابلة للفوترة.
POST	/	فتح محادثة من خارج الأداة (مثلًا لترحيل محادثة قائمة).
GET	/{id}/ai-turns	«من أين أتى بذلك؟» — سجل كل دور للذكاء الاصطناعي: على ماذا استند، وأي نموذج، وكم استغرق، ولماذا حوّل.
GET	/{id}/portal-case	حالة الحالة التي فتحتها هذه المحادثة في لوحة دعم البوابة، مع ردودها. يُستعلم عنها مباشرة.
POST	/{id}/read	وضع علامة مقروء من الفريق (عدّاد غير المقروء).
POST	/{id}/reopen	إعادة فتح محادثة مغلقة مع الحفاظ على السجل. بدونها كان الإغلاق بالخطأ نهائيًا.
POST	/{id}/archive	أرشفة أو إلغاء الأرشفة. تخرج من الوارد دون إغلاقها ودون فقد شيء؛ الجسم {valor:true\|false}.
POST	/{id}/pin	تثبيت في الأعلى أو إلغاؤه. المثبّتة تتصدّر الصفحة الأولى من الوارد. الجسم: {valor:true\|false}.
POST	/{id}/mute	كتم التنبيهات لعدد N من الساعات، أو {horas:null} لسماعها من جديد.
POST	/{id}/unread	تركها غير مقروءة: تُرجَع علامة القراءة إلى ما قبل آخر رسالة من العميل.
POST	/{id}/typing	إشارة «يكتب…» نحو العميل: في واتساب تستقبلها Meta، وفي دردشة الويب تستقبلها أداة الزائر. بلا جسم؛ ترجع 204 دائمًا (ولا تفعل شيئًا في القنوات التي لا تدعمها) و404 إذا لم تكن المحادثة موجودة.
POST	/{id}/messages/{messageId}/forward	إعادة توجيه رسالة إلى محادثة أخرى في مساحة العمل نفسها، مع مرفقها (يُنسخ ولا يُشارك). الجسم: `{to_conversation_id}`. تخرج كرسالة من الوكيل.
PUT	/{id}/messages/{messageId}/reaction	التفاعل برمز تعبيري مع رسالة واتساب؛ يحل محل تفاعل النشاط السابق و`{emoji:null}` يزيله. واتساب فقط (واجهة Meta)، وفقط على رسالة أكّدتها Meta: وإلا 400.
POST	/{id}/location	إرسال موقع عبر واتساب: `{lat, lon, name?, address?, reply_to_message_id?}`. يُرسل إلى Meta أولًا: إذا رفضته Meta لا يبقى شيء في المحادثة. واتساب فقط.
POST	/{id}/contact-card	إرسال بطاقة جهة اتصال عبر واتساب: `{name:{formatted_name}, phones?, emails?, reply_to_message_id?}`. مثل الموقع: Meta أولًا ثم المحادثة. واتساب فقط.
GET	/{id}/copiloto	المساعد الخاص بالوكيل: ما اقترحه الذكاء الاصطناعي لهذه المحادثة وما دار معه. خاص بالفريق: لا يراه العميل.
POST	/{id}/copiloto	طرح سؤال على الذكاء الاصطناعي بشكل خاص حول هذه المحادثة (`{content}`، حتى 4000 حرف). يجيب الوكيلَ لا العميل: لا يخرج شيء عبر القناة. 503 `copilot_unavailable` إذا تعذّر الرد.
POST	/{id}/copiloto/{sugerenciaId}/enviar	إرسال اقتراح من المساعد إلى العميل، كما هو أو بعد التعديل (`{content}` اختياري). يخرج كرسالة من الوكيل مع كاتبها البشري. يُرسل الاقتراح مرة واحدة فقط: المحاولة الثانية تعطي 409 `ya_enviada`.
POST	/{id}/resumen	طلب ملخص المحادثة (مفتوحة أو مغلقة) وتحديث بطاقة جهة الاتصال به. يكلّف مهمة واحدة من KIT؛ وإعادة الطلب دون رسائل جديدة لا تُحتسب مرة أخرى. إذا لم يوجد ملخص يُرجع السبب (`motivo`، `codigo`).

جهات الاتصال `/contacts`

GET	/	عرض قائمة جهات الاتصال.
GET	/{id}	جهة اتصال واحدة مع هوياتها وسجل محادثاتها.
GET	/{id}/historial	عمّ كانت استفساراته الأخيرة: أحدث المحادثات مع ملخصاتها (`?limit=`، حتى 25)، والإجماليات، وبطاقة جهة الاتصال. فتحها لا يُنشئ البطاقة الناقصة لأن ذلك يكلّف مالًا: تُطلب صراحةً بـ `?generar=1`.

وكلاء الذكاء الاصطناعي `/ai-agents`

GET	/	عرض وكلاء الذكاء الاصطناعي في مساحة العمل.
POST	/	إنشاء وكيل ذكاء اصطناعي: التعليمات، والقسم، وعتبة الثقة.
PATCH	/{id}	تحديث التعليمات أو العتبة أو القسم.
GET	/{id}/knowledge-sources	مصادر المعرفة الموصولة بهذا الوكيل.
POST	/{id}/knowledge-sources	وصل مصدر معرفة بهذا الوكيل.
GET	/{aiAgentId}	وكيل ذكاء اصطناعي واحد: التعليمات وعتبة الثقة والأدوات والقسم.

المعرفة (RAG) `/knowledge-sources`

POST	/document	فهرسة مستند كمعرفة تُبنى عليها الإجابات.
POST	/url	فهرسة رابط URL.
GET	/{id}	حالة المصدر وبياناته الوصفية.
DELETE	/{id}	إزالة مصدر ومتجهاته.
POST	/{id}/reindex	إعادة قراءة مصدر عنوان URL دون حذفه: إذا فشل التنزيل، لا يتغيّر شيء.
GET	/	سرد مصادر المعرفة مع حالة الفهرسة.

بطاقة بيانات النشاط `/ficha`

GET	/	سرد الوحدات (مرشحا ?estado= و ?tipo=) مع عتبات النطاقات.
POST	/	إنشاء وحدة: السؤال والصيغ والإجابة المعتمدة والرابط واللغة. ينشرها المسؤول أو مفتاح API، ويقترحها الوكيل. الذكاء الاصطناعي لا ينشر أبدًا.
GET	/{id}	عرض وحدة.
PATCH	/{id}	تعديل وحدة؛ تغيير السؤال أو الصيغ يعيد حساب التضمين.
DELETE	/{id}	حذف وحدة (مسؤول).
POST	/{id}/aprobar	اعتماد اقتراح: يصبح نشطًا ويُسجَّل من اعتمده (مسؤول).
POST	/{id}/rechazar	رفض اقتراح (مسؤول).
POST	/probar	معاينة: ما الذي ستجيب به البطاقة عن سؤال، مع الدرجة والنطاق (اختياريًا مع الاقتراحات).
POST	/recalcular	إعادة حساب التضمينات الناقصة أو غير المطابقة للنص (مسؤول).

القنوات `/channels`

GET	/	عرض القنوات. العاملة اليوم: دردشة الويب والواجهة البرمجية؛ وتُوصَل قنوات أخرى فور إطلاقها.
PUT	/{id}/credentials	ضبط بيانات اعتماد قناة.
PUT	/{id}/status	تفعيل قناة أو تعطيلها.
POST	/	إنشاء قناة.
GET	/{channelId}	قناة واحدة بنوعها وحالتها وإعداداتها.
GET	/{channelId}/snippet	السطر الوحيد الذي يلصقه العميل في موقعه. كل ما عداه يُضبط من هنا.
GET	/{channelId}/config	إعدادات الدردشة: المنشور (`config`) وما تتجاوزه هذه القناة (`settings`). وهما مختلفان.
PUT	/{channelId}/config	حفظ الإعدادات. الحفظ والنشر خطوة واحدة: إذا فشلت الشبكة، فشل الطلب.
POST	/{channelId}/config/publish	إعادة نشر الإعدادات إلى الشبكة دون تغييرها.
POST	/{channelId}/avatar	رفع صورة المساعد (≤512 كيلوبايت). تُخزَّن في R2 وتُقدَّم عبر الشبكة.
POST	/republicar-todos	إعادة نشر كل قنوات مساحة العمل. يقوم بذلك المجدول عند تغيّر حزمة النصوص؛ وهذا لتفادي الانتظار.
PUT	/{channelId}/modo	وضع الخدمة في القناة: `{modo:"humano"\|"hibrido"\|"ia"}`. يحدد هل يتحدث الذكاء الاصطناعي مع العميل. صالح لأي نوع من القنوات (واتساب، تيليجرام، البريد، الأداة). للمسؤولين فقط.
PUT	/{channelId}/auto	الرسائل التلقائية للقناة: `{bienvenida, fueraDeHorario}` (حتى 1000 حرف لكل منهما؛ `null` تحذف). رسالة خارج الدوام تستخدم ساعات عمل القناة. للمسؤولين فقط.
PUT	/{channelId}/tarjeta	بطاقة جهة الاتصال التي يمكن للوكيل إرسالها من هذه القناة: `{tarjetaContacto:{name:{formatted_name}, phones?, emails?}}`، مع هاتف أو بريد واحد على الأقل؛ `null` تزيلها. واتساب فقط. للمسؤولين فقط.
PUT	/{channelId}/horario	ساعات العمل: `{officeHours:{tz, dias:{lun:[["09:00","17:00"]], …}, festivos:["MM-DD" أو "YYYY-MM-DD"]}}`؛ `null` تزيلها (على مدار الساعة). ما لا يُفهم يُرفض بالرمز 400 مع بيان الخطأ. يُرجع `abiertoAhora` محسوبًا على الخادم. للمسؤولين فقط.

الوكلاء البشريون والأقسام `/agents · /departments`

GET	/agents	عرض الوكلاء البشريين في مساحة العمل.
POST	/agents/{userId}/departments	إلحاق وكيل بقسم.
GET	/departments	عرض الأقسام.
PUT	/departments/{id}/routing-rules	ضبط قواعد توجيه المحادثات الواردة.
POST	/agents	دعوة شخص إلى مساحة العمل بدوره وأقسامه.
GET	/agents/{userId}	عضو واحد من الفريق.
POST	/departments	إنشاء قسم بقواعد التوجيه الخاصة به.
GET	/departments/{id}	قسم واحد.

Webhooks والمفاتيح والفوترة والتحليلات `/webhooks · /api-keys · /billing · /analytics`

POST	/webhooks	تسجيل نقطة نهاية؛ تتلقى سرّ توقيعها مرة واحدة فقط.
DELETE	/webhooks/{id}	إزالة نقطة نهاية.
POST	/api-keys	إنشاء مفتاح (للقراءة فقط أو للقراءة والكتابة).
DELETE	/api-keys/{id}	إلغاء مفتاح فورًا.
GET	/billing/subscription	الخطة، والمحادثات المحلولة بالذكاء الاصطناعي المشمولة، والاستخدام في هذه الفترة.
GET	/analytics	مقاييس مجمعة لمساحة العمل.
GET	/webhooks	سرد نقاط الويب هوك.
GET	/webhooks/{id}/deliveries	سجل عمليات تسليم الويب هوك مع إعادات المحاولة. هو ما يوضح إن كان الخلل لديك أم لدينا.
GET	/api-keys	سرد المفاتيح. لا يُعاد السر أبدًا، بل بادئته فقط.

أدوات الوكيل `/conversations/{id} · /canned-responses · /tags · /presence`

GET	/conversations/{id}/notes	ملاحظات داخلية على المحادثة. لا يراها الزائر أبدًا.
POST	/conversations/{id}/notes	إضافة ملاحظة داخلية.
DELETE	/conversations/{id}/notes/{noteId}	حذف ملاحظة داخلية.
GET	/canned-responses	الردود الجاهزة لمساحة العمل، مع اختصارها.
POST	/canned-responses	إنشاء رد جاهز.
PATCH	/canned-responses/{cannedId}	تعديل رد جاهز.
DELETE	/canned-responses/{cannedId}	حذف رد جاهز.
POST	/presence	نبضة التواجد: تعلن أن هناك شخصًا متاحًا. بالجلسة فقط — مفتاح API ينبض ليس شخصًا أمام الشاشة، ويُرفض بالرمز 400.
GET	/presence	هل يوجد أحد متصل الآن؟ هذا يحدد ما إذا كان التحويل ينتظر أم يُحوَّل.
GET	/ai-usage	استهلاك الاستدلال لمساحة العمل يوميًا والمحادثات الأكثر استهلاكًا.
GET	/tags	وسوم مساحة العمل.
GET	/conversations/{id}/tags	وسوم محادثة.
POST	/conversations/{id}/tags	وسم محادثة. يُنشئ الوسم إن لم يكن موجودًا.
DELETE	/conversations/{id}/tags/{tagId}	إزالة وسم من المحادثة.
POST	/conversations/{id}/transfer	تحويل المحادثة إلى قسم. له الأولوية على قواعد التوجيه: التحويل اليدوي لا يُلغى تلقائيًا.
POST	/contacts/{contactId}/block	حظر جهة اتصال. تتلقى 403 بدون تفاصيل: لا يُشرح للمُسيء كيف تم اكتشافه.
GET	/canned-responses/categories	الفئات المستخدمة بالفعل في الردود الجاهزة (نص حر)، للإكمال التلقائي.
POST	/canned-responses/{cannedId}/use	تسجيل استخدام رد جاهز (العدّاد وآخر استخدام). ترجع 204 دائمًا، موجودًا كان أم لا: هي قياس للاستخدام وليست إجراءً.

المرفقات والأجهزة ومساحات العمل `/conversations/{id}/attachments · /devices · /workspaces`

POST	/conversations/{id}/attachments	رفع مرفق كوكيل. قائمة سماح صارمة و10 ميغابايت: لا يمر شيء يمكن للمتصفح تنفيذه.
GET	/conversations/{id}/attachments	مرفقات محادثة.
GET	/attachments/{attachmentId}	تنزيل مرفق. يُقدَّم برؤوس صارمة و`nosniff`؛ الصور والصوت فقط تُعرض ضمن الصفحة.
POST	/devices/register	تسجيل رمز الإشعارات لجهاز، لتنبيه شخص عند تحويل الذكاء الاصطناعي. خارج بادئة مساحة العمل: `/v1/devices/register`.
POST	/workspaces	إنشاء مساحة عمل. خارج البادئة: `/v1/workspaces`.
GET	/workspaces/{workspaceId}/retencion/ensayo	تجربة الحذف: كم محادثة ومرفقًا (وكم بايت) سيزيله الاحتفاظ، دون حذف أي شيء. `?days=` يسأل عن مدة لم تُحفظ بعد. يتطلب صلاحية المسؤول و`analytics:read`. المسار الكامل: `/v1/workspaces/{workspaceId}/retencion/ensayo`.

الزوار المباشرون والوقت الحقيقي `/visitantes · /stream-ticket`

GET	/visitantes	من يتصفح الآن مواقع مساحة العمل هذه: الصفحة واللغة ومنذ متى، وهل لديه الدردشة مفتوحة أو محادثة جارية.
POST	/visitantes/{visitorId}/invitar	دعوة زائر إلى فتح الدردشة، مع `{mensaje}` اختياري (من دونه تُستخدم تحية الأداة بلغته). لا تُنشئ محادثة ولا تستهلك ذكاءً اصطناعيًا: تبدأ المحادثة حين يرد الزائر. 404 `no_esta` إذا غادر؛ 409 `ya_conversa` إذا كان يحادث بالفعل.
POST	/stream-ticket	تذكرة لفتح WebSocket البث بـ `?ticket=` دون وضع الرمز في عنوان URL. صالحة 60 ثانية ولمرة واحدة. تعمل بالجلسة أو بمفتاح API.

قدرات KIT `/conversations/{id}/kit`

GET	/	مهام KIT التي أُطلقت في هذه المحادثة مع حالتها. عرضها يراجع المهام المعلقة أيضًا.
GET	/catalogo	أي قدرات KIT يمكن إطلاقها على مرفق (`?attachment_id=`) أو على المحادثة، مع بحث (`?q=`، `?lang=`). للقراءة فقط: لا تكلّف شيئًا.
POST	/	إطلاق قدرة من KIT (`{action, attachment_id?, params?}`) على مرفق أو على المحادثة. تعود النتيجة كملاحظة داخلية ولا تصل إلى العميل أبدًا. تكلّف مالًا من محفظة KIT، والطلب نفسه لا يُحتسب مرتين. 202 مع وضع المهمة في الطابور.

الهاتف (VOICE) `/voice`

GET	/llamadas	سجل مكالمات مقسم الهاتف الخاص بمساحة العمل (`?limite=` حتى 200، و`?antes_de=` للتصفح). النطاق `voice:read`؛ و404 إذا لم يكن لمساحة العمل مقسم.
GET	/llamadas-en-curso	المكالمات الجارية الآن.
GET	/aparcadas	المكالمات المركونة بانتظار من يستأنفها.
GET	/grabaciones/{id}/audio	صوت تسجيل، يُقدَّم عبر واجهة API (دون رابط عام) ودون تخزين مؤقت. يسجّل المقسم من استمع إليه.
GET	/extensiones	التحويلات الداخلية التي يمكن للوحة استخدامها كهاتف (المحجوزة لا تظهر).
POST	/webphone-sesion	تسجيل المتصفح كهاتف لتحويلة داخلية (`{extension_id}`): يُرجع بيانات اعتماد SIP قصيرة العمر يدوّرها المقسم في كل استبدال. النطاق `voice:write`. مفتاح المقسم لا يغادر الخادم أبدًا.

أمثلة حقيقية

إرسال رسالة وكيل (curl)

curl -X POST \
  https://api.inteligenciaviva.com/v1/workspaces/$WS/conversations/$CONV/messages \
  -H "Authorization: Bearer $IV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hi! I checked your order — it ships tomorrow."}'

عرض قائمة المحادثات (JavaScript)

const res = await fetch(
  `https://api.inteligenciaviva.com/v1/workspaces/${WS}/conversations`,
  { headers: { Authorization: `Bearer ${process.env.IV_KEY}` } }
);
const { data } = await res.json();

التحقق من توقيع webhook (Node)

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header, toleranceSec = 300) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((p) => p.split("="))
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Webhooks

سجّل نقطة نهاية HTTPS ونرسل إليها كل حدث عبر POST، موقَّعًا. الترويسة هي `iv-signature: t=<unix>,v1=<hex>`، حيث `v1` هو HMAC-SHA256 لـ `<timestamp>.<raw body>` بسرّ نقطة نهايتك — ارفض أي شيء أقدم من 5 دقائق (حماية من إعادة الإرسال). يُعاد إرسال التسليمات الفاشلة تلقائيًا بتوقيع جديد، حتى 5 محاولات.

conversation.created	بدأت محادثة جديدة على أي قناة.
message.created	وصلت رسالة (زائر أو إنسان أو ذكاء اصطناعي أو نظام).
handoff.requested	قرر الذكاء الاصطناعي أنه يحتاج إلى إنسان — اللحظة بعينها، مع الملخص.
conversation.resolved	أُغلقت محادثة؛ ويخبرك ما إذا كان الذكاء الاصطناعي قد أغلقها بمفرده.

يُسجَّل كل تسليم وحالته — فالـ webhook الذي لا يمكنك الوثوق به أسوأ من لا شيء.

البث في الوقت الفعلي

لواجهات المستخدم الحية، افتح اتصال WebSocket على بث مساحة العمل وتلقَّ أحداث المحادثات فور حدوثها — القناة نفسها التي تستخدمها تطبيقات وكلائنا.

wss://api.inteligenciaviva.com/v1/workspaces/{workspaceId}/stream

الأخطاء والحدود

الأخطاء هي HTTP التقليدية: `400` طلب مشوَّه، `401` مفتاح مفقود أو غير صالح، `403` مفتاح بلا نطاق صلاحية، `404` مورد ليس في مساحة العمل هذه، `429` تجاوز حد المعدل (تراجع وأعد المحاولة مع تشويش عشوائي)، `5xx` خطأنا نحن — أعد محاولة الطلبات العديمة الأثر الجانبي. يحمل الجسم دائمًا `error.code` و`error.message` مفهومة للبشر. حدود المعدل لكل مفتاح، وهي سخية للتكاملات الحقيقية.

الأسئلة الشائعة

هل هذه الوثائق طموحات أم السطح الحقيقي؟

حقيقية. كُتبت مقابل المسارات المركَّبة في الخادم الخلفي الحالي. عندما يقول شيء هنا "قريبًا"، فهو غير موجود بعد — نحن لا نوثّق السراب.

هل أحتاج إلى خطة مدفوعة لاستخدام الواجهة البرمجية؟

نعم — الواجهة البرمجية جزء من المنصة المدفوعة (Pro تتضمنها). الأداة المجانية وإضافة ووردبريس تعملان في جهة العميل ولا تحتاجان إلى أي واجهة برمجية.

ما الفرق بين مفاتيح القراءة فقط ومفاتيح القراءة والكتابة؟

مفاتيح القراءة فقط يمكنها العرض والجلب لكنها لا تعدّل أبدًا — مثالية للوحات المعلومات وذكاء الأعمال. مفاتيح القراءة والكتابة يمكنها إنشاء الرسائل وجهات الاتصال ووكلاء الذكاء الاصطناعي والإعدادات.

كيف أُخطَر بالرسائل الجديدة — بالاستطلاع الدوري أم بالـ webhooks؟

الـ webhooks (`message.created`) للخوادم، وبث WebSocket لواجهات المستخدم الحية. الاستطلاع الدوري يعمل لكنك ستصطدم بحدود المعدل قبل أن تصل إلى الزمن الفعلي.

كيف أتحقق بالضبط من أن webhook جاء منكم؟

أعد حساب HMAC-SHA256 لـ `<t>.<raw body>` بسرّ نقطة نهايتك وقارنه بزمن ثابت مع قيمة `v1` في ترويسة `iv-signature`؛ وارفض إذا كان `t` أقدم من 300 ثانية. الكود العامل موجود في هذه الصفحة.

ماذا يحدث إذا كانت نقطة نهاية الـ webhook لديّ متوقفة؟

نسجّل التسليم الفاشل ونعيد المحاولة تلقائيًا بطابع زمني وتوقيع جديدين، حتى 5 محاولات. وإذا حُذفت نقطة النهاية أو عُطّلت في الأثناء، تتوقف المحاولات بشكل نظيف.

هل يستطيع الذكاء الاصطناعي التسليم إلى نظام التصعيد الخاص بي؟

نعم — لهذا يوجد `handoff.requested`. يُطلَق في اللحظة التي تنتقل فيها المحادثة إلى شخص (طلب الزائر ذلك، أو ظهرت علامات أزمة أو إحباط، أو لم تستند الإجابة إلى المعرفة)، مع ملخص المحادثة، لتنبّه أحدًا أو تفتح تذكرة في نظام آخر.

ما القنوات التي يمكنني تشغيلها عبر الواجهة البرمجية اليوم؟

دردشة الويب تعمل من الطرف إلى الطرف، وكل ما في هذا المرجع يعمل اليوم. يتصل Telegram وقنوات المراسلة اللاحقة بنموذج المحادثات نفسه فور إطلاقها — لن يتغير تكاملك.

هل توجد حزمة SDK؟

حزمة Flutter SDK تشغّل تطبيق وكلائنا نحن، وهي أساس حزمة Enterprise ذات العلامة البيضاء. أما للخوادم، فسطح REST بسيط عمدًا — أي عميل HTTP يعمل دون غلاف.

أين أبلغ عن خطأ في الواجهة البرمجية أو نقص في هذه الوثائق؟

اكتب إلى l@inteligenciaviva.com. الوثائق التي تكذب أخطاء أيضًا — ونعاملها بالجدية نفسها.

ابنِ على الواجهة البرمجية نفسها التي نبني عليها

البداية السريعة: أول طلب لك في 60 ثانية

الواجهة البرمجية المجانية — بلا حساب وبلا مفتاح

المصادقة

مرجع الموارد

صندوق الوارد الموحّد /inbox

المحادثات /conversations

جهات الاتصال /contacts

وكلاء الذكاء الاصطناعي /ai-agents

المعرفة (RAG) /knowledge-sources

بطاقة بيانات النشاط /ficha

القنوات /channels

الوكلاء البشريون والأقسام /agents · /departments

Webhooks والمفاتيح والفوترة والتحليلات /webhooks · /api-keys · /billing · /analytics

أدوات الوكيل /conversations/{id} · /canned-responses · /tags · /presence

المرفقات والأجهزة ومساحات العمل /conversations/{id}/attachments · /devices · /workspaces

الزوار المباشرون والوقت الحقيقي /visitantes · /stream-ticket

قدرات KIT /conversations/{id}/kit

الهاتف (VOICE) /voice