دليل المطوّرين والربط مع Helpy

نظرة عامة

فيه 3 طرق تربط بيها أي حاجة بـ Helpy، وكلها بتشتغل بصلاحيات المستخدم اللي ربط ونطاق بياناته بالظبط، وبتتراجع فوراً لو صلاحياته اتغيّرت أو فصل الاتصال:

وصف OpenAPI 3.1 الكامل للـ REST API (لـ Postman وSwagger ومولّدات SDK):

https://helpy.ai/api/v1/openapi.json

اربط تطبيق ذكاء اصطناعي في دقيقتين

الرابط واحد لكل التطبيقات. التطبيق بيكتشف تسجيل الدخول لوحده (OAuth)، فبتسجّل دخولك في Helpy مرة وتوافق — من غير ما تنسخ أي مفتاح. الإعداد خطوة بخطوة جوه Helpy في الإعدادات ← ربط الذكاء الاصطناعي.

https://helpy.ai/api/mcp

{
  "mcpServers": {
    "helpy": {
      "url": "https://helpy.ai/api/mcp"
    }
  }
}

mcp_servers:
  helpy:
    url: "https://helpy.ai/api/mcp"
    auth: oauth

# then run: hermes mcp login helpy

claude mcp add --transport http helpy https://helpy.ai/api/mcp

{
  "servers": {
    "helpy": {
      "type": "http",
      "url": "https://helpy.ai/api/mcp"
    }
  }
}

بمفتاح API بدل تسجيل الدخول (Hermes على سيرفر، n8n، أي عميل MCP مبيدعمش OAuth): ابعت الترويسة Authorization: Bearer <المفتاح>.

mcp_servers:
  helpy:
    url: "https://helpy.ai/api/mcp"
    headers:
      Authorization: "Bearer ${HELPY_API_KEY}"

إزاي خادم MCP بيشتغل

• النقل: Streamable HTTP بدون جلسة (POST بـ JSON-RPC) — يدعم إصدارات البروتوكول 2025-11-25 و2025-06-18 و2025-03-26 و2024-11-05.
• الأدوات: نفس أدوات مساعد Helpy (حوالي 90 أداة) — التطبيق بيشوف بس اللي المستخدم مسموح له بيه في شركته وباقته وتطبيقاته المركّبة.
• القراءة فورية. أي تغيير بيرجع معاينة فيها action_id ومبيتنفّذش؛ بعد موافقة المستخدم في المحادثة التطبيق يستدعي helpy_confirm_action. فيه كمان helpy_cancel_action وhelpy_undo_action (للتغييرات القابلة للعكس خلال دقايق).
• التغييرات اللي بتمسّ عدد كبير من العملاء محتاجة acknowledge_bulk=true بعد ما المستخدم يأكد العدد.
• search وfetch: بحث موحّد في العملاء والمحادثات ومركز المساعدة (متوافق مع Deep Research في ChatGPT).
• أوامر جاهزة (prompts) بتظهر كاختصارات في Claude وCursor:

قصر الأدوات على مجموعات: ضيف أسماء المجموعات للرابط مفصولة بفاصلة، مثلاً /api/mcp/crm,inbox,tasks. أدوات الحساب والمساعدة والموافقة موجودة دايماً.

المصادقة

OAuth 2.1 (للتطبيقات اللي المستخدم بيربطها بنفسه):

مفاتيح API (للأنظمة والتشغيل الآلي): من Helpy ← الإعدادات ← ربط الذكاء الاصطناعي ← مفاتيح API. المفتاح بيظهر مرة واحدة، وبيشتغل مع خادم MCP والـ REST API. «اسمح بالتغييرات» تديله helpy:write.

Authorization: Bearer hlp_sk_YOUR_KEY

REST API v1

• العنوان الأساسي: https://helpy.ai/api/v1
• الرد دايماً { "data": ..., "meta"?: ... } والخطأ { "error": { "code", "message" } }.
• الصفحات بمؤشّر: meta.nextCursor ابعته كـ ?cursor= في الطلب التالي.
• النصوص المترجمة (أسماء المراحل والخدمات) بالعربي افتراضياً — ?locale=en أو Accept-Language: en للإنجليزي.
• كل حاجة خارج نطاق بيانات المستخدم بترجع 404 كأنها مش موجودة.

curl -X POST https://helpy.ai/api/v1/leads \
  -H "Authorization: Bearer hlp_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sara Ahmed","phone":"+966501112233","email":"sara@example.com","tags":["expo"]}'

curl -X POST https://helpy.ai/api/v1/tasks \
  -H "Authorization: Bearer hlp_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Sara","leadId":"LEAD_ID","dueAt":"2026-11-01T09:00:00Z","priority":"HIGH"}'

curl -X POST https://helpy.ai/api/v1/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer hlp_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"أهلاً سارة، عرض السعر في الطريق 👋"}'

const res = await fetch("https://helpy.ai/api/v1/leads?search=Sara", {
  headers: { Authorization: `Bearer ${process.env.HELPY_API_KEY}` },
});
const { data, error } = await res.json();

import os, requests

res = requests.get(
    "https://helpy.ai/api/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HELPY_API_KEY']}"},
)
tasks = res.json()["data"]

الأخطاء وحدود الاستخدام

• REST: 240 طلب قراءة و60 طلب تغيير في الدقيقة لكل اتصال.
• MCP: 120 طلب في الدقيقة لكل اتصال.
• كل رد فيه Helpy-Api-Version وX-RateLimit-Limit.

الويبهوكات (Webhooks)

من Helpy ← التطبيقات ← Zapier/Webhooks أضف رابطك واختار الأحداث: lead.created وlead.updated. كل تسليم POST بـ JSON، وبيتعاد لحد 6 مرات لو رابطك مردّش بـ 2xx.

{
  "event": "lead.created",
  "data": { "id": "…", "name": "Sara Ahmed", "phone": "+9665…", "status": "NEW", "createdAt": "…" },
  "firedAt": "2026-10-28T12:00:00.000Z"
}

اتأكد إن الطلب جاي من Helpy: الترويسة X-Webhook-Signature = sha256=HMAC-SHA256(الجسم الخام، سرّ الويبهوك).

import { createHmac, timingSafeEqual } from "node:crypto";

function fromHelpy(rawBody, header, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return header?.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

الأمان والخصوصية

• كل طلب بيتحقق من المستخدم وصلاحياته ونطاق بياناته من قاعدة البيانات لحظتها — مفيش صلاحية بتتخزن في التوكن.
• التوكنات والمفاتيح بتتخزن بصمات SHA-256 بس، ومفيش أي سرّ بيتكتب في السجلات.
• المستخدم يفصل أي تطبيق أو مفتاح فوراً، والمالك يفصل اتصالات فريقه. «الخروج من كل الأجهزة» وتغيير كلمة السر بيفصلوا كل حاجة.
• الربط والفصل وإنشاء المفاتيح وكل تغيير بيتسجّل في سجل التدقيق.
• في MCP: رسايل العملاء والملاحظات بتتعامل كبيانات مش أوامر، والتغييرات محتاجة موافقة صريحة.
• فريق Helpy يقدر يقفل الربط على المنصة كلها أو لشركة واحدة فوراً.