شروع کار

یکپارچه‌سازی با REST API

راهنمای کامل اتصال ایجنت‌های هوش مصنوعی موچت با استفاده از API نسخهٔ ۲ موچت برای برنامه‌ها و اتصال‌های سفارشی.

پلن Standard یا بالاتر لازم است. API نسخهٔ ۲ موچت از پلن Standard به بالا در دسترس است. مشاهدهٔ قیمت‌ها ←

مرور کلی

REST API موچت امکان افزودن گفتگوهای مبتنی بر هوش مصنوعی به هر برنامه یا گردش کاری را فراهم می‌کند. تجربه‌های گفتگوی سفارشی بسازید، تعاملات با مشتریان را خودکار کنید و ایجنت‌های هوش مصنوعی خود را از طریق کد مدیریت کنید.

API نسخهٔ ۲ از کدهای خطای ساختاریافته، صفحه‌بندی مبتنی بر مکان‌نما و دریافت جریانی بی‌درنگ از طریق رویدادهای ارسالی سرور (SSE) پشتیبانی می‌کند.

نشانی پایه:

https://api.mu.chat/api/v2

ارسال پیام

با ایجنت‌های هوش مصنوعی خود گفتگو کنید و پاسخ‌های جریانی بی‌درنگ را مدیریت کنید

ایجنت‌های هوش مصنوعی را مدیریت کنید

ایجنت‌های هوش مصنوعی و منابع آموزشی آنها را ایجاد، پیکربندی و به‌روزرسانی کنید

دسترسی به داده‌ها

گفتگوها و پیام‌های تعاملات خود با هوش مصنوعی را بازیابی کنید

شروع سریع

کلید API خود را دریافت کنید

ایجاد کلید API در داشبورد موچت
  1. به داشبورد موچت خود بروید
  2. به تنظیمات فضای کاری ← کلیدهای API بروید
  3. روی ایجاد کلید API کلیک کنید و کلید تولیدشده را کپی کنید

کلید API خود را در محلی امن نگه دارید و هرگز آن را در کد سمت کاربر افشا نکنید.

شناسهٔ ایجنت خود را دریافت کنید

یافتن شناسه ایجنت در تنظیمات موچت
  1. ایجنت هوش مصنوعی خود را در داشبورد انتخاب کنید
  2. به تنظیمات ← عمومی بروید
  3. شناسهٔ ایجنت را از کارت جزئیات ایجنت کپی کنید

اولین پیام خود را ارسال کنید

اتصال خود را با یک درخواست گفتگوی ساده آزمایش کنید:

curl -X POST 'https://api.mu.chat/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Hello! How can you help me?",
    "stream": false
  }'

پاسخ مورد انتظار:

{
  "data": {
    "id": "msg_abc123",
    "role": "assistant",
    "parts": [
      { "type": "text", "text": "Hello! I'm here to help answer your questions and assist with any information you need. What can I help you with today?" }
    ],
    "metadata": {
      "userMessageId": "msg_xyz789",
      "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "userId": null,
      "finishReason": "stop",
      "usage": { "credits": 2 }
    }
  }
}

مقدار پیش‌فرض stream در API نسخهٔ ۲ برابر با true است. آن را روی false تنظیم کنید تا پیام کامل را در قالب یک پاسخ JSON دریافت کنید.

گفتگو را ادامه دهید

موچت تاریخچهٔ گفتگو را ذخیره می‌کند؛ بنابراین نیازی به ارسال دوبارهٔ پیام‌های قبلی ندارید. برای ارسال پیام بعدی، conversationId پاسخ قبلی را ارسال کنید:

curl -X POST 'https://api.mu.chat/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Tell me more about your pricing.",
    "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "stream": false
  }'

برای مرتبط کردن یک گفتگوی جدید با یکی از کاربران خود، userId را همراه با اولین پیام ارسال کنید. برای جزئیات، گفتگوهای کاربر را ببینید.

دریافت جریانی در API گفتگو

API گفتگو با استفاده از رویدادهای ارسالی سرور، پاسخ‌ها را به‌صورت جریانی و بی‌درنگ ارسال می‌کند. هر رویداد یک خط data: شامل شیء JSON با فیلد type است و جریان با data: [DONE] پایان می‌یابد. برای ساخت پاسخ کامل، محتوای رویدادهای text-delta را به هم بچسبانید و برای ادامهٔ گفتگو، conversationId را از رویداد finish بخوانید.

// streamer.js (Node.js 18+)

const apiKey = '<Your-Secret-Key>'
const agentId = '<Your Agent ID>'
const apiUrl = `https://api.mu.chat/api/v2/agents/${agentId}/chat`

async function readAgentReply() {
  const response = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message: '<Your query here>',
      stream: true,
      // conversationId: '<Conversation ID>', // omit to start a new conversation
    }),
  })

  if (!response.ok) {
    const { error } = await response.json()
    throw new Error(`${error.code}: ${error.message}`)
  }

  const reader = response.body.getReader()
  const decoder = new TextDecoder()
  let buffer = ''
  let conversationId

  while (true) {
    const { done, value } = await reader.read()
    if (done) break

    buffer += decoder.decode(value, { stream: true })
    const lines = buffer.split('\n')
    buffer = lines.pop() // keep any incomplete line for the next chunk

    for (const line of lines) {
      if (!line.startsWith('data: ')) continue
      const data = line.slice('data: '.length)
      if (data === '[DONE]') continue

      const event = JSON.parse(data)
      switch (event.type) {
        case 'text-delta':
          process.stdout.write(event.delta)
          break
        case 'finish':
          conversationId = event.messageMetadata.conversationId
          break
        case 'error':
          console.error('\nStream error:', event.errorText)
          break
      }
    }
  }

  console.log('\nConversation ID:', conversationId)
}

readAgentReply().catch((error) => console.log('Error:', error.message))

برای فهرست کامل رویدادهای جریان، از جمله رویدادهای اکشن سمت کاربر (فراخوانی ابزار)، راهنمای دریافت جریانی را ببینید.

مدیریت خطا

API نسخهٔ ۲ خطاهای ساختاریافته را همراه با code قابل‌خواندن برای ماشین برمی‌گرداند:

{
  "error": {
    "code": "RATE_LIMIT_TOO_MANY_REQUESTS",
    "message": "Too many requests, please try again later"
  }
}

هر پاسخ شامل هدر x-request-id است؛ هنگام تماس با پشتیبانی آن را ارائه کنید. برای همهٔ کدهای خطا، مدیریت خطا و برای محدودیت‌ها و راهنمای تلاش مجدد، محدودیت نرخ درخواست را ببینید.

بهترین روش‌ها برای عملکرد بهتر

راهکارهای بهینه‌سازی:

  • برای اینکه کاربران پاسخگویی را سریع‌تر احساس کنند، پاسخ‌های گفتگو را به‌صورت جریانی دریافت کنید
  • برای پیام‌های بعدی، به‌جای شروع گفتگوی جدید از همان conversationId استفاده کنید
  • در موارد مناسب، پاسخ‌های ایجنت هوش مصنوعی را در حافظهٔ نهان ذخیره کنید
  • هنگام دریافت پاسخ 429، هدر Retry-After را رعایت کنید
  • هنگام فهرست کردن گفتگوها، پیام‌ها یا منابع از صفحه‌بندی مبتنی بر مکان‌نما استفاده کنید

🚀 آن را به‌صورت زنده امتحان کنید!

آماده‌اید امکانات را در عمل ببینید؟ وارد محیط آزمایش تعاملی ما شوید؛ می‌توانید هر نقطهٔ پایانی API را آزمایش کنید، پاسخ‌های واقعی را بررسی کنید و اتصال خود را به‌صورت بی‌درنگ بسازید.

نقاط پایانی کلیدی API

مرور کلی API نسخهٔ ۲

مرجع کامل API نسخهٔ ۲ را ببینید: احراز هویت، دریافت جریانی، اکشن‌های سمت کاربر، صفحه‌بندی و موارد دیگر

مستندات موچت

در این صفحه