العودة إلى لوحة التحكم

التوثيق

تعلّم كيفية استخدام Asyntai

مرجع API

أنشئ تكاملات مخصصة مع Asyntai REST API

الحصول على مفتاح API

يتطلب خطة مدفوعة: الوصول إلى API متاح في خطط Starter و Standard و Pro. عرض الأسعار

نظرة عامة

يتيح لك Asyntai API دمج دعم العملاء المدعوم بالذكاء الاصطناعي في أي تطبيق. أرسل رسائل واستقبل ردوداً ذكية مُدرَّبة على محتوى موقعك وقاعدة المعرفة.

المصادقة

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

قم بتضمين مفتاح API الخاص بك في الطلبات باستخدام إحدى هذه الطرق:

  • ترويسة Authorization (موصى بها): Authorization: Bearer YOUR_API_KEY
  • ترويسة X-API-Key: X-API-Key: YOUR_API_KEY

حافظ على سرية مفتاح API الخاص بك. يمكن لأي شخص يمتلك مفتاحك الوصول إلى حسابك عبر API. لا تكشفه أبداً في الكود من جانب العميل.

الرابط الأساسي

https://asyntai.com/api/v1/

نقاط النهاية

POST /chat/

أرسل رسالة واستقبل رداً مُنشأً بالذكاء الاصطناعي.

نص الطلب

{
  "message": "What are your business hours?",
  "session_id": "user_123",      // optional
  "website_id": 1                 // optional
}
المعامل النوع مطلوب الوصف
message string نعم رسالة المستخدم لإرسالها إلى الذكاء الاصطناعي
session_id string لا معرّف فريد للمحادثة. استخدم نفس session_id للحفاظ على سجل المحادثة.
website_id integer لا معرّف الموقع المحدد. إذا لم يُقدَّم، يُستخدم موقعك الأساسي.

الاستجابة

{
  "success": true,
  "response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
  "session_id": "user_123"
}

مثال (cURL)

curl -X POST https://asyntai.com/api/v1/chat/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your business hours?", "session_id": "user_123"}'

مثال (Python)

import requests

response = requests.post(
    "https://asyntai.com/api/v1/chat/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "message": "What are your business hours?",
        "session_id": "user_123"
    }
)

data = response.json()
print(data["response"])

مثال (JavaScript)

const response = await fetch("https://asyntai.com/api/v1/chat/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    message: "What are your business hours?",
    session_id: "user_123"
  })
});

const data = await response.json();
console.log(data.response);

GET /websites/

عرض جميع المواقع المرتبطة بحسابك.

الاستجابة

{
  "success": true,
  "websites": [
    {
      "id": 1,
      "name": "My Website",
      "domain": "example.com",
      "is_primary": true
    }
  ]
}

مثال (cURL)

curl https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /conversations/

استرجاع سجل المحادثة لجلسة محددة.

معاملات الاستعلام

المعامل النوع مطلوب الوصف
session_id string نعم معرّف الجلسة لاسترجاع السجل
limit integer لا الحد الأقصى للرسائل المُرجعة (الافتراضي: 50، الحد الأقصى: 100)

الاستجابة

{
  "success": true,
  "session_id": "user_123",
  "messages": [
    {
      "role": "user",
      "content": "What are your business hours?",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
      "timestamp": "2024-01-15T10:30:01Z"
    }
  ]
}

مثال (cURL)

curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /sessions/

عرض جلسات المحادثة الأخيرة. استخدم هذا لاكتشاف معرّفات الجلسات، والتي يمكنك تمريرها إلى /conversations/ لاسترجاع سجل الرسائل الكامل.

معاملات الاستعلام

المعامل النوع مطلوب الوصف
limit integer لا عدد الجلسات الأخيرة المُرجعة (الافتراضي: 20، الحد الأقصى: 100)
website_id string لا تصفية الجلسات حسب معرّف موقع محدد
source string لا تصفية حسب مصدر الجلسة: widget، api، whatsapp، instagram، messenger، gorgias، freshchat، zapier

الاستجابة

{
  "success": true,
  "sessions": [
    {
      "session_id": "session_abc123def",
      "source": "widget",
      "message_count": 5,
      "first_message": "What are your business hours?",
      "first_message_at": "2024-01-15T10:30:00Z",
      "last_message_at": "2024-01-15T10:35:00Z",
      "website_domain": "example.com"
    }
  ]
}

مثال (cURL)

curl "https://asyntai.com/api/v1/sessions/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /leads/

استرجاع العملاء المحتملين المجمعين — عناوين البريد الإلكتروني وأرقام الهواتف التي قدمها الزوار خلال محادثات الدردشة.

معاملات الاستعلام

المعامل النوع مطلوب الوصف
limit integer لا عدد العملاء المحتملين المُرجعين (الافتراضي: 50، الحد الأقصى: 100)
website_id string لا تصفية العملاء المحتملين حسب معرّف موقع محدد

الاستجابة

{
  "success": true,
  "leads": [
    {
      "session_id": "session_abc123def",
      "email": "visitor@example.com",
      "phone": "+1234567890",
      "page_url": "https://example.com/pricing",
      "started_at": "2024-01-15T10:30:00Z"
    }
  ]
}
الحقل النوع الوصف
session_id string معرف جلسة الدردشة. مرره إلى /conversations/ لرؤية سجل الدردشة الكامل.
email سلسلة نصية أو null عنوان البريد الإلكتروني المقدم من الزائر، أو null إذا لم يتم جمعه
phone سلسلة نصية أو null رقم الهاتف المقدم من الزائر، أو null إذا لم يتم جمعه
page_url سلسلة نصية أو null عنوان URL للصفحة التي كان الزائر يتحدث فيها
started_at string طابع زمني ISO 8601 لوقت بدء جلسة الدردشة

مثال (cURL)

curl "https://asyntai.com/api/v1/leads/?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

مثال (Python)

import requests

response = requests.get(
    "https://asyntai.com/api/v1/leads/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 20}
)

leads = response.json()["leads"]
for lead in leads:
    print(f"{lead['email'] or ''} | {lead['phone'] or ''}")

GET /account/

احصل على معلومات حسابك وإحصائيات الاستخدام.

الاستجابة

{
  "success": true,
  "account": {
    "email": "you@example.com",
    "plan": "starter",
    "messages_used": 150,
    "messages_limit": 2500
  }
}

مثال (cURL)

curl https://asyntai.com/api/v1/account/ \
  -H "Authorization: Bearer YOUR_API_KEY"

مواقع متعددة؟ نقاط نهاية قاعدة المعرفة تستخدم موقعك الأساسي افتراضياً. إذا كان لديك مواقع متعددة، مرّر website_id لاستهداف موقع محدد. يمكنك العثور على معرّفات مواقعك باستخدام GET /websites/.

حدود الرفع اليومية: تخضع عمليات رفع قاعدة المعرفة (نص، رابط، جدول بيانات) لحد يومي من الأحرف بناءً على خطتك. ينطبق هذا على إجمالي المحتوى المرفوع عبر جميع نقاط نهاية قاعدة المعرفة يومياً.

الخطة الأحرف/اليوم
Starter100,000
Standard500,000
Pro2,000,000

GET /knowledge/

عرض إدخالات قاعدة المعرفة الخاصة بك. هذه هي مصادر المحتوى التي يستخدمها روبوت المحادثة الذكي للإجابة على الأسئلة.

معاملات الاستعلام

المعامل النوع مطلوب الوصف
limit integer لا عدد الإدخالات المُرجعة (الافتراضي: 50، الحد الأقصى: 100)
website_id string لا التصفية حسب معرّف الموقع (الافتراضي: موقعك الأساسي)

الاستجابة

{
  "success": true,
  "entries": [
    {
      "id": "abc-123-def",
      "type": "text",
      "title": "Business Hours",
      "description": "Manual text content (150 words)",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ghi-456-jkl",
      "type": "url",
      "title": "About Us - Example",
      "description": "Content from https://example.com/about",
      "created_at": "2024-01-14T09:00:00Z"
    }
  ]
}

مثال (cURL)

curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /knowledge/text/

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

نص الطلب

{
  "title": "Return Policy",
  "content": "We offer a 30-day return policy on all items. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
  "website_id": "123"
}
المعامل النوع مطلوب الوصف
title string نعم عنوان لهذا الإدخال المعرفي
content string نعم المحتوى النصي (10 أحرف كحد أدنى)
website_id string لا الموقع المستهدف (الافتراضي: موقعك الأساسي)

الاستجابة

{
  "success": true,
  "id": "abc-123-def",
  "title": "Return Policy",
  "chunks_created": 1
}

مثال (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/text/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Return Policy", "content": "We offer a 30-day return policy..."}'

POST /knowledge/url/

أضف صفحة ويب إلى قاعدة المعرفة. سيتم جلب المحتوى واستخراجه تلقائياً.

نص الطلب

{
  "url": "https://example.com/faq",
  "website_id": "123"
}
المعامل النوع مطلوب الوصف
url string نعم الرابط لجلب المحتوى منه
website_id string لا الموقع المستهدف (الافتراضي: موقعك الأساسي)

الاستجابة

{
  "success": true,
  "id": "abc-123-def",
  "title": "FAQ - Example",
  "url": "https://example.com/faq",
  "chunks_created": 5
}

مثال (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/url/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/faq"}'

POST /knowledge/spreadsheet/

ارفع جدول بيانات CSV أو Excel (.xlsx) إلى قاعدة المعرفة. يصبح كل صف إدخالاً معرفياً منفصلاً، وهو مثالي لكتالوجات المنتجات وقوائم الأسئلة الشائعة وجداول الأسعار والأدلة.

الطلب

أرسل كـ multipart/form-data (رفع ملف)، وليس JSON.

المعامل النوع مطلوب الوصف
file ملف نعم ملف .csv أو .xlsx. يجب أن يكون الصف الأول عناوين الأعمدة. الحد الأقصى للصفوف لكل رفع: Starter 500، Standard 2,000، Pro 10,000. يتم اقتطاع الصفوف الزائدة.
website_id string لا الموقع المستهدف (الافتراضي: موقعك الأساسي)

الاستجابة

{
  "success": true,
  "id": "abc-123-def",
  "title": "products.csv",
  "rows_processed": 15,
  "chunks_created": 15
}

مثال (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@products.csv"

DELETE /knowledge/{id}/

حذف إدخال من قاعدة المعرفة. يمكن العثور على id من استجابة GET /knowledge/.

الاستجابة

{
  "success": true,
  "message": "Knowledge base entry deleted"
}

مثال (cURL)

curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

نصيحة: يمكنك أيضاً إدارة webhooks من إعدادات API الصفحة دون كتابة أي كود.

GET /webhooks/

عرض webhooks المسجلة لديك.

الاستجابة

{
  "success": true,
  "webhooks": [
    {
      "id": "abc-123-def",
      "url": "https://example.com/webhook",
      "events": ["message.received", "escalation.requested"],
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

مثال (cURL)

curl "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /webhooks/

سجّل webhook جديداً لاستقبال إشعارات الأحداث في الوقت الفعلي.

الأحداث المتاحة

الحدث الوصف
message.received أرسل زائر رسالة واستقبل رداً
conversation.started بدأت جلسة محادثة جديدة
escalation.requested أطلق الذكاء الاصطناعي تصعيداً إلى وكيل بشري
takeover.started تولّى وكيل بشري جلسة محادثة

نص الطلب

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "escalation.requested"],
  "website_id": "123"
}
المعامل النوع مطلوب الوصف
url string نعم رابط HTTPS لاستقبال طلبات webhook من نوع POST
events array نعم قائمة الأحداث للاشتراك فيها (انظر الجدول أعلاه)
website_id string لا الموقع المستهدف (الافتراضي: موقعك الأساسي)

الاستجابة

{
  "success": true,
  "webhook": {
    "id": "abc-123-def",
    "url": "https://example.com/webhook",
    "events": ["message.received", "escalation.requested"],
    "secret": "whsec_abc123...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

التحقق من webhooks: يتضمن كل webhook secret (يُعرض فقط عند الإنشاء). كل طلب POST إلى رابطك يتضمن X-Webhook-Signature ترويسة — HMAC-SHA256 لنص الطلب موقّع بسرّك.

مثال (cURL)

curl -X POST "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook", "events": ["message.received"]}'

DELETE /webhooks/{id}/

حذف webhook. يمكن العثور على id من استجابة GET /webhooks/.

الاستجابة

{
  "success": true,
  "message": "Webhook deleted"
}

مثال (cURL)

curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

استجابات الأخطاء

تتبع جميع استجابات الأخطاء هذا التنسيق:

{
  "success": false,
  "error": "Error message describing what went wrong"
}
رمز الحالة الوصف
400 طلب غير صالح - معاملات غير صحيحة أو حقول مطلوبة مفقودة
401 غير مصرّح - مفتاح API غير صالح أو مفقود
429 طلبات كثيرة جداً - تم الوصول إلى حد الرسائل لخطتك
503 الخدمة غير متاحة - خدمة الذكاء الاصطناعي غير متاحة مؤقتاً

حدود المعدل

استخدام API محدود بخطة اشتراكك:

  • Free: 100 رسالة/شهر
  • Starter ($39/شهر): 2,500 رسالة/شهر
  • Standard ($139/شهر): 15,000 رسالة/شهر
  • Pro ($449/شهر): 50,000 رسالة/شهر

تحتاج مساعدة؟

إذا كان لديك أي أسئلة أو واجهت مشاكل، تواصل معنا على hello@asyntai.com.