BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/messaging.mdx
View on GitHub---
title: "المراسلة"
description: "تحدث إلى وكيلك عبر Slack أو Microsoft Teams أو تفاعلات Discord أو البريد الإلكتروني أو Telegram أو WhatsApp."
---
# المراسلة
قم بتوصيل وكيلك بـ Slack أو Microsoft Teams أو تفاعلات Discord أو البريد الإلكتروني أو Telegram أو WhatsApp. إنه الوكيل نفسه بنفس الذاكرة والأدوات وسجل المحادثات.
> **نطاق الدعم بدقة:** يتحقق Teams من رموز JWT الرسمية لـ Bot Framework ويرد في المحادثة الأصلية. يدعم Discord أوامر الشرطة المائلة عبر تفاعلات HTTP الموقعة بـ Ed25519 مع إقرار مؤجل؛ ولا يستقبل رسائل الخادم العادية أو الرسائل المباشرة من دون تشغيل Gateway. يحتفظ Telegram بـ `message_thread_id` ويستخدم WhatsApp قيمة `wamid` الواردة للردود السياقية.
>
> يتطلب Teams القيم `MICROSOFT_TEAMS_APP_ID` و`MICROSOFT_TEAMS_APP_PASSWORD` و`MICROSOFT_TEAMS_ALLOWED_TENANT_IDS`. ويتطلب Discord القيم `DISCORD_APPLICATION_ID` و`DISCORD_PUBLIC_KEY`. كما يتطلب Telegram القيمة `TELEGRAM_WEBHOOK_SECRET` ويتطلب WhatsApp القيمة `WHATSAPP_APP_SECRET` بالإضافة إلى بيانات الاعتماد الحالية.
> **هل تستخدم قالب الإرسال؟** تم إعداد كل هذا لك في **الإدارة → المراسلة**. انقر لربط كل نظام أساسي — لن تحتاج إلى قراءة بقية هذه الصفحة إلا إذا كنت تقوم بتخصيص القالب الخاص بك أو إنشائه. راجع [Dispatch](/docs/dispatch) أو [Dispatch template reference](/docs/template-dispatch).
## ما يمكنك فعله {#what-you-can-do}
- **أرسل بريدًا إلكترونيًا إلى وكيلك** على عنوان مثل `agent@yourcompany.com` — حيث يتم الرد داخل سلسلة الرسائل، تمامًا كما يفعل زميل العمل.
- **إرسال رسالة إلى وكيلك** في سلسلة رسائل — ستتم قراءتها والتفاعل معك عندما تطلب ذلك.
- **إرسال رسالة مباشرة للوكيل على Slack**، أو `@mention` في أي قناة.
- **راسل الوكيل على Telegram أو WhatsApp** من هاتفك.
- **نفس الوكيل، نفس الذاكرة.** كل ما تقوله على Slack يتم تذكره عندما ترسله بالبريد الإلكتروني لاحقًا. تشترك دردشة الويب والرسائل الخارجية في سجل موضوع واحد.
- **نفّذ إجراءات في أدوات أخرى انطلاقًا من رسالة.** يمكن أن ينتهي `@mention` بصف في Notion أو مهمة في Jira أو سجل في HubSpot — راجع [`@mention` في Slack ← صف في Notion](#slack-to-notion) للمثال الكامل.
- للحصول على تنبيهات أحادية الاتجاه داخل التطبيق (رمز الجرس، webhooks)، راجع [Notifications](/docs/notifications).
<Diagram id="doc-block-13wwymq" title={"العديد من القنوات، وكيل واحد"} summary={"تنضم كل منصة إلى نفس حلقة الوكيل ونفس سجل سلاسل الرسائل SQL - لذلك تواصل رسالة مباشرة Slack وبريد إلكتروني نفس المحادثة."}>
```html
<div class="msg-fanin">
<div class="diagram-col">
<div class="diagram-node">Slack</div>
<div class="diagram-node">Email</div>
<div class="diagram-node">Telegram</div>
<div class="diagram-node">WhatsApp</div>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel center" data-rough>
<span class="diagram-pill accent">حلقة وكيل واحدة</span
><small class="diagram-muted">نفس الذاكرة · نفس الأدوات</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-box" data-rough>
سجل محادثة SQL واحد<br /><small class="diagram-muted"
>web chat + external messages share it</small
>
</div>
</div>
```
```css
.msg-fanin {
display: flex;
align-items: center;
gap: 14px;
flex-wrap: wrap;
}
.msg-fanin .diagram-col {
display: flex;
flex-direction: column;
gap: 8px;
}
.msg-fanin .center {
display: flex;
flex-direction: column;
align-items: center;
gap: 4px;
}
```
</Diagram>
## إعداد Slack {#slack}
### ما ستحتاج إليه
- مساحة عمل Slack حيث يمكنك تثبيت التطبيقات (وصول المشرف)
- حوالي 5 دقائق
### الخطوات
1. انتقل إلى **[api.slack.com/apps](https://api.slack.com/apps)** وانقر على **إنشاء تطبيق جديد** → **من البداية**. أطلق عليه اسمًا (على سبيل المثال، "الوكيل") واختر مساحة العمل الخاصة بك.
2. في الشريط الجانبي الأيسر، افتح **OAuth والأذونات**. ضمن **نطاقات الرموز المميزة للبوت**، أضف:
- `chat:write` — يتيح للوكيل إرسال الرسائل
- `app_mentions:read` — يتيح للوكيل معرفة متى يتم ذكره @ (اختياري)
- `im:history` — يتيح للوكيل قراءة الرسائل المباشرة المرسلة إليه
- `users:read.email` — اختياري؛ تساعد القوالب مثل البريد في التحقق من البريد الإلكتروني للمرسل Slack للحصول على هوية قائمة انتظار المسودة
3. انقر فوق **التثبيت على مساحة العمل** أعلى تلك الصفحة. سوف يمنحك Slack **رمز Bot User OAuth** الذي يبدأ بـ `xoxb-`. انسخه.
4. انتقل إلى **المعلومات الأساسية** في الشريط الجانبي وانسخ **سر التوقيع**.
5. افتح إعدادات تطبيقك (أو لوحة متغيرات البيئة الخاصة بموفر الاستضافة) والصق:
- `SLACK_BOT_TOKEN` — الرمز المميز `xoxb-…`
- `SLACK_SIGNING_SECRET` — سر التوقيع
- `SLACK_ALLOWED_TEAM_IDS` — موصى به في الإنتاج؛ يُسمح بمعرفات مساحة العمل/الفريق Slack المفصولة بفواصل بإرسال الأحداث
- `SLACK_ALLOWED_API_APP_IDS` — موصى به لتطبيقات مساحات العمل المتعددة؛ يُسمح لمعرفات تطبيقات Slack المفصولة بفواصل باستخدام سر التوقيع هذا
6. بالعودة إلى Slack، افتح **اشتراكات الأحداث**، وقم بتشغيلها، ثم الصق هذا الطلب URL:
```نص
https://your-app.example.com/_agent-native/integrations/slack/webhook
```
ثم ضمن **الاشتراك في أحداث الروبوت**، أضف `message.im` (للرسائل المباشرة) واختياريًا `app_mention` (لإشارات القناة). احفظ.
7. أرسل إلى الروبوت الخاص بك رسالة مباشرة في Slack. ينبغي الرد.
### اختياري: يتم فتح التطبيق
يتيح تطبيق Slack للتطبيق استبدال معاينة الرابط العادي لـ Slack بمعاينة أكثر ثراءً
معاينة. يستخدم Clips هذا لمعاينات الفيديو القابلة للتشغيل بنمط Loom.
أضف نطاقات الروبوت الإضافية هذه عندما يحتاج تطبيقك إلى النشر:
- `links:read` - يتيح لـ Slack إخطار التطبيق عند نشر النطاقات المسجلة
- `links:write` - يتيح للتطبيق استبدال المعاينة الافتراضية لـ Slack
- `links.embed:write` - يتيح للتطبيق تضمين الوسائط/المشغل المعتمد URLs
ثم اشترك في حدث `link_shared` وقم بتسجيل نطاقات التطبيق العامة الخاصة بك
ضمن **مجالات فتح التطبيق**. بالنسبة للمعاينات القابلة للتشغيل لـ Clips فقط، قم بتعيين Slack
اطلب اشتراكات الأحداث URL إلى:
```text
https://your-clips.example.com/api/slack/unfurl
```
يحتوي تطبيق Slack على طلب API واحد للأحداث وهو URL. إذا كان يجب على نفس تطبيق Slack التعامل مع
يتم نشر كل من أحداث محادثة الوكيل والمقاطع، وتوجيه أحداث Slack من خلال
المرسل الذي يرسل أحداث الرسالة إلى `/_agent-native/integrations/slack/webhook`
وأحداث `link_shared` إلى معالج نشر Clips.
### نصائح
- **إشارات القناة** — استخدم @mention لبدء العمل. يجب أن تتضمن كل رسالة قناة تريد من الوكيل معالجتها إشارة صريحة؛ لا تستدعيه الردود العادية في السلاسل أو الدردشة العامة.
- **الرسائل المباشرة** — الرسائل الخاصة المقبولة هي محادثات سرية، وتتطلب عضوًا موثّقًا في المؤسسة أو هوية Slack مرتبطة.
- **الهوية** — يمكن للرسائل الخاصة ربط بريد Slack الموثق بالمستخدم نفسه في التطبيق؛ تستخدم القنوات المُدارة هوية الخدمة والسياسة الخاصة بها.
- **قوائم الإنتاج المسموح بها** — قم بتعيين `SLACK_ALLOWED_TEAM_IDS`، وبالنسبة لتطبيقات Slack المشتركة، `SLACK_ALLOWED_API_APP_IDS` بحيث لا يمكن إعادة استخدام سر التوقيع الصالح بواسطة مساحة عمل غير متوقعة.
- **نشر تطبيق Clips** — تستخدم مقاطع Agent-Native القابلة للتثبيت لـ Slack `SLACK_CLIENT_ID`، و`SLACK_CLIENT_SECRET`، و`SLACK_SIGNING_SECRET`، و`/api/slack/oauth/callback`. تحصل كل مساحة عمل Slack متصلة على رمز الروبوت المشفر الخاص بها في `app_secrets`؛ `SLACK_BOT_TOKEN` ما هو إلا نسخة احتياطية قديمة لمساحة عمل واحدة.
### الإعداد المُدار عبر Add to Slack
OAuth المُدار هو الإعداد الموصى به. من **الإدارة → المراسلة**، اختر
**Agent manifest** لتنزيل ملف `agent-native-slack-manifest.json` الخاص بمضيفك،
ثم استورده من **App Manifest** في Slack. يفعّل الملف تجربة `agent_view` الحالية
وعلامة تبويب **Messages** قابلة للكتابة للرسائل المباشرة. تحقّق من هذه النطاقات:
لا يتضمن البيان أيقونة التطبيق. ضمن **Basic Information → Display Information**،
ارفع أيقونة Agent-Native كي تتطابق قائمة Agents مع هوية المنتج. يمكنك استخدام
`icon-512.svg` العام للتطبيق كمصدر وتحويله إلى تنسيق رفع يدعمه Slack عند الحاجة.
```text
assistant:write
app_mentions:read
channels:history
channels:read
chat:write
files:read
groups:history
groups:read
im:history
im:read
mpim:history
mpim:read
pins:read
reactions:read
users:read
users:read.email
```
اضبط OAuth Redirect URL على
`https://your-app.example.com/_agent-native/integrations/slack/oauth/callback`،
وEvent Subscriptions Request URL على
`https://your-app.example.com/_agent-native/integrations/slack/webhook`،
وInteractivity Request URL على
`https://your-app.example.com/_agent-native/integrations/slack/interactions`.
اشترك في `app_home_opened` و`app_context_changed` و`app_mention`
و`message.im`.
بعد إعداد `SLACK_CLIENT_ID` و`SLACK_CLIENT_SECRET`
و`SLACK_SIGNING_SECRET`، افتح **الإدارة → المراسلة** وانقر **Add to Slack**.
يُخزّن كل تثبيت رمزًا مشفرًا منفصلًا، وتفصل مفاتيح المحادثة بين مساحة العمل
والتطبيق والقناة وسلسلة الرسائل.
أعد تثبيت تطبيق Slack بعد تغيير البيان أو النطاقات أو الأحداث أو Agent view أو
علامة تبويب Messages. يستخدم `app_home_opened` لاكتشاف فتح الرسائل المباشرة،
ويضيف `app_context_changed` سياق العرض الحالي، ويسلّم `message.im` الرسائل الخاصة.
قد يخفي مسؤولو Slack الوكلاء المثبتين عن المؤسسة، كما يمكن لكل مستخدم إخفاؤهم من
الشريط العلوي. إذا نجح التثبيت ولم يظهر الوكيل، فتحقق من عناصر التحكم هذه أو افتحه
من **Tools → Apps**.
لا تُقبل الرسائل الخاصة الشخصية في Slack إلا من عضو موثّق في مؤسسة Agent-Native
أو من هوية Slack مرتبطة مسبقًا بذلك العضو. أما سياسات وميزانيات هوية الخدمة الخاصة
بالقناة فهي منفصلة.
يجب أن تتضمن كل رسالة قناة إشارة صريحة إلى الوكيل؛ ولا تستدعيه الردود العادية
في السلاسل أو محادثات القناة العامة. يحمّل الوكيل سياقًا محدودًا مع التفاعلات
ومراجع الملفات فقط، ويعرض خطة وتقدمًا مباشرًا مع أزرار الإلغاء والموافقة/الرفض.
الرسائل الخاصة تستخدم هوية المستخدم الشخصية، بينما تستخدم القنوات المُدارة هوية
خدمة صريحة وسياسات للضيوف وSlack Connect والنموذج الافتراضي. ذاكرة القناة صريحة
ومعزولة ولا تُحفظ تلقائيًا. تحتفظ الإجراءات الدورية التي تُنشأ من القناة بوجهة
Slack، وتفرض ميزانيات يومية أو شهرية للمؤسسة أو الطالب أو القناة مع سجل تدقيق كامل.
يتيح `assistant:write` أحداث سياق Agent View، بينما يتيح `chat:write` الردود
وتحديثات الحالة المباشرة.
### مثال عملي كامل: `@mention` في Slack ← صف في Notion {#slack-to-notion}
بعد أن تعمل إشارات Slack، يكون الطلب التالي الأكثر شيوعًا صيغة من صيغ _«عندما أشير إلى الوكيل بـ `@mention` داخل سلسلة رسائل، خذ ما كتبته وأضفه صفًا في قاعدة بيانات Notion الخاصة بي»_. هذا ممكن بالفعل — استقبال Slack، وواجهة مزوّد Notion، وإجراءات التطبيق كلها مدمجة — لكنه يتطلب ربط ثلاثة أجزاء بالترتيب الصحيح، واثنان منها يفشلان بصمت إذا تجاوزتهما.
كل ما يظهر بين `<ANGLE_BRACKETS>` أدناه هو عنصر نائب. لا تلصق أبدًا سرًا حقيقيًا من Notion في الشيفرة المصدرية أو في ملف `.env` مُودَع في المستودع أو في رسالة دردشة.
#### 1. اجعل الإشارات تصل إلى التطبيق
أكمل [إعداد Slack](#slack) وتأكد من أن `@mention` في قناة يحصل على رد قبل أن تبدأ بـ Notion. هناك سلوكان مهمان لبقية المثال:
- الرسالة التي تحتوي على `@mention` هي الاستدعاء، ونصها هو ما يراه الوكيل.
- يجب أن تتضمن كل رسالة لاحقة في السلسلة إشارة صريحة إلى الوكيل؛ فالردود العادية اللاحقة لا تصل إليه. أعد استخدام `@mention` لكل طلب جديد.
#### 2. أتِح إجراءات واجهة المزوّد
يأتي Core بإعداد مسبق لمزوّد Notion (عنوان URL الأساسي، وترويسة `Notion-Version`، والمصادقة، وروابط التوثيق)، لكن الإجراءات الثلاثة التي تتيح للوكيل استخدامه — `provider-api-catalog` و`provider-api-docs` و`provider-api-request` — هي **تصدير مسار فرعي اختياري**. التطبيق الذي لم يضِفها مطلقًا لا يملك أي طريق إلى Notion، وسيقول الوكيل إنه لا يملك أداة Notion. هذه هي الخطوة التي يفوّتها معظم الناس.
أضِف بيئة تشغيل المزوّد:
```ts
// server/lib/provider-api.ts
import { createProviderApiRuntime } from "@agent-native/core/provider-api";
const runtime = createProviderApiRuntime({
appId: "<YOUR_APP_ID>",
providerIds: ["notion"],
});
export function getProviderApiRuntime() {
return runtime;
}
```
ثم أضِف ملف إجراء رفيعًا لكل معرّف إجراء. جميع خيارات المصنع اختيارية، لذا يكفي في كل ملف استدعاء واحد:
```ts
// actions/provider-api-catalog.ts
import { createProviderApiCatalogAction } from "@agent-native/core/provider-api/actions/provider-api";
import { getProviderApiRuntime } from "../server/lib/provider-api.js";
export default createProviderApiCatalogAction(getProviderApiRuntime());
```
```ts
// actions/provider-api-docs.ts
import { createProviderApiDocsAction } from "@agent-native/core/provider-api/actions/provider-api";
import { getProviderApiRuntime } from "../server/lib/provider-api.js";
export default createProviderApiDocsAction(getProviderApiRuntime());
```
```ts
// actions/provider-api-request.ts
import { createProviderApiRequestAction } from "@agent-native/core/provider-api/actions/provider-api";
import { getProviderApiRuntime } from "../server/lib/provider-api.js";
export default createProviderApiRequestAction(getProviderApiRuntime());
```
تُكتشف الملفات الموجودة في `actions/` تلقائيًا — لا يوجد سجل يحتاج إلى تعديل. راجع [إعادة استخدام مصانع الإجراءات في Core](/docs/integrations#provider-api-factories) لتضييق قائمة المزوّدين أو إتاحتها عبر HTTP.
#### 3. ضع مفتاح Notion في الخزنة لا في `.env`
أنشئ تكاملًا داخليًا على **[notion.so/my-integrations](https://www.notion.so/my-integrations)** وانسخ سرّه. ثم في تطبيقك افتح **Settings → API Keys & Connections**، وأضِف مفتاحًا باسم `NOTION_API_KEY` تمامًا، والصق القيمة، واختر النطاق:
- **Personal** — لا يستطيع استخدامه إلا التشغيلات التي تجري باسمك.
- **Workspace** — مشترك مع المؤسسة. اختر هذا إذا كان غيرك سيشير إلى الوكيل، لأن تشغيل Slack يجري باسم مالك التكامل لا باسم من كتب الرسالة.
تحلّ بيئة تشغيل المزوّد بيانات الاعتماد من الخزنة المشفّرة بهذا الترتيب — شخصي، ثم مؤسسة، ثم مساحة عمل — و**لا تقرأ `process.env` إطلاقًا وعن قصد**، لأن متغيّر بيئة على مستوى النشر سيكون مشتركًا بين جميع مستخدمي تطبيق متعدد المستأجرين. لن يُؤخذ سطر `NOTION_API_KEY` في `.env` بعين الاعتبار هنا.
#### 4. شارك قاعدة البيانات مع التكامل
في Notion، افتح قاعدة البيانات المستهدفة ثم أضِف تكاملك من **••• → Connections →**. تخطّي هذه الخطوة هو أكثر أعطال Notion شيوعًا وأكثرها تضليلًا: تُجيب الواجهة بـ **404** لا 403، فيبدو الأمر وكأن معرّف قاعدة البيانات خاطئ. يحمل مدخل الكتالوج نصّ المعالجة هذا، ويضيفه `provider-api-request` إلى حقل `guidance` في أي استجابة 401 أو 403 أو 404.
تجد معرّف قاعدة البيانات في عنوان URL الخاص بها — وهو السلسلة المكوّنة من 32 حرفًا قبل `?`.
#### 5. اطلب من وكيلك أن يبنيه
هذا هو الجزء الذي لا تخبرك به أي شاشة إعداد: لست أنت من يربط النصفين، بل تطلب السلوك المطلوب. في دردشة الوكيل داخل التطبيق:
> أضِف إجراءً باسم `add-notion-row` يضيف صفًا إلى قاعدة بيانات Notion `<NOTION_DATABASE_ID>` عبر واجهة المزوّد. يجب أن يستقبل نص الرسالة، وكاتبها في Slack، ورابطًا يعود إلى رسالة Slack. ثم حدِّث `AGENTS.md` بحيث تستدعي هذا الإجراء وترد بعنوان صفحة Notion الجديدة عندما يشير إليك أحد بـ `@mention` في Slack ويطلب تسجيل شيء أو حفظه.
ما ينبغي أن يكتبه الوكيل هو **إجراء واحد** — لا مسار Nitro، ولا `fetch` من المتصفح:
```ts
// actions/add-notion-row.ts
import { defineAction } from "@agent-native/core/action";
import { z } from "zod";
import { getProviderApiRuntime } from "../server/lib/provider-api.js";
export default defineAction({
description:
"Append one row to the team's Notion database, e.g. from a Slack reply.",
schema: z.object({
databaseId: z.string().describe("Notion database id"),
text: z.string().min(1).describe("Body of the message to record"),
author: z.string().optional().describe("Who said it"),
sourceUrl: z.string().url().optional().describe("Link back to Slack"),
}),
run: async ({ databaseId, text, author, sourceUrl }) => {
const runtime = getProviderApiRuntime();
const database = await runtime.executeRequest({
provider: "notion",
method: "GET",
path: `/databases/${databaseId}`,
});
if (!database.response.ok) {
throw new Error(
`Notion rejected the database lookup (${database.response.status}). ${database.guidance}`,
);
}
const dataSourceId = (
database.response.json as { data_sources?: { id: string }[] }
)?.data_sources?.[0]?.id;
if (!dataSourceId) {
throw new Error("That Notion database has no readable data source.");
}
const created = await runtime.executeRequest({
provider: "notion",
method: "POST",
path: "/pages",
body: {
parent: { data_source_id: dataSourceId },
properties: {
Name: { title: [{ text: { content: text.slice(0, 200) } }] },
...(author
? { Author: { rich_text: [{ text: { content: author } }] } }
: {}),
...(sourceUrl ? { Source: { url: sourceUrl } } : {}),
},
},
});
if (!created.response.ok) {
throw new Error(
`Notion rejected the new row (${created.response.status}). ${created.guidance}`,
);
}
return created.response.json;
},
});
```
ثلاث تفاصيل في هذا المثال أساسية:
- ترتبط الصفوف في إصدارات Notion الحالية بـ**مصدر بيانات** داخل قاعدة البيانات، لذا اقرأ قاعدة البيانات أولًا واستخدم `data_sources[0].id` الخاص بها كأب. تمرير معرّف قاعدة البيانات مباشرةً كأب هو صيغة الواجهة القديمة.
- يعيد `executeRequest` أخطاء المزوّد بدل رميها، لذا تحقّق بنفسك من `response.ok` ومرّر قيمة `guidance` المعادة — فهناك تصل تلميحة «شارك قاعدة البيانات».
- يجب أن تطابق أسماء الخصائص (`Name` و`Author` و`Source`) أعمدة قاعدة بياناتك تمامًا، وأن تطابق الأنواع أيضًا. اجعل الوكيل يقرأ `properties` الخاصة بقاعدة البيانات أولًا بدل التخمين.
الجزء الخاص بـ `AGENTS.md` ليس اختياريًا. من دونه يملك الوكيل الأداة لكن لا سبب لديه لاستخدامها حين تقول رسالة في Slack «سجّل هذا».
#### 6. تأكّد من نجاحه، وماذا تفحص عند الفشل
في قناة Slack التي يوجد فيها الوكيل، اكتب `@YourAgent سجّل هذا في Notion: <SOME_TEXT>`. التشغيل الناجح يرد داخل السلسلة بعنوان الصفحة الجديدة، ويظهر الصف في Notion.
عندما لا ينجح:
| ما تراه | أين تبحث |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| لا يرد Slack إطلاقًا | لم تصل الإشارة إلى التطبيق أصلًا. أعِد فحص Request URL وسر التوقيع في [إعداد Slack](#slack) — هذه ليست مشكلة Notion. |
| يرد الوكيل لكنه يقول إنه لا يملك أداة Notion | الخطوة 2. لم تُضَف إجراءات واجهة المزوّد إلى `actions/` مطلقًا. |
| `notion credential not configured. Tried: NOTION_API_KEY` | الخطوة 3. المفتاح موجود في `.env`، أو محفوظ بنطاق **Personal** لحساب غير الحساب الذي يجري التشغيل باسمه. احفظه بنطاق **Workspace**. |
| يرد Notion بـ `404` | الخطوة 4. لم تُشارَك قاعدة البيانات مع التكامل. |
| يرد Notion بـ `400` بخصوص الخصائص | أسماء الخصائص أو أنواعها في الإجراء لا تطابق أعمدة قاعدة البيانات. |
| نجح مرة، ثم جرى تجاهل رد لاحق في السلسلة | هذا متوقّع. يجب أن تتضمن كل رسالة تريد من الوكيل معالجتها إشارة صريحة — أعد استخدام `@mention`. |
## إعداد تيليجرام {#telegram}
### ما ستحتاج إليه
- تطبيق Telegram على هاتفك
- حوالي 3 دقائق
### الخطوات
1. افتح تيليجرام وأرسل رسالة **[@BotFather](https://t.me/BotFather)**.
2. أرسل `/newbot` واتبع المطالبات لتسمية الروبوت الخاص بك. سوف يقوم BotFather بالرد باستخدام **رمز HTTP API**. انسخه.
3. في متغيرات بيئة تطبيقك، قم بتعيين:
- `TELEGRAM_BOT_TOKEN` — الرمز المميز من BotFather
4. بعد النشر، قم بتسجيل خطاف الويب بواسطة `POST`ing في تطبيقك على:
```نص
POST https://your-app.example.com/_agent-native/integrations/telegram/setup
```
يؤدي هذا إلى مطالبة Telegram بإرسال رسائل إلى خطاف الويب الخاص بتطبيقك. ما عليك سوى القيام بذلك مرة واحدة في كل عملية نشر.
5. ابحث عن الروبوت الخاص بك في Telegram (ابحث عن اسم المستخدم الذي قدمه لك BotFather) وأرسل إليه رسالة.
## إعداد البريد الإلكتروني {#email}
يعد البريد الإلكتروني أقوى عملية تكامل - حيث يحصل وكيلك على عنوانه الخاص، ويرد عليه في سلسلة المحادثات، ويمكن إرسال نسخة إليه في المحادثات، ويستخدم البريد الإلكتروني للمرسل كهوية له. لا حاجة لأمر `/link`.
### ما ستحتاج إليه
- النطاق الذي تتحكم فيه (أو يمكنك استخدام نطاق فرعي مجاني لإعادة الإرسال - انظر أدناه)
- حساب به **Resend** أو **SendGrid** للتعامل مع البريد الوارد والبريد الصادر
- حوالي 10 دقائق
### الخطوات (مع إعادة الإرسال — الأسهل)
1. قم بالتسجيل في **[resend.com](https://resend.com)**. الطبقة المجانية كافية للبدء.
2. اختر الشكل الذي سيبدو عليه عنوان البريد الإلكتروني للوكيل:
- **الأسهل:** استخدام عنوان `<your-slug>.resend.app` مجاني — لا حاجة إلى DNS.
- **العلامة التجارية:** أضف نطاقًا مخصصًا (مثل `yourcompany.com`) في صفحة **النطاقات** الخاصة بإعادة الإرسال واتبع خطوات DNS.
3. في إعادة الإرسال، افتح **Webhooks** → **إضافة نقطة نهاية** وأشر إليها:
```النص
https://your-app.example.com/_agent-native/integrations/email/webhook
```
اشترك في حدث **`email.received`**. ستمنحك إعادة الإرسال سر التوقيع — انسخه.
4. في متغيرات بيئة تطبيقك، قم بتعيين:
- `EMAIL_AGENT_ADDRESS` — العنوان الذي يتلقى الوكيل البريد عليه (على سبيل المثال، `agent@yourcompany.com`)
- `RESEND_API_KEY` — مفتاح إعادة إرسال API الخاص بك
- `EMAIL_INBOUND_WEBHOOK_SECRET` — سر التوقيع من إعادة الإرسال (موصى به؛ يستخدم للتحقق من التوقيع)
5. أرسل بريدًا إلكترونيًا إلى عنوان الوكيل. سيتم الرد في نفس الموضوع.
### الخطوات (باستخدام SendGrid)
1. قم بالتسجيل في **[sendgrid.com](https://sendgrid.com)**.
2. أضف سجل MX لنطاقك حتى يتدفق البريد الوارد إلى SendGrid:
```نص
MX yourcompany.com → mx.sendgrid.net (الأولوية 10)
```
3. افتح **الإعدادات ← التحليل الوارد**، انقر على **إضافة مضيف وURL**، وعيّن الوجهة على:
```نص
https://your-app.example.com/_agent-native/integrations/email/webhook
```
4. ضبط متغيرات البيئة:
- `EMAIL_AGENT_ADDRESS` — العنوان الذي يتلقاه الوكيل على
- `SENDGRID_API_KEY` — مفتاح SendGrid API الخاص بك
- `EMAIL_INBOUND_WEBHOOK_SECRET` — سر توقيع Svix الاختياري إذا قمت بتكوين webhooks الموقع
5. أرسل بريدًا إلكترونيًا إلى عنوان الوكيل.
### نصائح
- **CC الوكيل** لإحضاره إلى سلسلة رسائل. عندما يتم إرسال نسخة إلى الوكيل، فسوف يقوم بالرد على الكل حتى يرى سلسلة المحادثات بأكملها الرد.
- **الترابط يعمل فقط** — يستخدم الوكيل رؤوس `Message-ID` / `In-Reply-To` / `References` القياسية، لذا تظل الردود في سلسلة الرسائل الصحيحة في أي عميل بريد إلكتروني.
- **الهوية هي البريد الإلكتروني للمرسل.** إذا أرسل `alice@acme.com` بريدًا إلكترونيًا إلى الوكيل، فهذه _هي_ هويتها - لا يوجد رابط أو تدفق اشتراك.
- **الردود المنسّقة** — يتم عرض Markdown في استجابة الوكيل على هيئة HTML في البريد الإلكتروني.
- **المجالات المسموح بها** — تقييد من يمكنه إرسال بريد إلكتروني إلى الوكيل عن طريق تعيين `allowedDomains` في تكوين التكامل؛ يتم إسقاط الرسائل من النطاقات الأخرى.
- **حد السعر** — 20 رسالة واردة في الساعة لكل مرسل.
## إعداد واتساب {#whatsapp}
### ما ستحتاج إليه
- حساب مطور Meta (Facebook)
- رقم هاتف يمكنك تخصيصه للبوت
- حوالي 15 دقيقة (يحتوي إعداد Meta على معظم الخطوات)
### الخطوات
1. انتقل إلى **[Meta Developer Portal](https://developers.facebook.com/)**، وانقر على **إنشاء تطبيق**، واختر نوع **الأعمال**.
2. أضف منتج **WhatsApp** إلى تطبيقك وقم بتكوين رقم هاتف لاستخدامه كمرسل.
3. من صفحة إعداد WhatsApp، احصل على:
- **رمز الدخول** (الرمز المؤقت مناسب للاختبار؛ أنشئ رمزًا مميزًا دائمًا قبل بدء البث المباشر)
- **معرف رقم الهاتف**
4. اختر أي سلسلة عشوائية لاستخدامها كرمز تحقق — ستدخل نفس القيمة في مكانين أدناه.
5. في متغيرات بيئة تطبيقك، قم بتعيين:
- `WHATSAPP_ACCESS_TOKEN` — رمز الوصول الخاص بك
- `WHATSAPP_PHONE_NUMBER_ID` — معرف رقم الهاتف
- `WHATSAPP_VERIFY_TOKEN` — السلسلة العشوائية التي اخترتها
6. بالرجوع إلى إعدادات WhatsApp الخاصة بـ Meta، افتح قسم webhook وقم بتعيين:
```نص
رد الاتصال URL: https://your-app.example.com/_agent-native/integrations/whatsapp/webhook
رمز التحقق: نفس السلسلة العشوائية التي قمت بتعيينها كـ WHATSAPP_VERIFY_TOKEN
```
اشترك في الحقل `messages`.
7. أرسل رسالة واتساب إلى رقم هاتف الروبوت.
## استخدم Dispatch باعتباره البريد الوارد المركزي لوكيلك {#dispatch}
إذا كنت تقوم بتشغيل العديد من تطبيقات الوكيل الأصلية (البريد والتقويم والتحليلات وما إلى ذلك)، فإن النمط الموصى به هو إعداد المراسلة على **[Dispatch](/docs/dispatch)** (راجع أيضًا [template reference](/docs/template-dispatch)) والسماح لها بتوجيه العمل إلى تطبيقات المجال الخاصة بك عبر [A2A](/docs/a2a-protocol).
لماذا هذا لطيف:
- **وكيل واحد، صندوق وارد واحد.** تتدفق جميع قنواتك (Slack، البريد الإلكتروني، Telegram، WhatsApp) إلى Dispatch. يمكنك إعداد عمليات التكامل مرة واحدة فقط.
- **مندوبو Dispatch.** اسأل "تلخيص عمليات الاشتراك في الأسبوع الماضي" — تستدعي Dispatch وكيل التحليلات. اطلب "صياغة رد على أليس" — تتصل ديسباتش بوكيل البريد.
- **النقرات، وليس التكوين.** تحتوي صفحة **الإدارة → المراسلة** في Dispatch على أزرار اتصال لكل نظام أساسي مع حقول env-var المضمنة فيها.
إذا لم تكن بحاجة إلى منسق، فيمكن لأي قالب منفرد توصيل الرسائل مباشرةً باستخدام env vars في هذه الصفحة.
---
## للمطورين {#for-developers}
كل ما هو أدناه هو المرجع الفني. إذا كنت قد انتهيت من خطوات الإعداد المذكورة أعلاه، فيمكنك التوقف هنا إلا إذا كنت تقوم بتخصيص المكون الإضافي للتكامل أو إنشاء المحول الخاص بك.
### كيفية العمل {#how-it-works}
تستخدم منصة Inbound Platform webhooks نمط قائمة انتظار SQL عبر الأنظمة الأساسية بحيث تعمل على كل مضيف بدون خادم (Netlify وVercel وCloudflare Workers وFly وRender وNode) دون الاعتماد على عمليات API الخاصة بالتنفيذ في الخلفية الخاصة بالمنصة.
1. المنصة `POST` إلى `/_agent-native/integrations/<platform>/webhook`. يتحقق المعالج من التوقيع، ويوزع الحمولة في `IncomingMessage`، و**يدرج صفًا في `integration_pending_tasks`** باستخدام `status='pending'`.
2. يطلق المعالج إشارة "أطلق وانسى" `POST /_agent-native/integrations/process-task` ويعيد `200` على الفور، داخل Slack لمدة 3 ثوانٍ في SLA.
3. تعمل نقطة نهاية المعالج في **تنفيذ وظيفة جديدة** بميزانية المهلة الكاملة الخاصة بها. فهو يطالب بالمهمة ذريًا (`pending` → `processing` عبر `claimPendingTask`)، ويقوم بتشغيل حلقة الوكيل، وينشر الرد من خلال المحول، ويضع علامة على المهمة `completed`.
4. تقوم مهمة إعادة المحاولة المتكررة (`startPendingTasksRetryJob`، كل 60 ثانية) بمسح المهام العالقة في `pending` >90 ثانية أو `processing` > 5 دقائق وتعيد تشغيل المعالج. تم تحديد 3 محاولات، ثم تم وضع علامة `failed`.
<Diagram id="doc-block-db7fc7" title={"دورة حياة خطاف الويب الوارد"} summary={"يقوم خطاف الويب فقط بالتحقق من الرقم 200 وإدراجه في قائمة الانتظار وإرجاعه. يؤدي تنفيذ وظيفة جديدة إلى استنزاف قائمة الانتظار وتشغيل حلقة الوكيل، مع إعادة المحاولة لمدة 60 ثانية كشبكة أمان."}>
```html
<div class="msg-flow">
<div class="msg-row">
<div class="diagram-node">
Platform<br /><small class="diagram-muted">Slack · البريد · إلخ</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-box" data-rough>
<strong>/webhook</strong><br /><small class="diagram-muted"
>verify signature + parse</small
><br /><span class="diagram-pill">INSERT مهمة معلقة</span>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-pill ok">return 200</div>
</div>
<div class="msg-fire">
<span class="diagram-muted">fire-and-forget</span>
<span class="diagram-arrow diagram-muted" aria-hidden="true">↓</span>
</div>
<div class="msg-row">
<div class="diagram-box" data-rough>
<strong>/process-task</strong><br /><small class="diagram-muted"
>تنفيذ جديد · مهلة خاصة</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-pill accent">claim</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-pill accent">agent loop</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-pill accent">adapter.sendResponse</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-pill ok">completed</div>
</div>
<div class="diagram-panel msg-retry" data-rough>
<span class="diagram-pill warn">every 60s</span>
<span class="diagram-muted"
>retry job sweeps stuck tasks (pending >90s · processing >5min) and
re-fires /process-task — capped at 3 attempts, then
<strong>failed</strong></span
>
</div>
</div>
```
```css
.msg-flow {
display: flex;
flex-direction: column;
gap: 12px;
}
.msg-flow .msg-row {
display: flex;
align-items: center;
gap: 10px;
flex-wrap: wrap;
}
.msg-flow .msg-fire {
display: flex;
align-items: center;
gap: 8px;
padding-inline-start: 12px;
}
.msg-flow .msg-retry {
display: flex;
align-items: center;
gap: 8px;
flex-wrap: wrap;
}
```
</Diagram>
توجد المحادثات الواردة والصادرة في نفس سلسلة رسائل SQL، لذا يمكنك متابعة رسالة مباشرة Slack من الويب UI أو العكس.
<Endpoint id="doc-block-of3dmy" method="POST" path="/_agent-native/integrations/slack/webhook" summary={"Slack الأحداث API خطاف الويب الوارد"} auth={"HMAC-SHA256 of the raw body using `SLACK_SIGNING_SECRET`, checked against the `X-Slack-Signature` header. In production also gated by `SLACK_ALLOWED_TEAM_IDS` / `SLACK_ALLOWED_API_APP_IDS`."} params={[
{
"name": "X-Slack-Signature",
"in": "header",
"type": "string",
"required": true,
"description": "Slack request signature, verified before any processing."
},
{
"name": "X-Slack-Request-Timestamp",
"in": "header",
"type": "string",
"required": true,
"description": "Timestamp used in the signature base string."
}
]} request={{
"contentType": "application/json",
"example": "{\n \"type\": \"event_callback\",\n \"team_id\": \"T0123\",\n \"api_app_id\": \"A0123\",\n \"event\": {\n \"type\": \"message\",\n \"channel_type\": \"im\",\n \"user\": \"U0123\",\n \"text\": \"summarize last week's signups\"\n }\n}"
}} responses={[
{
"status": "200",
"description": "Acknowledged immediately. The agent loop runs in the separate /process-task execution. The first time a Request URL is saved, Slack POSTs a `url_verification` challenge and the adapter replies with the `challenge` value automatically.",
"example": "{ \"ok\": true }"
},
{
"status": "401",
"description": "Signature verification failed, or the team/app id is not in the production allowlist."
}
]}>
Receives Slack events (DMs and channel `app_mention`s). Verifies the request signature, parses the payload into an `IncomingMessage`, inserts a `pending` row into `integration_pending_tasks`, fires the fresh-execution processor, and returns **200 immediately** — well inside Slack's 3-second SLA. The same route shape exists per platform under `/_agent-native/integrations/<platform>/webhook`.
</Endpoint>
#### لماذا هذا النمط (وليس الاختصارات الأصلية للمنصة) {#why-this-pattern}
تتجمد الوظائف بدون خادم لحظة إرسال الاستجابة. أي شيء لا يزال قيد التشغيل - بما في ذلك وعد "أطلق وانسى" أو مكالمة LLM المؤجلة أو أداة أثناء الطيران - يتم إيقافه في منتصف التنفيذ. الطريقة الوحيدة لإبقاء حلقة الوكيل على قيد الحياة هي بدء تنفيذ وظيفة **جديدة** لها، وهو ما يفعله `/process-task` POST الذي يتم تشغيله ذاتيًا.
هل يستخدم NOT أيًا من هذه البدائل:
- **وظائف خلفية Netlify** — Netlify فقط، وتتطلب لاحقة اسم ملف `-background.ts`، وتتوقف عند كل مضيف آخر.
- **Cloudflare `event.waitUntil()`** — عمال CF فقط، غير محمولين.
- **Vercel `after()` / Fluid** — Vercel فقط، خلف أوقات تشغيل محددة.
- **وعود إطلاق النار والنسيان العارية بعد `return`** — تُقتل بصمت عندما تتجمد الوظيفة؛ لا يوجد خطأ في السجلات، ولن يحصل المستخدم على رد أبدًا.
إن مجموعة SQL-queue + self-webhook + إعادة محاولة المهمة هي الشيء الوحيد الذي يعمل بشكل مماثل على كل مضيف مدعوم. مهمة إعادة المحاولة هي شبكة الأمان - لا تفترض أبدًا أن الإرسال الأولي قد تم مسحه قبل تجميد الوظيفة.
### المكون الإضافي لعمليات التكامل {#plugin}
يتم تثبيت المكون الإضافي تلقائيًا في حالة عدم وجود إصدار مخصص. للتخصيص، قم بإنشاء:
```ts
// server/plugins/integrations.ts
import { createIntegrationsPlugin } from "@agent-native/core/server";
import { scriptRegistry } from "../../agent.config";
export default createIntegrationsPlugin({
actions: scriptRegistry,
systemPrompt: "You are a helpful assistant...",
});
```
تقبل `createIntegrationsPlugin()` كائن `IntegrationsPluginOptions` اختياريًا. يحدد الخيار `initialToolNames?: readonly string[]` مخططات actions المحلية التي تُرسل في أول طلب إلى النموذج. عند حذفه، تبقى جميع actions المحلية ضمن المجموعة الأولية. تُنسخ المصفوفة المقدمة دون تعديل مصفوفة المستدعي.
تؤجل القائمة الفارغة الصريحة تحميل actions المحلية حتى تكتشفها `tool-search`. تبقى أدوات إطار العمل المطلوبة متاحة منذ البداية. يعطّل هذا الإعداد أيضًا التفويض بين التطبيقات عندما لا تتضمن بيئة النشر نظير A2A:
```ts
export default createIntegrationsPlugin({
actions: scriptRegistry,
initialToolNames: [] as const,
callAgent: false,
});
```
تنطبق مجموعة الأدوات الأولية نفسها على معالجة webhooks والمهام في قائمة الانتظار والاستطلاع الدوري لـ Google Docs. يبقى سجل actions الكامل قابلًا للبحث. يعطّل `callAgent: false` تسجيل action المدمج `call-agent` بشكل مستقل، حتى لو ظهر في `initialToolNames`.
تعتمد الأنظمة الأساسية النشطة على نوع env vars الذي تم تعيينه. يسجل المكون الإضافي مسارات خطاف الويب لكل مسار ضمن `/_agent-native/integrations/`.
### الخطاف التلقائي على الويب URL {#webhook-urls}
```text
/_agent-native/integrations/slack/webhook
/_agent-native/integrations/telegram/webhook
/_agent-native/integrations/whatsapp/webhook
/_agent-native/integrations/email/webhook
```
يكشف Telegram أيضًا عن نقطة نهاية الإعداد لمرة واحدة:
```text
POST /_agent-native/integrations/telegram/setup
```
### متغيرات البيئة {#env-vars}
| المنصة | مطلوب | اختياري |
| ----------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Slack | `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET` | `SLACK_ALLOWED_TEAM_IDS`, `SLACK_ALLOWED_API_APP_IDS` |
| تيليجرام | `TELEGRAM_BOT_TOKEN` | — |
| البريد الإلكتروني | `EMAIL_AGENT_ADDRESS`، بالإضافة إلى واحد من `RESEND_API_KEY` أو `SENDGRID_API_KEY` | `EMAIL_INBOUND_WEBHOOK_SECRET` |
| واتساب | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID` | — |
يتم حل بيانات اعتماد التكامل أولاً من الأسرار ذات النطاق لمالك التكامل (المستخدم ثم المؤسسة ثم مساحة العمل)؛ وتكون متغيرات بيئة النشر بديلاً للتثبيت المحلي أو أحادي المستأجر المقصود. تحفظ واجهة الإعداد أسراراً ذات نطاق؛ ولا تُعاد القيم أبداً إلى المتصفح أو تُخزَّن في كود المصدر.
محولات وقت التشغيل المضمنة هي **Slack** و**Telegram** و**WhatsApp Cloud API** والبريد الإلكتروني عبر webhooks لموفر الخدمة (Resend أو SendGrid). لا يمكن توصيل Discord أو Microsoft Teams حتى يتم تنفيذ محول تم التحقق منه وتسجيله.
### الترابط والهوية {#threading-and-identity}
يتم تعيين كل محادثة خارجية لسلسلة محادثات مستمرة في قاعدة بيانات الوكيل الأصلية:
- **رسالة Slack مباشرة** → موضوع واحد لكل مستخدم Slack.
- **@إشارة قناة Slack** → موضوع واحد لكل قناة.
- **دردشة تيليجرام** → موضوع واحد لكل دردشة تيليجرام.
- **محادثة WhatsApp** → موضوع واحد لكل رقم WhatsApp.
- **البريد الإلكتروني** → سلسلة الرسائل مشتقة من رؤوس `Message-ID` / `In-Reply-To` / `References`.
تظهر المواضيع الخارجية في الويب UI جنبًا إلى جنب مع المواضيع التي تم إنشاؤها على الويب، والتي تم وضع علامة عليها باستخدام نظامها الأساسي المصدر. تحليل الهوية: عندما يطابق مستخدم Slack/البريد الإلكتروني مستخدمًا مسجلاً (عادةً عن طريق البريد الإلكتروني)، يتم ربطه بهذا الحساب.
### الأمان {#security}
يتم التحقق من توقيع كل خطاف ويب وارد قبل المعالجة:
- **Slack** — HMAC-SHA256 للجسم باستخدام `SLACK_SIGNING_SECRET`، تم فحصه مقابل رأس `X-Slack-Signature`. في المرة الأولى التي تقوم فيها بحفظ طلب URL في لوحة اشتراكات الأحداث الخاصة بـ Slack، تقوم Slack بنشر تحدي `url_verification` له؛ يكتشف محول إطار العمل ذلك ويرد بقيمة `challenge` تلقائيًا، لذلك يتحول URL إلى اللون الأخضر في Slack دون أي عمل إضافي من جانبك.
- **Telegram** — يتم تعيين الرمز السري عند تسجيل خطاف الويب.
- **WhatsApp** — اختبار التحقق من Meta (باستخدام `WHATSAPP_VERIFY_TOKEN`) بالإضافة إلى توقيع الحمولة.
- **البريد الإلكتروني** — التحقق من التوقيع بنمط Svix عند تعيين `EMAIL_INBOUND_WEBHOOK_SECRET` (يستخدم كل من Resend وSendGrid هذا التنسيق). إذا لم يتم تعيين السر، فسيتم قبول خطاف الويب ولكن يتم تسجيل تحذير.
يفرض محول البريد الإلكتروني أيضًا ما يلي:
- **المجالات المسموح بها** — مصفوفة `allowedDomains` اختيارية في صف `integration_configs` الخاص بالتكامل؛ يتم إسقاط المرسلين من خارج القائمة.
- **حد السعر** — حد معدل SQL المدعوم بقائمة الانتظار يبلغ 20 رسالة واردة لكل مرسل في الساعة.
### الإرسال الاستباقي {#proactive-sends}
يمكن للوكيل إرسال رسائل من تلقاء نفسه (الإعلامات والتذكيرات والملخصات المجدولة) عن طريق استدعاء إجراء `send-platform-message` باستخدام حقل `platform` `"slack"` أو `"telegram"` أو `"whatsapp"` أو `"email"`. الإجراء موجود في حزمة Dispatch في `packages/dispatch/src/actions/send-platform-message.ts` ويمكنك نسخه/تكييفه مع أي قالب.
### المحولات المخصصة {#custom-adapters}
لإضافة منصة مراسلة جديدة، قم بتنفيذ واجهة `PlatformAdapter`:
```ts
import type { H3Event } from "h3";
import type {
PlatformAdapter,
IncomingMessage,
OutgoingMessage,
} from "@agent-native/core/server";
import type { EnvKeyConfig } from "@agent-native/core/server";
const myAdapter: PlatformAdapter = {
platform: "my-chat",
label: "My Chat",
// Env keys this adapter needs (rendered in the settings UI)
getRequiredEnvKeys(): EnvKeyConfig[] {
return [
{ key: "MY_CHAT_BOT_TOKEN", label: "My Chat Bot Token", required: true },
];
},
// Handle platform-specific verification challenges (e.g. Slack's
// url_verification). Return { handled: true, response } to short-circuit.
async handleVerification(event: H3Event) {
return { handled: false };
},
// Validate the webhook request signature
async verifyWebhook(event: H3Event): Promise<boolean> {
// Validate signature headers; return true if authentic
return true;
},
// Parse the webhook payload into a normalized IncomingMessage.
// Return null to silently ignore the event (bot messages, edits, etc.).
async parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null> {
return {
platform: "my-chat",
externalThreadId: "channel-or-thread-id",
text: "the user's message",
senderId: "my-chat-user-id",
platformContext: { channelId: "channel-id" },
timestamp: Date.now(),
};
},
// Format plain agent text into a platform-appropriate OutgoingMessage.
// opts.threadDeepLinkUrl, when provided, is a URL back to the originating
// thread in the dispatch UI — render it as a button (Slack) or inline link.
formatAgentResponse(
text: string,
opts?: { threadDeepLinkUrl?: string },
): OutgoingMessage {
return { text, platformContext: {} };
},
// Post the agent's response back to the platform
async sendResponse(
message: OutgoingMessage,
context: IncomingMessage,
): Promise<void> {
// Call the platform's API, using context.platformContext for routing
},
// Return current connection/configuration status for the settings UI.
// baseUrl is the app's public URL, used for status checks that need it.
async getStatus(baseUrl?: string) {
return {
platform: "my-chat",
label: "My Chat",
enabled: true,
configured: !!process.env.MY_CHAT_BOT_TOKEN,
};
},
};
```
سجله في البرنامج المساعد للتكامل الخاص بك:
```ts
export default createIntegrationsPlugin({
actions: scriptRegistry,
systemPrompt: "You are a helpful assistant...",
adapters: [myAdapter],
});
```
التطبيقات المرجعية موجودة في `packages/core/src/integrations/adapters/` (`slack.ts`، `telegram.ts`، `whatsapp.ts`، `email.ts`) — محول البريد الإلكتروني هو المثال الأكثر اكتمالا، بما في ذلك التحقق من التوقيع، والترابط، وتحديد المعدل، وعرض HTML.
### الموثوقية عبر استمرارية Dispatch + A2A {#reliability}
عندما يقوم [Dispatch](/docs/dispatch) بتفويض طلب إلى تطبيق آخر عبر [A2A](/docs/a2a-protocol#continuations)، يضمن تدفق استمرار الاسترداد حصول المستخدم على رد Slack/البريد الإلكتروني حتى إذا تعطل وكيل المصب في منتصف التنفيذ. تظل مهمة webhook الأصلية في `processing` حتى يتم حل المتابعة أو تشير عملية المسح لإعادة المحاولة إلى أنها عالقة؛ وفي كلتا الحالتين، يحصل موضوع المنصة على رد نهائي بدلاً من الصمت.
يعني هذا أن مساحة العمل متعددة التطبيقات التي تقدمها Dispatch أكثر مرونة من قالب واحد متصل بالمراسلة مباشرة - حيث تؤدي حالات الفشل في أي تطبيق واحد إلى ظهور رسالة خطأ بسيطة بدلاً من إسقاط الرد. راجع [A2A continuations](/docs/a2a-protocol#continuations) للاطلاع على القصة الكاملة لضمان التسليم.
### المزالق الشائعة {#pitfalls}
- **لا تقرأ نص الطلب مرتين.** يتم استهلاك دفق نص h3 v2 مرة واحدة: إذا اتصلت بـ `readBody(event)` بعد أن قام إطار العمل بالفعل بتحليل `event.node.req.body` (أو العكس)، فإن القراءة الثانية تعلق الطلب إلى أجل غير مسمى. يظهر هذا في أغلب الأحيان مع Resend وSendGrid - كلاهما دفق الحمولة الواردة ولا يتم حل القراءة المتدلية أبدًا، وتنتهي مهلة النظام الأساسي، وتتم إعادة محاولة خطاف الويب حتى يتم التخلص منه. إذا قمت بلف معالج خطاف الويب الخاص بإطار العمل في برنامجك الوسيط، فقم بتمرير `IncomingMessage` الذي تم تحليله بالفعل عبر خيار `incoming` بدلاً من السماح للمعالج بإعادة التحليل.
- **لا تقم بتشغيل حلقات الوكيل داخل معالج webhook.** يجب أن يقوم المعالج بوضعه في قائمة الانتظار والعودة — يتم تشغيل حلقة الوكيل في التنفيذ الجديد للمعالج. ويضمن وضعه في السطر أن يؤدي التجميد بدون خادم إلى إنهاء التشغيل. علاوة على ذلك، فإن عمليات تكامل البوابة العامة (مثل Netlify أو Vercel) تفرض حدودًا صارمة لمهلة HTTP (على سبيل المثال، حد طلب Netlify البالغ 10 ثوانٍ). نظرًا لأن تشغيل الوكيل والأدوات غالبًا ما تستغرق وقتًا أطول من هذه النافذة، فإن محاولة تشغيل الحلقة بشكل متزامن داخل طلب خطاف الويب سوف يتسبب في قيام البوابة بإنهاء الاتصال، مما يؤدي إلى إحباط التنفيذ وإسقاط الردود. يعد نمط قائمة الانتظار HMAC ذاتي الخطاف `/process-task` هو الطريقة الوحيدة لتلبية حدود البوابة أثناء تنفيذ حلقة الوكيل الكاملة بأمان.
- **لا تعتمد على ذاكرة الحذف أثناء عمليات التشغيل الباردة.** يوجد مفتاح الحذف في الفهرس الفريد SQL `(platform, external_event_key)`، وليس في خريطة قيد المعالجة. إذا قمت باستبدال قائمة الانتظار، فاحتفظ بعملية الحذف على مستوى SQL أو ستؤدي عمليات إعادة المحاولة Slack المكررة إلى تشغيل الوكيل المكرر.
- **حافظ على إمكانية الوصول إلى خطاف الويب الذاتي URL.** تم إنشاء المعالج URL من `APP_URL` / `URL` / `DEPLOY_URL` / `BETTER_AUTH_URL`، ويعود إلى رؤوس الطلبات الواردة. عند نشر المعاينة باستخدام أسماء المضيفين المعاد كتابتها، قم بتعيين أحد هذه الأسماء بشكل صريح وإلا سيصل الإرسال إلى 404.
### انظر أيضًا {#see-also}
- [Dispatch](/docs/dispatch) — نظرة عامة على مفهوم استخدام البريد الوارد المركزي عبر التطبيقات
- [Dispatch template reference](/docs/template-dispatch) — البريد الوارد المركزي الموصى به لمساحات العمل متعددة التطبيقات
- [A2A Protocol](/docs/a2a-protocol) — كيفية عمل مندوبي Dispatch إلى الوكلاء الآخرين، بما في ذلك استمرار الاسترداد
- [Agent Mentions](/docs/agent-mentions) — وكلاء الإشارة إلى `@` داخل دردشة الويب
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |