> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-parschat.parstechai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-parschat.parstechai.com/_mcp/server.

# شروع سریع

> یک ربات بسازید، یک کانال وصل کنید و اولین رویدادتان را دریافت کنید.

> **Warning**
>
> **نسخه پیش‌انتشار `v1`، منتشرشده در ۲۰۲۶-۰۹-۱۴.** این صفحه به شکل API متعهد است، نه به تاریخ
> آن. دقیقاً همان چیزی را می‌سازیم که اینجا مستند شده است. شکل API تا
> **۲۰۲۶-۱۰-۱۴** هنوز ممکن است تغییر کند؛ پس از آن، تغییرات از [نسخه‌بندی و پایداری](/documentation/reference/versioning-stability) پیروی می‌کنند.
>
> این بنر صفحه‌به‌صفحه و هم‌زمان با فعال‌شدن هر مسیر برداشته می‌شود. تا وقتی بنر هست، بر اساس
> قرارداد پیاده‌سازی کنید و فرض کنید آن مسیر هنوز قابل فراخوانی نیست.

## پیش از شروع

دسترسی به API همراه با بسته ارائه می‌شود. به بسته **تجاری**، **حرفه‌ای** یا **بسته API اینستاگرام**
نیاز دارید. [قیمت‌ها](https://parstechai.com/products/parschat/) را ببینید.

وقتی یکی از این بسته‌ها فعال بود، بقیه موارد را در [chat.parstechai.com](https://chat.parstechai.com) تنظیم کنید:

|                 |                                                                |
| --------------- | -------------------------------------------------------------- |
| **کلید API**    | از پنل‌تان کپی کنید                                            |
| **آدرس وب‌هوک** | اندپوینت HTTPS شما. آن را در پنل تنظیم می‌کنید                 |
| **آدرس بازگشت** | پیش از اولین اتصال اینستاگرام، آن را به رابط پارس‌چت خود بدهید |

> **Info**
>
> ساخت و حذف ربات و اتصال کانال اینستاگرام، عملیات ویژه شرکای تجاری است. اگر به آن‌ها نیاز
> دارید، [با فروش تماس بگیرید](mailto:info@parstechai.com).

## نکته‌ای که اول باید بدانید

**کانال همیشه متعلق به یک ربات است.** نمی‌توانید یک صفحه اینستاگرام را به‌تنهایی وصل کنید. اول
ربات را بسازید، سپس کانال را به آن متصل کنید.

#### ساخت ربات

فضای کاری‌ای که گفتگوها، قانون‌های خودکارسازی و داده‌های آموزشی را نگه می‌دارد.

#### اتصال یک کانال به آن

در اینستاگرام، این کار یک فرایند تأیید در مرورگر را آغاز می‌کند. مالک صفحه خودش دسترسی را تأیید می‌کند.

#### دریافت رویدادها

هر پیام، تغییر وضعیت و واکنش روی وب‌هوک شما می‌رسد.

اگر مشتریان نهایی زیادی را مدیریت می‌کنید، برای هر مشتری یک ربات بسازید. همین کار است که
گفتگوهای یک مشتری را از گفتگوهای مشتری دیگر جدا نگه می‌دارد.

## ۱. ساخت ربات

**`cURL`**

```bash cURL
curl -X POST https://api-chat.parstechai.com/v1/robots \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rose Flower Shop",
    "external_id": "shop_10422"
  }'
```

**`Python`**

```python Python
import requests

robot = requests.post(
    "https://api-chat.parstechai.com/v1/robots",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "Rose Flower Shop", "external_id": "shop_10422"},
    timeout=10,
).json()
```

**`Node.js`**

```javascript Node.js
const res = await fetch("https://api-chat.parstechai.com/v1/robots", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Rose Flower Shop", external_id: "shop_10422" }),
});
const robot = await res.json();
```

**`Response`**

```json Response
{
  "id": "rbt_8fK2mQ",
  "name": "Rose Flower Shop",
  "external_id": "shop_10422",
  "channels": [],
  "created_at": "2026-09-20T11:04:33Z"
}
```

`external_id` مال شماست. شناسه مشتری خودتان را در آن بگذارید تا ما آن را در هر رویداد برگردانیم؛
به این ترتیب هیچ‌وقت به جدول تطبیق شناسه‌ها نیاز پیدا نمی‌کنید.

> **Warning**
>
> هر ربات یک واحد از ظرفیت بسته شما را مصرف می‌کند. وقتی ظرفیت تمام شود، خطای
> `403 capacity_exhausted` دریافت می‌کنید. حذف ربات ظرفیت را بلافاصله آزاد می‌کند.

## ۲. شروع اتصال کانال

**`cURL`**

```bash cURL
curl -X POST https://api-chat.parstechai.com/v1/robots/rbt_8fK2mQ/channels \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "type": "instagram" }'
```

**`Python`**

```python Python
channel = requests.post(
    f"https://api-chat.parstechai.com/v1/robots/{robot['id']}/channels",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"type": "instagram"},
    timeout=10,
).json()
```

**`Node.js`**

```javascript Node.js
const res = await fetch(
  `https://api-chat.parstechai.com/v1/robots/${robot.id}/channels`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "instagram" }),
  },
);
const channel = await res.json();
```

**`Response`**

```json Response
{
  "id": "chn_3pQ7xL",
  "type": "instagram",
  "robot_id": "rbt_8fK2mQ",
  "status": "pending_authorisation",
  "authorisation_url": "https://api-chat.parstechai.com/v1/connect/ig/svc_4dR8nW",
  "expires_at": "2026-09-20T12:04:33Z"
}
```

> **Warning**
>
> **این درخواست هنوز چیزی را وصل نمی‌کند.** اینستاگرام لازم می‌داند مالک صفحه در مرورگر خودش
> دسترسی را تأیید کند. او را به `authorisation_url` بفرستید. کانال وقتی فعال می‌شود که این مرحله را تمام کند.
>
> پیش از ساختن این جریان، [اتصال اینستاگرام](/documentation/guides/connect-instagram) را بخوانید. یک ریدایرکت
> به پنل شما وجود دارد که باید اول تنظیم شود.

## ۳. اطمینان از فعال‌بودن کانال

```bash
curl https://api-chat.parstechai.com/v1/robots/rbt_8fK2mQ/channels \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
```

**`Response`**

```json Response
{
  "data": [
    {
      "id": "chn_3pQ7xL",
      "type": "instagram",
      "robot_id": "rbt_8fK2mQ",
      "username": "rose.flower.shop",
      "is_active": true,
      "connected_at": "2026-09-20T11:06:10Z"
    }
  ]
}
```

## ۴. بررسی اولین رویداد

رویدادها به آدرس وب‌هوکی می‌رسند که در پنل تنظیم کرده‌اید. پیش از اعتماد به محتوای رویداد،
امضای آن را بررسی کنید.

**`Event`**

```json Event
{
  "schema_version": "1.0.0",
  "event": "message",
  "delivery_id": "dlv_9fK2mQ",
  "occurred_at": "2026-09-20T11:09:02Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": {
    "conversation_id": "cnv_4dR8nW",
    "message_id": "msg_1aB2cD",
    "source": "direct",
    "role": "client",
    "type": "text",
    "text": "Hi, do you have these roses in stock?",
    "attachments": [],
    "sender": { "id": "iguser_88213", "username": "sara.k" },
    "created_at": "2026-09-20T11:09:02Z"
  }
}
```

امضا در هدر `X-ParsChat-Signature` می‌آید و مقدار آن HMAC-SHA256 بدنه خام درخواست به‌صورت hex است
که با secret شما ساخته شده است.

**`Python`**

```python Python
import hashlib
import hmac

def is_authentic(raw_body: bytes, header_signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_signature)
```

**`Node.js`**

```javascript Node.js
import crypto from "node:crypto";

function isAuthentic(rawBody, headerSignature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerSignature),
  );
}
```

**`PHP`**

```php PHP
function is_authentic(string $rawBody, string $headerSignature, string $secret): bool
{
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $headerSignature);
}
```

> **Warning**
>
> امضا را روی بایت‌های خام و پیش از هر پردازش JSON بررسی کنید. سریال‌سازی دوباره محتوا ترتیب
> کلیدها و فاصله‌ها را تغییر می‌دهد و امضا هرگز تطابق پیدا نمی‌کند.

به‌محض ذخیره‌کردن رویداد، با `2xx` پاسخ دهید. هر پاسخ دیگری، از جمله پایان مهلت (timeout)، دوباره تلاش می‌شود.
[رویدادهای وب‌هوک](/documentation/guides/webhook-events#retries) را ببینید.

## خطاهای رایج

| کد وضعیت | معنی                                                                                                    |
| -------- | ------------------------------------------------------------------------------------------------------- |
| `401`    | کلید اشتباه، باطل‌شده یا منقضی است                                                                      |
| `403`    | نقش لازم را ندارید، بسته غیرفعال است یا ظرفیت تمام شده است                                              |
| `404`    | چنین منبعی وجود ندارد، یا متعلق به شما نیست                                                             |
| `409`    | `external_id` تکراری است، یا کانالی از این نوع از قبل وجود دارد                                         |
| `422`    | اعتبارسنجی ناموفق بود                                                                                   |
| `429`    | از محدودیت نرخ درخواست عبور کرده‌اید. کمی صبر کنید و دوباره تلاش کنید؛ `details` سقف شما را مشخص می‌کند |

همه مقدارهای `code` در [خطاها](/documentation/reference/errors) فهرست شده‌اند.

## قدم بعدی

#### [اتصال اینستاگرام](/documentation/guides/connect-instagram)

جریان کامل ریدایرکت، و آدرس بازگشتی که اول باید تنظیم کنید.

#### [پاسخ به مشتریان](/documentation/guides/replying-to-customers)

متن، فایل و پیام صوتی را برای مشتری نهایی بفرستید.

#### [رویدادهای وب‌هوک](/documentation/guides/webhook-events)

همه انواع رویداد، قرارداد کامل محتوای رویداد و رفتار تلاش دوباره.

#### [خودکارسازی اینستاگرام](/documentation/guides/instagram-automation)

محرک‌های کلیدواژه‌ای، پاسخ عمومی، شرط دنبال‌کردن و هدف‌گیری یک پست مشخص.

#### [مرجع API](/api-reference/robots/create-robot)

همه اندپوینت‌ها، همراه با محیط آزمایش تعاملی.