با API ایجنتهاتون ارتباط بگیرید. پیام ارسال کنید، پاسخ استریم دریافت کنید و ایجنتهاتون رو در هر اپلیکیشنی ادغام کنید.
از بخش تنظیمات ایجنت → کلیدهای API یک کلید بسازید. کلید را در هدر X-API-Key تمام درخواستها ارسال کنید.
X-API-Key: agk_YOUR_API_KEY
/api/chat/{AGENT_ID}/messageپیام ارسال کنید و پاسخ کامل را یکجا دریافت کنید.
| فیلد | نوع | توضیح |
|---|---|---|
| message* | string | متن پیام |
| user_id | string | شناسه کاربر (برای حافظه مکالمه) |
| thread_id | string | شناسه مکالمه (جداسازی موضوعات) |
curl -X POST https://agent.noqte.ai/api/chat/{AGENT_ID}/message \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"message": "سلام", "user_id": "user_1"}'{
"response": "سلام! چطور میتونم کمکت کنم؟",
"user_id": "user_1"
}/api/chat/{AGENT_ID}/streamپاسخ را بهصورت Server-Sent Events دریافت کنید. مناسب برای نمایش real-time.
tokenبخشی از متن پاسخ
tool_callایجنت در حال اجرای ابزار
new_messageشروع پیام جدید (بعد از tool)
confirmationتایید عملیات خطرناک
doneپایان پاسخ
errorخطا
وقتی ایجنت ابزاری اجرا میکنه (مثلاً جستجوی وب)، اول tool_call میاد، بعد new_message نشون میده که پاسخ بعدی توی یه پیام جداگانه نمایش داده بشه.
curl -N -X POST https://agent.noqte.ai/api/chat/{AGENT_ID}/stream \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"message": "قیمت دلار چنده؟", "user_id": "user_1"}'import requests
response = requests.post(
"https://agent.noqte.ai/api/chat/{AGENT_ID}/message",
headers={
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY",
},
json={"message": "سلام", "user_id": "user_1"},
)
print(response.json()["response"])const res = await fetch("https://agent.noqte.ai/api/chat/{AGENT_ID}/message", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY",
},
body: JSON.stringify({ message: "سلام", user_id: "user_1" }),
});
const data = await res.json();
console.log(data.response);const res = await fetch("https://agent.noqte.ai/api/chat/{AGENT_ID}/stream", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY",
},
body: JSON.stringify({ message: "سلام", user_id: "user_1" }),
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
for (const line of decoder.decode(value).split("\n")) {
if (!line.startsWith("data: ")) continue;
const event = JSON.parse(line.slice(6));
switch (event.type) {
case "token":
process.stdout.write(event.content);
break;
case "tool_call":
console.log("\n[Tool] " + event.content);
break;
case "new_message":
console.log("\n--- پیام جدید ---");
break;
case "done":
console.log("\n--- Done ---");
break;
case "error":
console.error("Error: " + event.content);
break;
}
}
}import json, requests
response = requests.post(
"https://agent.noqte.ai/api/chat/{AGENT_ID}/stream",
headers={
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY",
},
json={"message": "سلام", "user_id": "user_1"},
stream=True,
)
for line in response.iter_lines():
if not line:
continue
line = line.decode()
if not line.startswith("data: "):
continue
event = json.loads(line[6:])
match event["type"]:
case "token":
print(event["content"], end="", flush=True)
case "tool_call":
print(f"\n[Tool] {event['content']}")
case "new_message":
print("\n--- پیام جدید ---")
case "done":
print("\n--- Done ---")
case "error":
print(f"Error: {event['content']}")هر کاربر مکالمه مستقل دارد. با user_id و thread_id مکالمات رو جدا کنید.
| فیلد | نوع | توضیح |
|---|---|---|
| user_id | string | شناسه کاربر — هر کاربر حافظه جدا دارد |
| thread_id | string | شناسه مکالمه — برای جداسازی موضوعات مختلف |
| user_name | string | نام کاربر (برای شخصیسازی پاسخ) |
• بدون user_id: هر درخواست session جدید میسازه
• با user_id: مکالمه ادامهدار (حافظه حفظ میشه)
• با thread_id: موضوعات مختلف برای یک کاربر
/api/chat/{AGENT_ID}/configاطلاعات عمومی ایجنت — بدون نیاز به API Key.
{
"agent_name": "قیمت طلا",
"description": "ایجنت قیمت لحظهای طلا",
"theme": {
"title": "قیمت لحظهای طلا",
"logo_url": "https://...",
"welcome_message": "سلام! چطور کمکت کنم؟",
"primary_color": "#3B82F6"
}
}صدای فارسی رو با دقت بالا به متن تبدیل میکنه. هزینه از موجودی توکن حسابت کسر میشه.
/api/stt/transcribeبا هدر X-API-Key: agk_... — همون کلیدی که برای چت ایجنتت استفاده میکنی.
(یا Authorization: Bearer JWT اگه از داشبورد وب استفاده میکنی.)
| فیلد | نوع | توضیح |
|---|---|---|
| audio* | file | فایل صدا — webm / mp3 / wav / m4a / ogg (حداکثر ۲۵MB) |
| duration* | float | مدت صدا به ثانیه (حداکثر ۳۰۰ثانیه) |
| agent_id | string | ایجنتی که هزینه روش حساب میشه (پیشفرض: builder) |
۳۰ توکن به ازای هر ثانیه صدا — مثلاً ۱۰ ثانیه = ۳۰۰ توکن. قبل از تبدیل، موجودی چک میشه.
curl -X POST https://agent.noqte.ai/api/stt/transcribe \
-H "X-API-Key: agk_YOUR_KEY" \
-F "audio=@voice.webm" \
-F "duration=8.4" \
-F "agent_id={AGENT_ID}"{
"text": "سلام، میخوام قیمت طلا رو بدونم",
"duration_seconds": 8.4,
"tokens_charged": 252
}import httpx
with open("voice.webm", "rb") as f:
audio_data = f.read()
# duration رو از روی فایل صدا حساب کن یا از ضبطکننده بگیر
duration = 8.4
resp = httpx.post(
"https://agent.noqte.ai/api/stt/transcribe",
headers={"X-API-Key": "agk_YOUR_KEY"},
files={"audio": ("voice.webm", audio_data, "audio/webm")},
data={"duration": str(duration), "agent_id": "{AGENT_ID}"},
timeout=60,
)
print(resp.json())401 — کلید نامعتبر
402 — موجودی توکن کافی نیست
413 — فایل بزرگتر از ۲۵MB
422 — صدا قابل شناسایی نبود
503 — سرویس موقتاً غیرفعاله (پشتیبانی اطلاع داره)
اگه ایجنتت به سرویسهایی وصله که هر کاربر باید کلید/توکن جدای خودش رو داشته باشه (مثلاً صرافی، ووکامرس، حسابداری)، میتونی کلید هر کاربر رو یه بار ذخیره کنی و بعد توی چتها فقط با user_id بفرستی — ایجنت خودکار کلید درست رو استفاده میکنه.
با X-API-Key: agk_... (همون کلید ایجنت)
/api/users/{user_id}/credentials/{service_id}curl -X PUT https://agent.noqte.ai/api/users/bob_42/credentials/abantether \
-H "X-API-Key: agk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"credential": "user_aban_api_key_xxx",
"type": "api_key"
}'• user_id: شناسه کاربری که خودت میدی (هر چیزی، مثلاً bob_42 یا email یا UUID)
• service_id: همون شناسهی سرویسی که توی ایجنت تنظیم کردی (مثل abantether, woocommerce, hesabfa)
• credential: کلید/توکن کاربر (encrypted ذخیره میشه)
curl -X POST https://agent.noqte.ai/api/chat/{AGENT_ID}/message \
-H "X-API-Key: agk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id":"bob_42","message":"موجودی تترم چقدره؟"}'ایجنت موقع فراخوانی tool که نیاز به کلید کاربر داره، خودکار کلید bob_42 رو از DB میخونه و وصلش میکنه به request.
| فیلد | نوع | توضیح |
|---|---|---|
| GET /api/users/{user_id}/credentials | list | لیست سرویسهایی که کلید ست شده — مقدار کلید برنمیگرده |
| GET /api/users/{user_id}/credentials/{service_id} | check | وضعیت یک سرویس خاص (set / not set + متادیتا) |
| DELETE /api/users/{user_id}/credentials/{service_id} | remove | حذف یک کلید |
| DELETE /api/users/{user_id}/credentials | logout | حذف همه کلیدهای کاربر (logout) |
• کلیدها با AES-256 رمزنگاری میشن قبل از ذخیره
• هیچ endpoint کلید رو واقعی برنمیگردونه — فقط set: true/false
• scope: کلید مال (ایجنت، user_id، service) هست. ایجنت دیگهای دسترسی نداره
• اگه کلید ست نشده باشه و ایجنت بخواد ازش استفاده کنه، یه پیام خطا برمیگرده با needs_credential: true
import httpx
API = "https://agent.noqte.ai"
KEY = "agk_YOUR_KEY"
H = {"X-API-Key": KEY}
# 1. وقتی کاربر کلیدش رو وارد میکنه (یه بار)
r = httpx.put(
f"{API}/api/users/bob_42/credentials/abantether",
headers=H,
json={"credential": user_provided_key},
)
assert r.json()["ok"]
# 2. چتهای بعدی — فقط user_id بفرست
r = httpx.post(
f"{API}/api/chat/{AGENT_ID}/message",
headers=H,
json={"user_id": "bob_42", "message": "خرید ۱۰ تتر"},
)
print(r.json()["response"])
# 3. وقتی کاربر logout میکنه
httpx.delete(f"{API}/api/users/bob_42/credentials", headers=H)• هر درخواست از موجودی توکن حساب شما کسر میشود.
• سقف مصرف روزانه هر ایجنت از تنظیمات → کیف پول قابل تنظیم است (پیشفرض ۵,۰۰۰ توکن).
• بدون API Key هم کار میکنه (پابلیک) ولی مصرف از حساب مالک کسر میشه.
• در صورت اتمام موجودی، پاسخ 402 دریافت خواهید کرد.