بوابة كيان دمج — API v1

إرسال رسالة

POST /api/v1/messages
{
  "instance": "INSTANCE_ID",
  "to": "9665XXXXXXXX",
  "type": "text",
  "text": "مرحباً"
}

الأنواع: text, image, video, audio, document, sticker, location, contact, poll, reaction. استخدم ترويسة Idempotency-Key بمعرف الطلب لمنع تكرار الرسالة عند إعادة المحاولة.

إرسال جماعي

POST /api/v1/messages/bulk
{"instance":"INSTANCE_ID","messages":[{"to":"9665XXXXXXXX","type":"text","text":"رسالة 1"},{"to":"9665YYYYYYYY","type":"text","text":"رسالة 2"}]}

الموقع

{"instance":"INSTANCE_ID","to":"9665XXXXXXXX","type":"location","latitude":24.7136,"longitude":46.6753,"name":"الرياض","address":"السعودية"}

جهة اتصال

{"instance":"INSTANCE_ID","to":"9665XXXXXXXX","type":"contact","name":"خدمة العملاء","contact_phone":"966500000000"}

استطلاع

{"instance":"INSTANCE_ID","to":"9665XXXXXXXX","type":"poll","question":"اختر موعداً","values":["صباحاً","مساءً"],"selectable_count":1}

فحص الأرقام

POST /api/v1/contacts/check
{"instance":"INSTANCE_ID","numbers":["9665XXXXXXXX"]}

الرسائل والوسائط

GET /api/v1/messages?instance=INSTANCE_ID
GET /api/v1/messages/MESSAGE_ID/media?instance=INSTANCE_ID
GET /api/v1/queue/QUEUE_ID

المجموعات

POST /api/v1/groups
{"instance":"INSTANCE_ID","subject":"فريق العمل","participants":["9665XXXXXXXX"]}

GET  /api/v1/groups/GROUP_JID?instance=INSTANCE_ID
POST /api/v1/groups/GROUP_JID/participants
GET  /api/v1/groups/GROUP_JID/invite?instance=INSTANCE_ID
POST /api/v1/groups/join

الإحصاءات

GET /api/v1/stats?instance=INSTANCE_ID&days=30

Webhooks

الأحداث: message.received وmessage.sent وmessage.ack وconnection.update وgroup.updated وgroup.participants. التوقيع في X-Kayan-Signature باستخدام HMAC-SHA256.