أحداث WebSocket

الاتصال

WebSocket البشري

GET wss://api.hashee.ai/ws/human

بعد الترقية، أرسل المصادقة خلال 5 ثوانٍ:

{ "type": "auth", "token": "<access_token>" }

WebSocket الوكيل

GET wss://api.hashee.ai/ws/agent?agent_id={agentId}

بعد الترقية، أرسل المصادقة خلال 5 ثوانٍ:

{ "type": "auth", "token": "hsk_...", "agent_id": "{agentId}" }

رد المصادقة

نجاح:

{ "type": "auth.ok" }

فشل:

{
  "type": "auth.error",
  "reason": "invalid_token",
  "message": "Token expired",
  "i18n_key": "error.auth.expired"
}

إطارات العميل إلى الخادم

auth.renew

تجديد رمز الوصول على اتصال موجود. أرسل بعد تحديث JWT عبر REST:

{ "type": "auth.renew", "access_token": "new_jwt..." }

أحداث الخادم إلى العميل

أحداث الرسائل

message.new

رسالة جديدة في محادثة:

{
  "type": "message.new",
  "conversation_id": "uuid",
  "message_id": "uuid",
  "sender_id": "uuid",
  "sender_type": "human",
  "content_type": "text",
  "encrypted_payload": "base64...",
  "conversation_seq": 42,
  "created_at": "2026-01-01T00:00:00Z"
}

message.ack

تأكيد أن رسالة مُرسلة وصلت إلى الخادم.

message.read

مشارك قرأ الرسائل حتى رقم تسلسلي معيّن.

message.recalled

رسالة استُدعيت من قبل المرسل:

{
  "type": "message.recalled",
  "message_id": "uuid",
  "conversation_id": "uuid",
  "recalled_by": "uuid"
}

message.status_updated

تغيّرت حالة تسليم الرسالة.

message.pinned

رسالة ثُبّتت في مجموعة.

أحداث البث

stream.start

وكيل بدأ بث رد.

stream.delta

جزء من محتوى متدفق:

{
  "type": "stream.delta",
  "conversation_id": "uuid",
  "encrypted_payload": "base64..."
}

stream.done

البث اكتمل مع الحمولة المشفرة الكاملة للتخزين.

stream.abort

البث أُلغي من قبل الوكيل.

stream.error

البث انتهت مهلته أو بلغ حداً.

أحداث العلاقات

relation.established

مستخدم جديد بدأ استخدام الوكيل:

{
  "type": "relation.established",
  "payload": {
    "user_id": "uuid",
    "display_name": "Alice",
    "avatar_url": "https://...",
    "language": "en",
    "referral_source": "invite_link",
    "public_key": "base64..."
  }
}

يُخزّن SDK الـ public_key من هذا الحدث تلقائياً.

relation.terminated

المستخدم قطع الاتصال بالوكيل:

{ "type": "relation.terminated", "payload": { "user_id": "uuid" } }

relation.suspended

المستخدم عُلّق من قبل المنشئ:

{ "type": "relation.suspended", "payload": { "user_id": "uuid" } }

relation.restored

المستخدم أُعيد من قبل المنشئ:

{ "type": "relation.restored", "payload": { "user_id": "uuid" } }

أحداث Artifact

artifact_response

المستخدم رد على artifact (إرسال نموذج، ضغط زر):

{
  "type": "artifact_response",
  "payload": {
    "conversation_id": "uuid",
    "message_id": "uuid",
    "ref_artifact": "artifact_id",
    "ref_action": "submit",
    "based_on_revision": 1,
    "values": { "name": "My Project" }
  }
}

artifact_update

وكيل حدّث artifact (توصيل WebSocket للعملاء البشريين).

artifact.expired

انتهى TTL لـ artifact:

{
  "type": "artifact.expired",
  "payload": {
    "conversation_id": "uuid",
    "message_id": "uuid",
    "artifact_id": "uuid"
  }
}

أحداث الوكيل

agent.governance

تغيّرت حالة حوكمة الوكيل (WebSocket فقط، لا يُسلّم عبر webhook):

{
  "type": "agent.governance",
  "payload": {
    "agent_template_id": "uuid",
    "governance_status": "suspended",
    "reason": "Policy violation"
  }
}

إذا كانت الحالة suspended أو banned، يُنهى اتصال WebSocket.

agent.status

تغيّرت حالة الوكيل (متصل/غير متصل).

agent.typing

الوكيل يكتب.

أحداث التفاعلات

reaction.update

تغيّرت التفاعلات على رسالة (حالة مجمّعة):

{
  "type": "reaction.update",
  "payload": {
    "message_id": "uuid",
    "reactions": [
      { "emoji": "thumbsup", "count": 3, "user_ids": ["uuid1", "uuid2", "uuid3"] }
    ]
  }
}

أحداث المجموعة

group.updated

تغيّرت معلومات المجموعة (الاسم، الصورة، الإعدادات):

{
  "type": "group.updated",
  "payload": {
    "conversation_id": "uuid",
    "changes": { "name": "New Group Name" }
  }
}

أحداث الجلسة

auth.expiring

تحذير: رمز الوصول على وشك الانتهاء. يجب على العميل التحديث عبر REST وإرسال auth.renew:

{ "type": "auth.expiring", "expires_in_seconds": 60 }

session.invalidated

الخادم أنهى الجلسة (الجهاز أُزيل، كلمة المرور تغيّرت، إلخ):

{
  "type": "session.invalidated",
  "payload": {
    "reason": "device_removed",
    "message": "Session terminated",
    "i18n_key": "error.session.invalidated"
  }
}

error

خطأ WebSocket عام:

{
  "type": "error",
  "payload": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "i18n_key": "error.rate_limited"
  }
}

توصيل الأحداث حسب النقل

الحدث	WebSocket	Webhook
message.new	نعم	نعم
relation.established	نعم	نعم
relation.terminated	نعم	نعم
relation.suspended	نعم	نعم
relation.restored	نعم	نعم
artifact_response	نعم	نعم
agent.governance	نعم	لا
reaction.update	نعم	لا
group.updated	نعم	لا
artifact.expired	نعم	لا
session.invalidated	نعم	لا
auth.expiring	نعم	لا

Long Polling يُسلّم نفس مجموعة أحداث Webhook.

الخطوات التالية

• نقاط REST — مرجع نقاط HTTP
• أكواد الأخطاء — جدول أكواد الأخطاء
• البث — دليل البث في SDK