توسعه‌دهندگان پیکو 🤖

👋ربات پیکو چیست؟

ربات یک برنامه‌ی کوچک است که در پیکو مثل یک مخاطب عادی با آدم‌ها صحبت می‌کند. شما آن را با هر زبان برنامه‌نویسی می‌نویسید، هر جا خواستید اجرا می‌کنید و ربات از راه یک API ساده روی HTTPS با پیکو حرف می‌زند.

Bot API پیکو همان شکل و قالب تلگرام را دارد؛ پس اگر قبلاً ربات تلگرام نوشته‌اید، بیشترش را از قبل بلدید. 🎉

🚀شروع سریع

1. ربات را بسازید. در پیکو @botfather را باز کنید و /newbot را بفرستید. یک نام و یک نام کاربری که به bot ختم شود انتخاب کنید.
2. توکن را کپی کنید. بات‌فادر توکنی شبیه 123456:AbCdEf-your-token می‌فرستد. برای کپی روی آن بزنید. هر وقت خواستید دوباره می‌توانید ببینیدش: /mybots ← ربات شما ← 🔑 توکن API.
3. به رباتتان سلام کنید. آن را باز کنید و Start را بزنید. ربات‌ها هرگز نمی‌توانند به کسی که اول به آن‌ها پیام نداده، پیام بدهند.
4. یک برنامه اجرا کنید. یکی از مثال‌های زیر را بردارید، توکن را بگذارید و به رباتتان پیام بدهید. 🎈

curl "https://picogram.ir/bot123456:AbCdEf-your-token/getMe"

curl -X POST "https://picogram.ir/bot123456:AbCdEf-your-token/sendMessage" \
  -H "content-type: application/json" \
  -d '{"chat_id": 42, "text": "Hello from my bot 👋"}'

import requests

TOKEN = "123456:AbCdEf-your-token"
API = f"https://picogram.ir/bot{TOKEN}"
offset = 0

while True:
    r = requests.get(f"{API}/getUpdates", params={"offset": offset, "timeout": 30}, timeout=40).json()
    for u in r["result"]:
        offset = u["update_id"] + 1
        m = u.get("message")
        if m and m.get("text"):
            requests.post(f"{API}/sendMessage", json={"chat_id": m["chat"]["id"], "text": f"You said: {m['text']}"})

const TOKEN = "123456:AbCdEf-your-token";
const API = `https://picogram.ir/bot${TOKEN}`;
let offset = 0;

for (;;) {
  const r = await (await fetch(`${API}/getUpdates?offset=${offset}&timeout=30`)).json();
  for (const u of r.result) {
    offset = u.update_id + 1;
    const m = u.message;
    if (m?.text) {
      await fetch(`${API}/sendMessage`, {
        method: "POST", headers: { "content-type": "application/json" },
        body: JSON.stringify({ chat_id: m.chat.id, text: `You said: ${m.text}` }),
      });
    }
  }
}

<?php
$api = "https://picogram.ir/bot" . getenv("PICO_TOKEN");
$offset = 0;

while (true) {
    $res = json_decode(file_get_contents("$api/getUpdates?offset=$offset&timeout=30"), true);
    foreach ($res["result"] as $u) {
        $offset = $u["update_id"] + 1;
        if (!empty($u["message"]["text"])) {
            $m = $u["message"];
            file_get_contents("$api/sendMessage?" . http_build_query([
                "chat_id" => $m["chat"]["id"], "text" => "You said: " . $m["text"],
            ]));
        }
    }
}

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"strings"
)

const api = "https://picogram.ir/bot123456:AbCdEf-your-token"

func main() {
	offset := 0
	for {
		resp, err := http.Get(fmt.Sprintf("%s/getUpdates?offset=%d&timeout=30", api, offset))
		if err != nil { continue }
		var out struct {
			Result []struct {
				UpdateID int `json:"update_id"`
				Message  *struct {
					Text string `json:"text"`
					Chat struct{ ID int `json:"id"` } `json:"chat"`
				} `json:"message"`
			} `json:"result"`
		}
		json.NewDecoder(resp.Body).Decode(&out)
		resp.Body.Close()
		for _, u := range out.Result {
			offset = u.UpdateID + 1
			if u.Message != nil && u.Message.Text != "" {
				http.PostForm(api+"/sendMessage", url.Values{
					"chat_id": {fmt.Sprint(u.Message.Chat.ID)}, "text": {"You said: " + strings.TrimSpace(u.Message.Text)}})
			}
		}
	}
}

🌐چطور وصل شویم

همه‌ی درخواست‌ها به این نشانی می‌روند:

https://picogram.ir/bot<TOKEN>/<METHOD>

• 🔒 فقط HTTPS.
• 📨 پارامترها را به‌صورت query string، بدنه‌ی JSON (content-type: application/json) یا هر دو بفرستید. هم GET و هم POST کار می‌کند.
• 📦 پاسخ همیشه JSON است: در حالت موفق {"ok": true, "result": …} و در حالت خطا {"ok": false, "error_code": 400, "description": "…"}.
• 🐢 سقف درخواست: ۶۰۰ درخواست در دقیقه برای هر آدرس IP.

کتابخانه‌های تلگرام

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

# python-telegram-bot
Application.builder().token(TOKEN).base_url("https://picogram.ir/bot").build()

# aiogram 3
AiohttpSession(api=TelegramAPIServer.from_base("https://picogram.ir"))

# grammY
new Bot(TOKEN, { client: { apiRoot: "https://picogram.ir" } })

# Telegraf
new Telegraf(TOKEN, { telegram: { apiRoot: "https://picogram.ir" } })

# node-telegram-bot-api
new TelegramBot(TOKEN, { polling: true, baseApiUrl: "https://picogram.ir" })

💻زبان‌ها و قالب‌ها

برای پیکو فرقی ندارد ربات را با چه زبانی بنویسید. اگر زبان شما بتواند درخواست HTTPS بفرستد و JSON بخواند، کار می‌کند: پایتون، جاوااسکریپت / تایپ‌اسکریپت (Node، Deno، Bun)، PHP، Go، جاوا، کاتلین، C#، Rust، روبی، دارت، سوئیفت، اسکریپت شل… 🌍

📚متدها

🖼عکس، ویدئو و فایل

ربات شما می‌تواند هر چیزی را که آدم‌ها در پیکو می‌فرستند بفرستد و دریافت هم بکند.

همه‌ی این‌ها chat_id، caption (تا ۱۰۲۴ نویسه)، parse_mode، reply_to_message_id و reply_markup را هم می‌گیرند. برای ویدئو و صدا می‌توانید duration، width و height هم بدهید.

خود فایل را سه‌ جور می‌توان داد:

# 1) upload a file from your computer (multipart/form-data)
curl -F chat_id=42 -F caption="Look 👀" -F photo=@cat.jpg "https://picogram.ir/bot123456:AbCdEf-your-token/sendPhoto"

# 2) send a file Pico already has (a file_id from an update or an earlier message)
curl "https://picogram.ir/bot123456:AbCdEf-your-token/sendDocument" -d chat_id=42 -d document=<FILE_ID>

# 3) let Pico download a public https link for you
curl "https://picogram.ir/bot123456:AbCdEf-your-token/sendVideo" -d chat_id=42 --data-urlencode "video=https://example.com/clip.mp4"

# receive: getFile gives a path, then download it
curl "https://picogram.ir/bot123456:AbCdEf-your-token/getFile?file_id=<FILE_ID>"
curl -O "https://picogram.ir/file/bot123456:AbCdEf-your-token/files/<FILE_ID>"

• 📤 آپلود با multipart/form-data (در هر درخواست یک فایل).
• 🆔 یک file_id که پیکو به شما داده، برای فرستادن دوباره‌ی همان فایل بدون آپلود.
• 🔗 یک لینک https عمومی: پیکو خودش آن را دانلود می‌کند (تا ۵۰ مگابایت، فقط آدرس‌های عمومی).

دریافت فایل

وقتی کسی عکس، ویدئو، پیام صوتی یا فایلی برای ربات شما می‌فرستد، به‌روزرسانی فیلد متناظر (photo، video، voice، document)، یک file_id و caption را دارد.

{
  "update_id": 120,
  "message": {
    "message_id": 940,
    "from": { "id": 7, "is_bot": false, "first_name": "Sara" },
    "chat": { "id": 42, "type": "private" },
    "caption": "my cat",
    "photo": [ { "file_id": "k2s9…", "width": 1280, "height": 960, "file_size": 183412 } ]
  }
}

getFile را صدا بزنید تا یک file_path بگیرید، بعد https://picogram.ir/file/bot<TOKEN>/<file_path> را دانلود کنید. بزرگ‌ترین فایل ۱۰۰ مگابایت است (۵۰ مگابایت برای آپلود و لینک از سمت ربات).

فوروارد، کپی و ویرایش

forwardMessage و copyMessage (‏chat_id، from_chat_id، message_id)، editMessageCaption، editMessageReplyMarkup، pinChatMessage و unpinChatMessage.

👮گروه، کانال و متدهای مدیریتی

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

دسترسی‌های ادمین

مالک و ادمین‌ها دقیقاً همان دسترسی‌هایی را که لازم است به افراد (و ربات‌ها) می‌دهند: تغییر اطلاعات، ارسال پیام (کانال)، ویرایش و حذف پیام، مسدودکردن افراد، دعوت افراد، سنجاق‌کردن پیام و افزودن ادمین جدید. مالک همچنین می‌تواند گفتگو را به شخص دیگری واگذار کند و تعیین کند اعضای عادی یک گروه چه کارهایی بتوانند بکنند (ارسال پیام، ارسال رسانه، افزودن افراد، سنجاق و تغییر اطلاعات).

نمایه‌ی ربات شما

setMyName، getMyName، setMyDescription، getMyDescription. تصویر ربات را در @botfather عوض کنید: /mybots ← ربات شما ← 📷 ویرایش تصویر.

پاسخ به دکمه‌ها

answerCallbackQuery با text یک پیام کوتاه به کسی که روی دکمه زده نشان می‌دهد.

📥به‌روزرسانی‌ها: ربات چه دریافت می‌کند

هر مورد از getUpdates (یا هر فراخوانی وب‌هوک) یک update_id دارد و یکی از دو چیز را:

💬 یک پیام

{
  "update_id": 118,
  "message": {
    "message_id": 931,
    "from": { "id": 7, "is_bot": false, "first_name": "Sara", "username": "sara" },
    "date": 1767225600,
    "text": "hello",
    "chat": { "id": 42, "type": "private" }
  }
}

text متن ساده است. اگر کاربر قالب‌بندی کرده باشد، formatted_text هم متن اصلی را همراه نمادهای قالب‌بندی پیکو دارد.

👆 ضربه روی دکمه

{
  "update_id": 119,
  "callback_query": {
    "id": "931.1767225700000",
    "from": { "id": 7, "is_bot": false, "first_name": "Sara", "username": "sara" },
    "data": "yes",
    "message": { "message_id": 931, "chat": { "id": 42, "type": "private" }, "text": "Pick one" }
  }
}

در گروه‌ها و کانال‌ها ربات فقط دستورها (/start)، پیام‌هایی که به آن اشاره دارند (@yourbot) و پاسخ به پیام‌های خودش را می‌بیند.

🎨قالب‌بندی متن

به sendMessage و editMessageText پارامتر parse_mode بدهید: HTML، MarkdownV2 یا Markdown، دقیقاً مثل تلگرام. بدون آن متن همان‌طور که نوشته‌اید فرستاده می‌شود.

HTML

<b>bold</b> <i>italic</i> <u>underline</u> <s>strike</s> <tg-spoiler>spoiler</tg-spoiler>
<a href="https://picogram.ir">link</a> <code>inline code</code>
<pre><code class="language-python">print("hi")</code></pre>
<blockquote>quote</blockquote>

MarkdownV2

*bold* _italic_ __underline__ ~strike~ ||spoiler||
[link](https://picogram.ir) `inline code`
```python
print("hi")
```
>quote  (escape these with a backslash: _ * [ ] ( ) ~ ` > # + - = | { } . !)

پیکو پررنگ، کج، زیرخط، خط‌خورده، اسپویلر، کد درون‌خطی، بلوک کد با نام زبان، پیوند و نقل‌قول (حتی جمع‌شونده با <blockquote expandable>) را پشتیبانی می‌کند. اشاره (@name)، هشتگ، پیوند، ایمیل و /دستورها خودکار شناخته می‌شوند. اگر قالب‌بندی خراب باشد 400 can't parse entities می‌گیرید.

⌨️دکمه‌ها (کیبورد درون‌خطی)

به پیام reply_markup بدهید تا زیر آن دکمه نمایش داده شود. هر دکمه یا callback_data دارد (با ضربه روی آن، ربات یک callback_query می‌گیرد) یا url (یک پیوند را باز می‌کند).

{
  "chat_id": 42,
  "text": "Pick one 👇",
  "reply_markup": {
    "inline_keyboard": [
      [ { "text": "✅ Yes", "callback_data": "yes" }, { "text": "❌ No", "callback_data": "no" } ],
      [ { "text": "🌐 Website", "url": "https://example.com" } ]
    ]
  }
}

وقتی کسی روی دکمه می‌زند، answerCallbackQuery را صدا بزنید و بعد با editMessageText پیام را به‌روز کنید یا پیام تازه بفرستید.

🪝وب‌هوک

به‌جای polling، پیکو می‌تواند هر وقت اتفاقی افتاد سرور شما را صدا بزند.

curl "https://picogram.ir/bot123456:AbCdEf-your-token/setWebhook" \
  --data-urlencode "url=https://bot.example.com/pico-hook" \
  --data-urlencode "secret_token=my_secret_123"

• 🔒 آدرس باید https روی پورت ۴۴۳ یا ۸۴۴۳ باشد و به یک آدرس عمومی برسد.
• 🔑 اگر secret_token بگذارید، هر فراخوانی هدر X-Pico-Bot-Api-Secret-Token را دارد. آن را بررسی کنید.
• 📮 پیکو به‌روزرسانی را به‌صورت JSON در یک POST می‌فرستد. ظرف ۱۰ ثانیه با 2xx جواب بدهید.
• 🔁 ارسال ناموفق ۳ بار تلاش می‌شود (همین حالا، بعد از ۱٫۵ ثانیه، بعد از ۸ ثانیه). getWebhookInfo آخرین خطا را نشان می‌دهد.
• ⚠️ تا وقتی وب‌هوک تنظیم است، getUpdates خطای 409 Conflict می‌دهد. برای برگشت به polling، deleteWebhook را صدا بزنید.

📏قوانین و محدودیت‌ها

🚧 هنوز موجود نیست

حالت inline (‏answerInlineQuery)، پرداخت، بازی، نظرسنجی، استیکر، sendVideoNote، دستورها به تفکیک زبان یا حوزه، و مینی‌اپ. نیازتان را از طریق @support در پیکو بگویید. 💙

🩺خطاها