# Vispa Bot Platform — complete API reference

Contract version: 2.0.0
Canonical API: https://bots.vispaco.net/v2/<methodName>
Human reference: https://docs.vispaco.net/chat/
OpenAPI: https://docs.vispaco.net/chat/openapi.json

This file is standalone usage documentation. Examples use illustrative IDs and tokens. Obtain real identifiers through authorized API responses and explicit user Start; do not infer or manufacture them.

## Canonical API and scope

Public API origin: https://bots.vispaco.net. Invoke a method by POST to /v2/<methodName>; names are case-sensitive. Documentation: https://docs.vispaco.net/chat/. Examples contain illustrative IDs and tokens, not credentials or existing resources. Replace YOUR_BOT_TOKEN and all sample IDs with values actually obtained for your bot. The API is server-to-server; keep tokens out of frontend code, URLs, repositories and logs. This contract covers private bot chats. Group/channel administration, payments, inline queries, reply keyboards, phone/location requests and Mini Apps are not methods of this API.

## Authentication, input and output

Send Authorization: Bearer YOUR_BOT_TOKEN. Tokens are issued/rotated through the messenger bot manager; rotation invalidates the previous token. Default content type is application/json. For uploadFile/direct media upload use multipart/form-data and let the HTTP library create the boundary. Unknown parameters are rejected. Text and captions are plain UTF-8: parse_mode supports only plain; HTML/Markdown are not interpreted. Success is HTTP200 with {"ok":true,"result":...}. Failure is a non-2xx HTTP status with {"ok":false,"error_code":"SYMBOLIC_CODE","description":"...","parameters":{...}}. error_code is a string. Public dates are Unix epoch seconds. Text limits are UTF-8 bytes, not character counts. The maximum JSON request body is1MiB.

## Obtain chat_id through explicit user consent

The user must press Start for this exact bot before receiving its messages. The equivalent user command is /start with an optional 1–64 ASCII letter/digit/_/- parameter. Receive that update through getUpdates/webhook and store message.chat.id or membership.chat_id; getSubscribers lists current consenting members. chat_id is a stable opaque string: vc_ followed by 40 lowercase hex digits. Never invent or derive chat_id, or substitute phone, username or internal user ID. Knowing a chat_id is not permission: membership is independent per bot. Stop (/stop), blocking or unavailable user/bot forbids delivery. Edits require active membership; deletion of the bot's own sent message remains allowed after Stop. A bot cannot edit/delete user messages or another bot's messages.

## Minimum reliable integration

1. Create a bot using the messenger bot manager and securely store its issued token. 2. Verify it with getMe. 3. Ask the user to open and Start the bot. 4. Durably accept the Start update and store its real chat_id. 5. Call sendMessage with that chat_id and text. 6. Store returned message_id per recipient for editing/deletion. Sample IDs in examples do not create membership or resources.

## Pagination and identifiers

getSubscribers/getBroadcastRecipients use limit (1–100, default100) and cursor. Omit cursor initially, pass exact next_cursor into the next request, stop at next_cursor=null. Treat cursors as opaque. Subscriber cursor is a public chat ID; broadcast recipients use their own cursor. Do not confuse update_id, message_id, broadcast_id, file_id and chat_id. Incoming/outgoing message_id share this bot's public message namespace. reply_to_message_id can reference a received or sent message in the same bot chat; replying does not authorize editing/deleting received messages.

## Polling, acknowledgement and deduplication

Choose polling OR webhook. getUpdates returns unacknowledged Updates in ascending update_id order. offset=0 (default) acknowledges nothing. limit is1–100, default100; timeout is only0 (no long polling). After durable acceptance through update_id N, call getUpdates with offset=N+1: IDs smaller than offset are acknowledged. Do not advance offset before durable acceptance. Until acknowledgement a response may repeat, including after transport failure. Deduplicate by update_id in your own database. An Update can contain message, membership or callback_query. Start/Stop command updates contain both message and membership with optional start_parameter. A blocking update can contain membership alone with chat_id, status=stopped and optional reason=blocked, without start_parameter or message. Polling while a webhook is configured returns WEBHOOK_ACTIVE / HTTP409.

## Webhook delivery and verification

setWebhook requires url and secret_token. URL must use HTTPS, public DNS hostname, port443, no embedded credentials/fragment. The server resolves and pins publicly routable addresses per delivery; private/reserved/loopback/link-local destinations, redirects and other ports are rejected. secret_token is16–256 ASCII letters/digits/_/-. Verify X-Vispa-Bot-Secret-Token using a constant-time comparison. The JSON body is an Update directly, not an ok/result envelope. Return2xx after durable acceptance. Delivery is at least once with retries/backoff: deduplicate by update_id. getWebhookInfo reports URL, pending count and last error/success metadata. deleteWebhook enables polling. drop_pending_updates=true deliberately discards queued updates; use it only if that loss is intended.

## Cards and inline buttons

Card types: info/product/status/receipt. Required: type and nonempty title (max256 UTF-8 bytes). Optional text8192, subtitle512, up to12 fields with nonempty label128/value1024 bytes. A receipt is display only, not a payment operation. reply_markup is {"inline_keyboard":[[button,...],...]}, up to10 rows,1–8 buttons per nonempty row and80 overall. Each button has text (max128 bytes) and exactly one action: HTTPS url (max2048), callback_data (max256), copy_text (max256). Empty inline_keyboard removes buttons. Use callback_query.id from the received update in answerCallbackQuery, not raw callback_data or an invented ID. Callback actions are bound to their bot, user and message.

## Safe upload and normalization

uploadFile uses multipart field file; send its returned real file_id in media methods. Direct multipart media upload is also supported. Internet URLs and filesystem paths are not accepted as media input. kind is inferred from verified MIME/filename; uploadFile has no kind parameter. Default upload ceiling50MiB, hard ceiling100MiB; installs may lower it. Default per-bot storage quota1GiB. Originals allowed: JPEG/PNG/WebP; GIF; MP4/M4V, MOV, WebM, MKV; MP3, OGG/OGA/Opus, WAV, FLAC, M4A; passive PDF; TXT/CSV/LOG/JSON. Extension, declared MIME and real MIME must agree under policy. Executables/scripts, HTML/SVG, archives, Office/macros and unsafe double extensions are rejected. Images are decoded/re-encoded (max8192 per dimension,16million pixels). Audio becomes Opus/OGG; video H264/AAC MP4; GIF becomes MP4 kind=animation. Ordinary MP4 has kind=video: use sendVideo, not sendAnimation. sendVoice/sendAudio accept audio-kind files. PDF normalization rejects encrypted, active, linked, form-containing and embedded-file PDFs. Original and normalized files are scanned; missing/failing antivirus or converter rejects upload (fail closed). Storage is outside webroot. Do not rename/relabel unsafe files to bypass policy. Text/JSON documents are additionally limited to5MiB and valid UTF-8 without control/active markup. Audio/video must have a positive duration at most1800seconds and no more than6 streams. Video originals are limited to4096 per dimension and8.5million pixels; output fits1920 by1920 at30fps. Unsafe or unrecognized stream types are rejected. Album member media replacement is restricted to photo/video; editMessageMedia cannot convert an album member to voice/audio/document/animation.

## Ownership, signed downloads, HEAD and ranges

uploadFile returns metadata/file_id, never a private disk path. getFile checks bot ownership and adds download_url plus expires_at (Unix seconds). The signed URL is a private HMAC capability valid for one hour: https://bots.vispaco.net/download.php?id=...&exp=...&sig=.... Use the complete returned URL. Alternatively GET or HEAD https://bots.vispaco.net/download.php?file_id=<real file_id> with Authorization: Bearer. Both modes support a single byte Range, e.g. bytes=0-1023; partial success206 with Content-Range, invalid range416. HEAD returns no body. Keep signed links private. Expired/tampered signatures and cross-bot files are rejected.

## Asynchronous bulk delivery

createBroadcast accepts method (one of eight single-message send methods) and payload without chat_id. Optional chat_ids selects1–10000 existing members of this bot; omission targets members active at creation. sendMediaGroup is not a broadcast method; reply_to_message_id is not used in bulk. A worker delivers asynchronously and rechecks membership/blocking at delivery. Returned broadcast_id/status/counts do not prove receipt. Poll getBroadcast and paginate getBroadcastRecipients. sent means recorded in the messenger, not read. Failed recipients have last_error. Successful recipients have their own message_id; edit/delete using that exact chat_id/message_id. cancelBroadcast cancels pending work, not sent messages. No campaign-wide edit/delete method exists; use per-recipient results with standard methods.

## Idempotency, errors and rate limits

For retryable mutations use Idempotency-Key:1–128 characters A–Z/a–z/0–9/._:-. Reuse it only for the same method/body. A successful replay returns the original result; changed method/body yields IDEMPOTENCY_CONFLICT / HTTP409. Use a fresh key for a new logical action and preserve keys across transport timeouts. A timeout does not prove failure. Default per-bot limits:60API requests/second,20sends/second including broadcasts,10uploads/minute,10createBroadcast/minute; installation limits may differ. RATE_LIMITED / HTTP429 has parameters.retry_after seconds: wait at least that long. For other transient failures use bounded exponential backoff/jitter. Successful idempotency replays do not consume rate counters. Common failures: INVALID_PARAMETER/INVALID_JSON400; UNAUTHORIZED401; BOT_NOT_STARTED/BOT_BLOCKED/BOT_DISABLED403; CHAT_NOT_FOUND/MESSAGE_NOT_FOUND/BROADCAST_NOT_FOUND404; WEBHOOK_ACTIVE/IDEMPOTENCY_CONFLICT409; REQUEST_TOO_LARGE413; RATE_LIMITED429; PLATFORM_DISABLED or unavailable scanner/media503. Media policy errors are symbolic400 failures, missing dependencies503. Fix invalid inputs/access before retrying. HTTP success is not a read receipt.

## Complete method reference

31 public methods follow. All sample requests use POST and the canonical public origin. For authenticated file download, use the separate download route documented above.

### getMe — مشخصات ربات

POST https://bots.vispaco.net/v2/getMe

اعتبار توکن و مشخصات ربات فعلی را بررسی می‌کند.

Parameters: none. Send an empty JSON object `{}`.

Result: شیء شامل id، is_bot، username، display_name و description.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Bot"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/getMe' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/getMe',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {}
response = requests.post(
    'https://bots.vispaco.net/v2/getMe',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### getChat — اطلاعات گفت‌وگو

POST https://bots.vispaco.net/v2/getChat

اطلاعات گفت‌وگو و وضعیت عضویت همین کاربر در همین ربات را برمی‌گرداند.

این متد مجوز ارسال ایجاد نمی‌کند؛ فقط عضویت موجود را می‌خواند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |

Result: شیء شامل id، type=private، status، started_at و stopped_at.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Chat"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/getChat' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/getChat',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
response = requests.post(
    'https://bots.vispaco.net/v2/getChat',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### getChatMember — وضعیت عضویت

POST https://bots.vispaco.net/v2/getChatMember

اطلاعات گفت‌وگو و وضعیت عضویت همین کاربر در همین ربات را برمی‌گرداند.

این متد مجوز ارسال ایجاد نمی‌کند؛ فقط عضویت موجود را می‌خواند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |

Result: شیء شامل id، type=private، status، started_at و stopped_at.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Chat"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/getChatMember' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/getChatMember',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
response = requests.post(
    'https://bots.vispaco.net/v2/getChatMember',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### getUpdates — دریافت رویداد با polling

POST https://bots.vispaco.net/v2/getUpdates

رویدادهای تأییدنشده را به ترتیب update_id برمی‌گرداند؛ این متد long polling نیست.

تا پیش از تأیید ممکن است رویداد دوباره برگردد. هنگام فعال بودن وب‌هوک، خطای WEBHOOK_ACTIVE با HTTP 409 دریافت می‌کنید.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| offset | integer | no | برای تأیید رویدادهای قبلی، آخرین update_id پردازش‌شده + ۱ را بفرستید. شناسه‌های کوچک‌تر تأیید می‌شوند. مقدار ۰ تأییدی انجام نمی‌دهد. |
| limit | integer | no | تعداد رکورد، از ۱ تا ۱۰۰؛ پیش‌فرض ۱۰۰. |
| timeout | integer | no | فقط ۰؛ long polling پشتیبانی نمی‌شود. از short polling یا وب‌هوک استفاده کنید. |

Result: آرایه Update شامل update_id و message، membership یا callback_query.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Update"
      }
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/getUpdates' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "limit": 100
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/getUpdates',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "limit": 100
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "limit": 100
}
response = requests.post(
    'https://bots.vispaco.net/v2/getUpdates',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### setWebhook — تنظیم وب‌هوک

POST https://bots.vispaco.net/v2/setWebhook

ارسال رویدادها به یک نشانی عمومی HTTPS را فعال می‌کند.

هدر X-Vispa-Bot-Secret-Token را با secret_token خود به‌صورت امن مقایسه کنید. پس از پذیرش رویداد پاسخ 2xx بدهید. تحویل دست‌کم یک‌بار است و تلاش مجدد با فاصله افزایشی انجام می‌شود؛ بر اساس update_id از پردازش تکراری جلوگیری کنید.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| url | string | yes | URL با نام دامنه عمومی HTTPS روی پورت ۴۴۳، بدون نام کاربری، رمز یا fragment؛ IP داخلی و مقصد غیرمجاز رد می‌شوند. |
| secret_token | string | yes | ۱۶ تا ۲۵۶ حرف لاتین، رقم، زیرخط یا خط تیره؛ مقدار هدر تأیید وب‌هوک. |
| drop_pending_updates | boolean | no | true رویدادهای منتظر را کنار می‌گذارد؛ پیش‌فرض false. |

Result: true در صورت ثبت موفق.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "type": "boolean"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/setWebhook' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://bot.example.com/webhook",
  "secret_token": "REPLACE_WITH_RANDOM_SECRET_32_BYTES"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/setWebhook',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "url": "https://bot.example.com/webhook",
  "secret_token": "REPLACE_WITH_RANDOM_SECRET_32_BYTES"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "url": "https://bot.example.com/webhook",
  "secret_token": "REPLACE_WITH_RANDOM_SECRET_32_BYTES"
}
response = requests.post(
    'https://bots.vispaco.net/v2/setWebhook',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### deleteWebhook — حذف وب‌هوک

POST https://bots.vispaco.net/v2/deleteWebhook

دریافت با وب‌هوک را متوقف می‌کند و امکان polling را باز می‌کند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| drop_pending_updates | boolean | no | با true رویدادهای منتظر هم کنار گذاشته می‌شوند. |

Result: true.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "type": "boolean"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/deleteWebhook' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/deleteWebhook',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {}
response = requests.post(
    'https://bots.vispaco.net/v2/deleteWebhook',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### getWebhookInfo — وضعیت وب‌هوک

POST https://bots.vispaco.net/v2/getWebhookInfo

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

Parameters: none. Send an empty JSON object `{}`.

Result: url، pending_update_count و در صورت ثبت، last_error، last_error_at و last_success_at.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/WebhookInfo"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/getWebhookInfo' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/getWebhookInfo',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {}
response = requests.post(
    'https://bots.vispaco.net/v2/getWebhookInfo',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### sendMessage — ارسال پیام متنی

POST https://bots.vispaco.net/v2/sendMessage

به یک عضو فعال ربات پیام متنی می‌فرستد.

Start همین ربات الزامی است. message_id خروجی را برای ویرایش یا حذف ذخیره کنید.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| text | string | yes | متن ساده و غیرخالی، حداکثر ۱۶۳۸۴ بایت UTF-8. |
| parse_mode | string | no | فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| reply_to_message_id | integer | no | شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن. |

Result: Message شامل message_id، chat.id، date، type و محتوای پیام.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/sendMessage' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "text": "سلام! به ربات ما خوش آمدید."
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/sendMessage',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "text": "سلام! به ربات ما خوش آمدید."
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "text": "سلام! به ربات ما خوش آمدید."
}
response = requests.post(
    'https://bots.vispaco.net/v2/sendMessage',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### sendPhoto — ارسال عکس

POST https://bots.vispaco.net/v2/sendPhoto

رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود.

ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| photo | string \| binary | yes | file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود. |
| caption | string | no | کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| reply_to_message_id | integer | no | شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن. |
| parse_mode | string | no | فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود. |

Result: Message شامل message_id و اطلاعات عمومی رسانه.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/sendPhoto' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "photo": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/sendPhoto',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "photo": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "photo": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}
response = requests.post(
    'https://bots.vispaco.net/v2/sendPhoto',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### sendVoice — ارسال ویس

POST https://bots.vispaco.net/v2/sendVoice

رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود.

ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| voice | string \| binary | yes | file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود. |
| caption | string | no | کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| reply_to_message_id | integer | no | شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن. |
| parse_mode | string | no | فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود. |

Result: Message شامل message_id و اطلاعات عمومی رسانه.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/sendVoice' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "voice": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/sendVoice',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "voice": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "voice": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}
response = requests.post(
    'https://bots.vispaco.net/v2/sendVoice',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### sendVideo — ارسال فیلم

POST https://bots.vispaco.net/v2/sendVideo

رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود.

ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| video | string \| binary | yes | file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود. |
| caption | string | no | کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| reply_to_message_id | integer | no | شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن. |
| parse_mode | string | no | فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود. |

Result: Message شامل message_id و اطلاعات عمومی رسانه.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/sendVideo' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "video": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/sendVideo',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "video": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "video": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}
response = requests.post(
    'https://bots.vispaco.net/v2/sendVideo',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### sendAudio — ارسال موسیقی و صوت

POST https://bots.vispaco.net/v2/sendAudio

رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود.

ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| audio | string \| binary | yes | file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود. |
| caption | string | no | کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| reply_to_message_id | integer | no | شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن. |
| parse_mode | string | no | فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود. |

Result: Message شامل message_id و اطلاعات عمومی رسانه.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/sendAudio' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "audio": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/sendAudio',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "audio": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "audio": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}
response = requests.post(
    'https://bots.vispaco.net/v2/sendAudio',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### sendDocument — ارسال فایل

POST https://bots.vispaco.net/v2/sendDocument

فایل پاک را به عضو فعال ربات ارسال و آن را در بابل عمومی فایل نمایش می‌دهد؛ حتی اگر محتوای فایل صوت یا فیلم باشد.

ابتدا فایل را با uploadFile بارگذاری کنید؛ نوع واقعی فایل باید با نوع این متد سازگار باشد. ویس و موسیقی از فایل صوتی استفاده می‌کنند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| document | string \| binary | yes | file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود. |
| caption | string | no | کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| reply_to_message_id | integer | no | شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن. |
| parse_mode | string | no | فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود. |

Result: Message شامل message_id و اطلاعات عمومی رسانه.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/sendDocument' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "document": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/sendDocument',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "document": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "document": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}
response = requests.post(
    'https://bots.vispaco.net/v2/sendDocument',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### sendAnimation — ارسال تصویر متحرک

POST https://bots.vispaco.net/v2/sendAnimation

رسانه را به عضو فعال ربات ارسال می‌کند و پیام با بابل مخصوص همان نوع نمایش داده می‌شود.

فایل GIF پاک‌سازی‌شده به ویدئوی MP4 با kind=animation تبدیل می‌شود؛ MP4 آپلودشده معمولی از نوع video است و باید با sendVideo ارسال شود.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| animation | string \| binary | yes | file_id فایل پاک و متعلق به همین ربات؛ یا فایل مستقیم در درخواست multipart. آدرس URL پذیرفته نمی‌شود. |
| caption | string | no | کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| reply_to_message_id | integer | no | شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن. |
| parse_mode | string | no | فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود. |

Result: Message شامل message_id و اطلاعات عمومی رسانه.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/sendAnimation' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "animation": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/sendAnimation',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "animation": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "animation": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "caption": "نمونه رسانه"
}
response = requests.post(
    'https://bots.vispaco.net/v2/sendAnimation',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### sendMediaGroup — ارسال آلبوم

POST https://bots.vispaco.net/v2/sendMediaGroup

۲ تا ۱۰ عکس یا فیلم را به‌عنوان یک آلبوم می‌فرستد.

در این نسخه آلبوم، دکمه و پاسخ به پیام ندارد.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| media | array | yes | ۲ تا ۱۰ شیء با type برابر photo/video، فیلد media برابر file_id و caption اختیاری. |

Result: آرایه Message؛ هر عضو message_id مستقل دارد.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Message"
      }
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/sendMediaGroup' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "media": [
    {
      "type": "photo",
      "media": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    },
    {
      "type": "photo",
      "media": "cccccccccccccccccccccccccccccccccccccccccccccccc"
    }
  ]
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/sendMediaGroup',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "media": [
    {
      "type": "photo",
      "media": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    },
    {
      "type": "photo",
      "media": "cccccccccccccccccccccccccccccccccccccccccccccccc"
    }
  ]
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "media": [
    {
      "type": "photo",
      "media": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    },
    {
      "type": "photo",
      "media": "cccccccccccccccccccccccccccccccccccccccccccccccc"
    }
  ]
}
response = requests.post(
    'https://bots.vispaco.net/v2/sendMediaGroup',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### sendCard — ارسال کارت تعاملی

POST https://bots.vispaco.net/v2/sendCard

یک کارت ساختاریافته از نوع اطلاع‌رسانی، محصول، وضعیت یا رسید می‌فرستد.

کارت رسید فقط نمایشی است؛ این متد عملیات پرداخت یا تأیید تراکنش انجام نمی‌دهد.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| card | object | yes | type: info/product/status/receipt؛ title الزامی تا ۲۵۶ بایت، text تا ۸۱۹۲، subtitle تا ۵۱۲ و fields تا ۱۲ جفت label (۱۲۸) و value (۱۰۲۴ بایت UTF-8). |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| reply_to_message_id | integer | no | شناسه پیام ورودی یا خروجی در همین ربات و همین گفت‌وگو برای پاسخ به آن. |
| parse_mode | string | no | فقط plain پذیرفته می‌شود؛ فرمت‌دهی HTML/Markdown پشتیبانی نمی‌شود. |

Result: Message با type=card و شیء card.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/sendCard' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "card": {
    "type": "status",
    "title": "سفارش آماده شد",
    "text": "سفارش شما آماده ارسال است.",
    "fields": [
      {
        "label": "شماره سفارش",
        "value": "1042"
      }
    ]
  },
  "reply_markup": {
    "inline_keyboard": [
      [
        {
          "text": "پیگیری سفارش",
          "callback_data": "order:1042"
        }
      ]
    ]
  }
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/sendCard',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "card": {
    "type": "status",
    "title": "سفارش آماده شد",
    "text": "سفارش شما آماده ارسال است.",
    "fields": [
      {
        "label": "شماره سفارش",
        "value": "1042"
      }
    ]
  },
  "reply_markup": {
    "inline_keyboard": [
      [
        {
          "text": "پیگیری سفارش",
          "callback_data": "order:1042"
        }
      ]
    ]
  }
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "card": {
    "type": "status",
    "title": "سفارش آماده شد",
    "text": "سفارش شما آماده ارسال است.",
    "fields": [
      {
        "label": "شماره سفارش",
        "value": "1042"
      }
    ]
  },
  "reply_markup": {
    "inline_keyboard": [
      [
        {
          "text": "پیگیری سفارش",
          "callback_data": "order:1042"
        }
      ]
    ]
  }
}
response = requests.post(
    'https://bots.vispaco.net/v2/sendCard',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### answerCallbackQuery — پاسخ به کلیک دکمه

POST https://bots.vispaco.net/v2/answerCallbackQuery

به callback_query دریافتی از کلیک کاربر پاسخ می‌دهد.

دکمه callback به کاربر و پیام مشخص متصل است؛ داده callback_data دلخواه دیگران پذیرفته نمی‌شود.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| callback_query_id | string | yes | id رویداد callback_query که همین ربات دریافت کرده است. |
| text | string | no | متن پاسخ، حداکثر ۱۰۲۴ بایت UTF-8. |
| show_alert | boolean | no | درخواست نمایش به‌صورت اعلان برجسته؛ پیش‌فرض false. |

Result: true.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "type": "boolean"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/answerCallbackQuery' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "callback_query_id": "dddddddddddddddddddddddddddddddddddddddddddddddd",
  "text": "درخواست شما ثبت شد.",
  "show_alert": false
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/answerCallbackQuery',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "callback_query_id": "dddddddddddddddddddddddddddddddddddddddddddddddd",
  "text": "درخواست شما ثبت شد.",
  "show_alert": false
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "callback_query_id": "dddddddddddddddddddddddddddddddddddddddddddddddd",
  "text": "درخواست شما ثبت شد.",
  "show_alert": False
}
response = requests.post(
    'https://bots.vispaco.net/v2/answerCallbackQuery',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### editMessageText — ویرایش متن پیام

POST https://bots.vispaco.net/v2/editMessageText

محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند.

فقط پیام متنی همین ربات قابل ویرایش است. عضویت فعال برای ویرایش الزامی است.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| message_id | integer | yes | شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید. |
| text | string | yes | متن ساده و غیرخالی، حداکثر ۱۶۳۸۴ بایت UTF-8. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| parse_mode | string | no | فقط plain؛ متن و کپشن بدون HTML/Markdown پردازش می‌شوند. |

Result: Message به‌روزشده.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/editMessageText' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "text": "متن به‌روزرسانی شد."
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/editMessageText',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "text": "متن به‌روزرسانی شد."
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "text": "متن به‌روزرسانی شد."
}
response = requests.post(
    'https://bots.vispaco.net/v2/editMessageText',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### editMessageCaption — ویرایش کپشن رسانه

POST https://bots.vispaco.net/v2/editMessageCaption

محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند.

فقط پیام رسانه؛ برای حذف کپشن رشته خالی بفرستید. عضویت فعال برای ویرایش الزامی است.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| message_id | integer | yes | شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید. |
| caption | string | no | کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |
| parse_mode | string | no | فقط plain؛ متن و کپشن بدون HTML/Markdown پردازش می‌شوند. |

Result: Message به‌روزشده.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/editMessageCaption' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "caption": "کپشن جدید"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/editMessageCaption',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "caption": "کپشن جدید"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "caption": "کپشن جدید"
}
response = requests.post(
    'https://bots.vispaco.net/v2/editMessageCaption',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### editMessageMedia — جایگزینی رسانه

POST https://bots.vispaco.net/v2/editMessageMedia

محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند.

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

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| message_id | integer | yes | شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید. |
| media | string | yes | file_id پاک و متعلق به همین ربات. |
| type | string | no | photo، voice، video، audio، document یا animation؛ پیش‌فرض نوع قبلی. |
| caption | string | no | کپشن ساده، حداکثر ۴۰۹۶ بایت UTF-8؛ بدون HTML یا Markdown. |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |

Result: Message به‌روزشده.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/editMessageMedia' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "media": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "type": "photo"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/editMessageMedia',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "media": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "type": "photo"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "media": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "type": "photo"
}
response = requests.post(
    'https://bots.vispaco.net/v2/editMessageMedia',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### editMessageCard — ویرایش کارت

POST https://bots.vispaco.net/v2/editMessageCard

محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند.

فقط پیام کارت؛ شیء کامل کارت جدید را بفرستید. عضویت فعال برای ویرایش الزامی است.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| message_id | integer | yes | شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید. |
| card | object | yes | type: info/product/status/receipt؛ title الزامی تا ۲۵۶ بایت، text تا ۸۱۹۲، subtitle تا ۵۱۲ و fields تا ۱۲ جفت label (۱۲۸) و value (۱۰۲۴ بایت UTF-8). |
| reply_markup | object | no | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |

Result: Message به‌روزشده.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/editMessageCard' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "card": {
    "type": "status",
    "title": "سفارش آماده شد",
    "text": "سفارش شما آماده ارسال است.",
    "fields": [
      {
        "label": "شماره سفارش",
        "value": "1042"
      }
    ]
  }
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/editMessageCard',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "card": {
    "type": "status",
    "title": "سفارش آماده شد",
    "text": "سفارش شما آماده ارسال است.",
    "fields": [
      {
        "label": "شماره سفارش",
        "value": "1042"
      }
    ]
  }
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "card": {
    "type": "status",
    "title": "سفارش آماده شد",
    "text": "سفارش شما آماده ارسال است.",
    "fields": [
      {
        "label": "شماره سفارش",
        "value": "1042"
      }
    ]
  }
}
response = requests.post(
    'https://bots.vispaco.net/v2/editMessageCard',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### editMessageReplyMarkup — ویرایش دکمه‌های پیام

POST https://bots.vispaco.net/v2/editMessageReplyMarkup

محتوای پیام قبلی همین ربات را در همان گفت‌وگو به‌روزرسانی می‌کند.

آرایه خالی inline_keyboard دکمه‌های پیام را حذف می‌کند. عضویت فعال برای ویرایش الزامی است.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| message_id | integer | yes | شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید. |
| reply_markup | object | yes | inline_keyboard شامل حداکثر ۱۰ ردیف و ۸۰ دکمه؛ هر ردیف ۱ تا ۸ دکمه. هر دکمه text و دقیقاً یکی از url (HTTPS)، callback_data یا copy_text دارد. برای حذف دکمه‌ها آرایه خالی بفرستید. |

Result: Message به‌روزشده.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Message"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/editMessageReplyMarkup' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "reply_markup": {
    "inline_keyboard": []
  }
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/editMessageReplyMarkup',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "reply_markup": {
    "inline_keyboard": []
  }
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42,
  "reply_markup": {
    "inline_keyboard": []
  }
}
response = requests.post(
    'https://bots.vispaco.net/v2/editMessageReplyMarkup',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### deleteMessage — حذف پیام

POST https://bots.vispaco.net/v2/deleteMessage

یک پیام خروجی همین ربات را حذف می‌کند.

حذف پیام متعلق به ربات پس از Stop هم مجاز است؛ پیام دیگران قابل حذف نیست.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| message_id | integer | yes | شناسه پیام خروجی همین ربات در همین گفت‌وگو؛ از پاسخ ارسال ذخیره کنید. |

Result: true؛ حذف دوباره همان پیام نیز true است.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "type": "boolean"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/deleteMessage' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/deleteMessage',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_id": 42
}
response = requests.post(
    'https://bots.vispaco.net/v2/deleteMessage',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### deleteMessages — حذف چند پیام

POST https://bots.vispaco.net/v2/deleteMessages

۱ تا ۱۰۰ پیام خروجی همین ربات را در یک گفت‌وگو حذف می‌کند.

تمام شناسه‌ها باید به همین ربات و chat_id تعلق داشته باشند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chat_id | string | yes | شناسه پایدار گفت‌وگوی متعلق به این ربات، مانند vc_… . |
| message_ids | array | yes | ۱ تا ۱۰۰ شناسه مثبت message_id از پیام‌های خروجی همین ربات. |

Result: true در صورت موفقیت.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "type": "boolean"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/deleteMessages' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_ids": [
    42,
    43
  ]
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/deleteMessages',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_ids": [
    42,
    43
  ]
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "chat_id": "vc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message_ids": [
    42,
    43
  ]
}
response = requests.post(
    'https://bots.vispaco.net/v2/deleteMessages',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### uploadFile — بارگذاری امن فایل

POST https://bots.vispaco.net/v2/uploadFile

فایل را در قرنطینه بررسی، اسکن و به قالب امن تبدیل می‌کند؛ فقط فایل پاک شناسه قابل‌ارسال می‌گیرد.

پیش‌فرض سقف ۵۰ MiB و سقف سخت ۱۰۰ MiB است؛ مدیر نصب می‌تواند حد پایین‌تری تعیین کند. فایل اجرایی، HTML، SVG، آرشیو و فایل ماکرو رد می‌شوند. نوع فایل از نام و MIME واقعی تشخیص داده می‌شود؛ پارامتر kind وجود ندارد. سهمیه ذخیره‌سازی پیش‌فرض هر ربات ۱ GiB است و مدیر نصب می‌تواند آن را تغییر دهد.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| file | binary | yes | فایل multipart؛ نام فایل باید پسوند مجاز و سازگار با MIME واقعی داشته باشد. |

Result: اطلاعات فایل شامل file_id، kind، mime_type، file_name، file_size، sha256 و متادیتای موجود.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/File"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/uploadFile' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --form 'file=@./photo.jpg'
```

JavaScript example:
```javascript
// Node.js 22+ — execute on your server
import { readFile } from 'node:fs/promises';
const form = new FormData();
form.set('file', new Blob([await readFile('./photo.jpg')]), 'photo.jpg');
const response = await fetch('https://bots.vispaco.net/v2/uploadFile', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN },
  body: form
});
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
with open('photo.jpg', 'rb') as file:
    response = requests.post(
        'https://bots.vispaco.net/v2/uploadFile',
        headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
        files={'file': ('photo.jpg', file, 'image/jpeg')},
        timeout=60
    )
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### getFile — اطلاعات فایل

POST https://bots.vispaco.net/v2/getFile

اطلاعات عمومی فایل پاک و متعلق به همین ربات را می‌خواند.

لینک امضاشده را محرمانه نگه دارید. برای دانلود سمت سرور می‌توانید GET یا HEAD به https://bots.vispaco.net/download.php?file_id=… با هدر Authorization: Bearer بفرستید. هر دو مسیر دانلود Range را پشتیبانی می‌کنند؛ مسیر خصوصی دیسک افشا نمی‌شود.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| file_id | string | yes | شناسه فایل پاک همین ربات؛ از پاسخ uploadFile یا پیام بگیرید. |

Result: اطلاعات عمومی File به‌همراه download_url امضاشده با اعتبار یک ساعت و expires_at به ثانیه Unix.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/DownloadFile"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/getFile' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/getFile',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "file_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "file_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
response = requests.post(
    'https://bots.vispaco.net/v2/getFile',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### getSubscribers — فهرست اعضای فعال

POST https://bots.vispaco.net/v2/getSubscribers

اعضای فعال ربات را به‌صورت صفحه‌بندی‌شده برمی‌گرداند.

عضویت ممکن است پس از این پاسخ تغییر کند؛ مجوز ارسال دوباره بررسی می‌شود.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| cursor | string | no | next_cursor پاسخ قبلی؛ در اولین درخواست حذف شود. مقدار را به‌عنوان توکن صفحه‌بندی نگه دارید. |
| limit | integer | no | تعداد رکورد، از ۱ تا ۱۰۰؛ پیش‌فرض ۱۰۰. |

Result: subscribers شامل chat_id و started_at، به‌همراه next_cursor یا null.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/SubscriberPage"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/getSubscribers' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "limit": 100
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/getSubscribers',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "limit": 100
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "limit": 100
}
response = requests.post(
    'https://bots.vispaco.net/v2/getSubscribers',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### createBroadcast — ساخت ارسال انبوه

POST https://bots.vispaco.net/v2/createBroadcast

ارسال متن، رسانه یا کارت را در صف ارسال انبوه ثبت می‌کند؛ ارسال با worker انجام می‌شود.

مجوز هر مخاطب هنگام پردازش بررسی می‌شود. sent یعنی ثبت پیام در پیام‌رسان؛ رسید خواندن نیست. برای جلوگیری از ساخت کمپین تکراری از Idempotency-Key استفاده کنید.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| method | string | yes | یکی از sendMessage، sendPhoto، sendVoice، sendVideo، sendAudio، sendDocument، sendAnimation یا sendCard. |
| payload | object | yes | پارامترهای متد ارسال بدون chat_id؛ reply_to_message_id در انبوه استفاده نمی‌شود. |
| chat_ids | array | no | اختیاری: ۱ تا ۱۰٬۰۰۰ chat_id از مخاطبان همین ربات. با حذف این فیلد همه اعضای فعال فعلی هدف می‌شوند. |

Result: broadcast_id، status، counts، created_at و completed_at.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Broadcast"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/createBroadcast' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "method": "sendMessage",
  "payload": {
    "text": "خبر تازه برای اعضای ربات"
  }
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/createBroadcast',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "method": "sendMessage",
  "payload": {
    "text": "خبر تازه برای اعضای ربات"
  }
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "method": "sendMessage",
  "payload": {
    "text": "خبر تازه برای اعضای ربات"
  }
}
response = requests.post(
    'https://bots.vispaco.net/v2/createBroadcast',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### getBroadcast — وضعیت ارسال انبوه

POST https://bots.vispaco.net/v2/getBroadcast

وضعیت کلی و شمارش نتایج یک ارسال انبوه را می‌خواند.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| broadcast_id | integer | yes | شناسه ارسال انبوه متعلق به همین ربات. |

Result: broadcast_id، status و counts شامل queued، sent، failed و cancelled، به‌همراه زمان‌ها.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/Broadcast"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/getBroadcast' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "broadcast_id": 12
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/getBroadcast',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "broadcast_id": 12
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "broadcast_id": 12
}
response = requests.post(
    'https://bots.vispaco.net/v2/getBroadcast',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### getBroadcastRecipients — نتیجه تک‌تک مخاطبان

POST https://bots.vispaco.net/v2/getBroadcastRecipients

نتیجه ارسال هر مخاطب را صفحه‌بندی‌شده می‌خواند.

برای ویرایش یا حذف یک پیام انبوه، chat_id و message_id نتیجه همان مخاطب را در متد ویرایش/حذف استفاده کنید.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| broadcast_id | integer | yes | شناسه ارسال انبوه متعلق به همین ربات. |
| cursor | string | no | next_cursor پاسخ قبلی؛ در اولین درخواست حذف شود. مقدار را به‌عنوان توکن صفحه‌بندی نگه دارید. |
| limit | integer | no | تعداد رکورد، از ۱ تا ۱۰۰؛ پیش‌فرض ۱۰۰. |

Result: recipients شامل chat_id، status، message_id و last_error، به‌همراه next_cursor.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "$ref": "#/components/schemas/BroadcastRecipientPage"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/getBroadcastRecipients' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "broadcast_id": 12,
  "limit": 100
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/getBroadcastRecipients',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "broadcast_id": 12,
  "limit": 100
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "broadcast_id": 12,
  "limit": 100
}
response = requests.post(
    'https://bots.vispaco.net/v2/getBroadcastRecipients',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

### cancelBroadcast — لغو ارسال انبوه

POST https://bots.vispaco.net/v2/cancelBroadcast

ارسال‌های هنوز منتظر را لغو می‌کند.

پیام‌های قبلاً ارسال‌شده حذف نمی‌شوند؛ برای حذف آن‌ها از message_id هر مخاطب استفاده کنید.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| broadcast_id | integer | yes | شناسه ارسال انبوه متعلق به همین ربات. |

Result: true.

Success response schema (common references are defined below):
```json
{
  "type": "object",
  "required": [
    "ok",
    "result"
  ],
  "properties": {
    "ok": {
      "const": true
    },
    "result": {
      "type": "boolean"
    }
  }
}
```

cURL example:
```sh
curl --request POST 'https://bots.vispaco.net/v2/cancelBroadcast' \
  --header 'Authorization: Bearer YOUR_BOT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "broadcast_id": 12
}'
```

JavaScript example:
```javascript
// Execute on your server; never expose the bot token in a browser.
const response = await fetch(
  'https://bots.vispaco.net/v2/cancelBroadcast',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VISPA_BOT_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "broadcast_id": 12
})
  }
);
const data = await response.json();
if (!data.ok) throw new Error(data.description);
console.log(data.result);
```

Python example:
```python
# pip install requests — execute on your server
import os
import requests
payload = {
  "broadcast_id": 12
}
response = requests.post(
    'https://bots.vispaco.net/v2/cancelBroadcast',
    headers={'Authorization': 'Bearer ' + os.environ['VISPA_BOT_TOKEN']},
    json=payload,
    timeout=60
)
data = response.json()
if not data.get('ok'):
    raise RuntimeError(data.get('description'))
print(data['result'])
```

## Common object schemas

These JSON Schema objects define every common reference used in the method response schemas. Optional fields may be omitted; nullable fields may be null. UTF-8 byte limits are described in the usage and parameter text, because JSON Schema maxLength counts characters.

### Card

```json
{
  "type": "object",
  "required": [
    "type",
    "title"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "info",
        "product",
        "status",
        "receipt"
      ]
    },
    "title": {
      "type": "string",
      "description": "Nonempty; max 256 UTF-8 bytes."
    },
    "text": {
      "type": "string",
      "description": "Max 8192 UTF-8 bytes."
    },
    "subtitle": {
      "type": "string",
      "description": "Max 512 UTF-8 bytes."
    },
    "fields": {
      "type": "array",
      "maxItems": 12,
      "items": {
        "type": "object",
        "required": [
          "label",
          "value"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "Nonempty; max 128 UTF-8 bytes."
          },
          "value": {
            "type": "string",
            "description": "Nonempty; max 1024 UTF-8 bytes."
          }
        }
      }
    }
  }
}
```

### Button

```json
{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "description": "Nonempty; max 128 UTF-8 bytes."
    },
    "url": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "No embedded credentials; max 2048 UTF-8 bytes."
    },
    "callback_data": {
      "type": "string",
      "description": "Nonempty; max 256 UTF-8 bytes."
    },
    "copy_text": {
      "type": "string",
      "description": "Nonempty; max 256 UTF-8 bytes."
    }
  },
  "oneOf": [
    {
      "required": [
        "url"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "callback_data"
            ]
          },
          {
            "required": [
              "copy_text"
            ]
          }
        ]
      }
    },
    {
      "required": [
        "callback_data"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "url"
            ]
          },
          {
            "required": [
              "copy_text"
            ]
          }
        ]
      }
    },
    {
      "required": [
        "copy_text"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "url"
            ]
          },
          {
            "required": [
              "callback_data"
            ]
          }
        ]
      }
    }
  ]
}
```

### ReplyMarkup

```json
{
  "type": "object",
  "required": [
    "inline_keyboard"
  ],
  "properties": {
    "inline_keyboard": {
      "type": "array",
      "maxItems": 10,
      "description": "Maximum 80 buttons overall. Empty array removes all buttons.",
      "items": {
        "type": "array",
        "minItems": 1,
        "maxItems": 8,
        "items": {
          "$ref": "#/components/schemas/Button"
        }
      }
    }
  }
}
```

### InputMedia

```json
{
  "type": "object",
  "required": [
    "type",
    "media"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "photo",
        "video"
      ]
    },
    "media": {
      "type": "string",
      "pattern": "^[a-f0-9]{48}$"
    },
    "caption": {
      "type": "string",
      "description": "Maximum 4096 UTF-8 bytes."
    }
  }
}
```

### ApiError

```json
{
  "type": "object",
  "required": [
    "ok",
    "error_code",
    "description"
  ],
  "properties": {
    "ok": {
      "const": false
    },
    "error_code": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "parameters": {
      "type": "object",
      "additionalProperties": true
    }
  }
}
```

### Message

```json
{
  "type": "object",
  "required": [
    "message_id",
    "chat",
    "date",
    "type"
  ],
  "properties": {
    "message_id": {
      "type": "integer"
    },
    "chat": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "const": "private"
        }
      }
    },
    "date": {
      "type": "integer",
      "description": "Unix epoch seconds."
    },
    "type": {
      "type": "string"
    },
    "text": {
      "type": "string"
    },
    "caption": {
      "type": "string"
    },
    "card": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/Card"
        },
        {
          "type": "null"
        }
      ]
    },
    "file": {
      "type": [
        "object",
        "null"
      ]
    },
    "reply_markup": {
      "$ref": "#/components/schemas/ReplyMarkup"
    },
    "from": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        }
      }
    }
  },
  "additionalProperties": true
}
```

### Chat

```json
{
  "type": "object",
  "required": [
    "id",
    "type",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "const": "private"
    },
    "status": {
      "type": "string"
    },
    "started_at": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Unix epoch seconds."
    },
    "stopped_at": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Unix epoch seconds."
    }
  }
}
```

### File

```json
{
  "type": "object",
  "required": [
    "file_id",
    "mime_type",
    "file_name",
    "file_size",
    "kind",
    "sha256"
  ],
  "properties": {
    "file_id": {
      "type": "string"
    },
    "mime_type": {
      "type": "string"
    },
    "file_name": {
      "type": "string"
    },
    "file_size": {
      "type": "integer"
    },
    "kind": {
      "type": "string"
    },
    "sha256": {
      "type": "string"
    },
    "width": {
      "type": [
        "integer",
        "null"
      ]
    },
    "height": {
      "type": [
        "integer",
        "null"
      ]
    },
    "duration": {
      "type": [
        "number",
        "null"
      ]
    }
  },
  "additionalProperties": true
}
```

### Update

```json
{
  "type": "object",
  "required": [
    "update_id"
  ],
  "properties": {
    "update_id": {
      "type": "integer"
    },
    "message": {
      "$ref": "#/components/schemas/Message"
    },
    "membership": {
      "$ref": "#/components/schemas/Membership"
    },
    "callback_query": {
      "$ref": "#/components/schemas/CallbackQuery"
    }
  },
  "additionalProperties": true
}
```

### Broadcast

```json
{
  "type": "object",
  "required": [
    "broadcast_id",
    "status",
    "counts"
  ],
  "properties": {
    "broadcast_id": {
      "type": "integer"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "completed",
        "cancelled"
      ]
    },
    "counts": {
      "type": "object",
      "properties": {
        "queued": {
          "type": "integer"
        },
        "sent": {
          "type": "integer"
        },
        "failed": {
          "type": "integer"
        },
        "cancelled": {
          "type": "integer"
        }
      }
    },
    "created_at": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Unix epoch seconds."
    },
    "completed_at": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Unix epoch seconds."
    }
  }
}
```

### DownloadFile

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/File"
    },
    {
      "type": "object",
      "required": [
        "download_url",
        "expires_at"
      ],
      "properties": {
        "download_url": {
          "type": "string",
          "format": "uri",
          "description": "Signed URL, expires after one hour. Treat as a private bearer capability."
        },
        "expires_at": {
          "type": "integer",
          "description": "Unix epoch seconds."
        }
      }
    }
  ]
}
```

### Bot

```json
{
  "type": "object",
  "required": [
    "id",
    "is_bot",
    "username",
    "display_name",
    "description"
  ],
  "properties": {
    "id": {
      "type": "integer"
    },
    "is_bot": {
      "const": true
    },
    "username": {
      "type": "string"
    },
    "display_name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    }
  }
}
```

### WebhookInfo

```json
{
  "type": "object",
  "required": [
    "url",
    "pending_update_count"
  ],
  "properties": {
    "url": {
      "type": "string"
    },
    "pending_update_count": {
      "type": "integer"
    },
    "last_error": {
      "type": [
        "string",
        "null"
      ]
    },
    "last_error_at": {
      "type": [
        "integer",
        "null"
      ]
    },
    "last_success_at": {
      "type": [
        "integer",
        "null"
      ]
    }
  }
}
```

### SubscriberPage

```json
{
  "type": "object",
  "required": [
    "subscribers",
    "next_cursor"
  ],
  "properties": {
    "subscribers": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "chat_id",
          "started_at"
        ],
        "properties": {
          "chat_id": {
            "type": "string"
          },
          "started_at": {
            "type": "integer"
          }
        }
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
```

### BroadcastRecipientPage

```json
{
  "type": "object",
  "required": [
    "recipients",
    "next_cursor"
  ],
  "properties": {
    "recipients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "chat_id",
          "status",
          "message_id",
          "last_error"
        ],
        "properties": {
          "chat_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "sent",
              "failed",
              "cancelled"
            ]
          },
          "message_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
```

### Membership

```json
{
  "type": "object",
  "required": [
    "chat_id",
    "status"
  ],
  "properties": {
    "chat_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "stopped"
      ]
    },
    "start_parameter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional; emitted for Start/Stop command updates."
    },
    "reason": {
      "type": "string",
      "enum": [
        "blocked"
      ],
      "description": "Optional; a blocking event can emit membership alone without a message or start_parameter."
    }
  }
}
```

### CallbackQuery

```json
{
  "type": "object",
  "required": [
    "id",
    "from",
    "chat_id",
    "message_id",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "from": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string"
        }
      }
    },
    "chat_id": {
      "type": "string"
    },
    "message_id": {
      "type": "integer"
    },
    "data": {
      "type": "string"
    }
  }
}
```

## Documentation maintenance

Every new or changed API capability must update the same methods.json contract, OpenAPI, examples and these generated plain-text references in the same release. Undocumented/unimplemented Telegram-compatible methods must not be assumed to exist.