مرجع API
أنشئ تكاملات مخصصة مع Asyntai REST 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/.
حدود الرفع اليومية: تخضع عمليات رفع قاعدة المعرفة (نص، رابط، جدول بيانات) لحد يومي من الأحرف بناءً على خطتك. ينطبق هذا على إجمالي المحتوى المرفوع عبر جميع نقاط نهاية قاعدة المعرفة يومياً.
| الخطة | الأحرف/اليوم |
|---|---|
| Starter | 100,000 |
| Standard | 500,000 |
| Pro | 2,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.