کتابخانه PHP کار با Bot Platform API

مقدمه

معرفی

در صورتی که می خواهید از زبان php برای برنامه خود و ارتباط با api گپ استفاده کنید می‌توانید از کتابخانه‌ای که برای برنامه نویسان این زبان آماده شده است استفاده کنید که شامل مثال‌هایی برای توسعه دهندگان نیز می‌باشد.

دریافت کتابخانه

این کتابخانه و نمونه کدهای آن را می‌توانید از مخزن github در آدرس https://github.com/GapAfzar/Gap-SDP-API دریافت کنید.

همچنین برای شروع کار می‌توانید با استفاده از composer و دستور زیر، کلاس کمکی و نمونه کدهای لازم را به پروژه خود اضافه کنید.

$ composer require GapAfzar/gap-sdp-api

کار با API

فراخوانی کلاس

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

require dirname(__FILE__) . '/../vendor/autoload.php';
use Gap\SDP\Api;

تنظیم توکن

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

$gap = new Api($token);
نام پارامتر Type الزامی Description
token string Yes توکنی که پس از ساخت ربات دریافت کرده‌اید.

chat_id

نکته مهم: برای ارسال پیام به کاربران با توجه به نوع ربات مقدار chat_id تغییر میکند. که در جدول زیر می‌توانید انواع این مقادیر را مشاهده کنید:

مقدار chat_id در انواع ربات‌ها:
نام پارامتر نوع پارامتر Type Methods of sending content Description
chat_id integer collaborative - شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
string شماره موبایل کاربر عضو شده در ربات با فرمت +989123456789
integer Notification individual شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
string شماره موبایل کاربر عضو شده در ربات با فرمت +989123456789
string group شناسه ربات به همراه @ بطور مثال: @service

ارسال پیام متنی
....
$message_id = $gap->sendText($chat_id ,$message ,$reply_keyboard ,$inline_keyboard ,$form);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
message string Yes متن و یا محتوای ارسالی شما
reply_keyboard string No افزودن کیبورد از نوع reply keyboard به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard string No افزودن کیبورد از نوع inline به پیام. (توضیحات مربوط به inline_keyboard)
form string No افزودن فرم به پیام. (توضیحات مربوط به form)
در صورتی که پیام با موفقیت ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
message_id integer message_id پیام ارسال شده برای کاربر می‌باشد.

ارسال تصویر
....
$message_id = $gap->sendImage($chat_id, $image, $caption, $reply_keyboard, $inline_keyboard, $form);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
image string Yes مسیر فایل تصویر مورد نظر، بطور مثال: images/test.jpg
caption string No توضیحات مربوط به تصویر
reply_keyboard string No افزودن کیبورد از نوع reply keyboard به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard string No افزودن کیبورد از نوع inline به پیام. (توضیحات مربوط به inline_keyboard)
form string No افزودن فرم به پیام. (توضیحات مربوط به form)
در صورتی که پیام با موفقیت ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
message_id integer message_id پیام ارسال شده برای کاربر می‌باشد.

ارسال ویدئو
....
$message_id = $gap->sendVideo($chat_id, $video, $caption, $reply_keyboard, $inline_keyboard, $form);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
video string Yes مسیر ویدئو مورد نظر، بطور مثال: video/test.mp4
caption string No توضیحات مربوط به ویدئو
reply_keyboard string No افزودن کیبورد از نوع reply keyboard به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard string No افزودن کیبورد از نوع inline به پیام. (توضیحات مربوط به inline_keyboard)
form string No افزودن فرم به پیام. (توضیحات مربوط به form)
در صورتی که پیام با موفقیت ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
message_id integer message_id پیام ارسال شده برای کاربر می‌باشد.

ارسال فایل صوتی
....
$message_id = $gap->sendAudio($chat_id, $audio, $caption, $reply_keyboard, $inline_keyboard, $form);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
audio string Yes مسیر فایل صوتی مورد نظر، بطور مثال: audio/test.mp3
caption string No توضیحات مربوط به فایل صوتی
reply_keyboard string No افزودن کیبورد از نوع reply keyboard به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard string No افزودن کیبورد از نوع inline به پیام. (توضیحات مربوط به inline_keyboard)
form string No افزودن فرم به پیام. (توضیحات مربوط به form)
در صورتی که پیام با موفقیت ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
message_id integer message_id پیام ارسال شده برای کاربر می‌باشد.

ارسال فایل
....
$message_id = $gap->sendFile($chat_id, $file, $caption, $reply_keyboard, $inline_keyboard, $form);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
file string Yes مسیر فایل مورد نظر، بطور مثال: files/file.zip
caption string No توضیحات مربوط به فایل
reply_keyboard string No افزودن کیبورد از نوع reply keyboard به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard string No افزودن کیبورد از نوع inline به پیام. (توضیحات مربوط به inline_keyboard)
form string No افزودن فرم به پیام. (توضیحات مربوط به form)
در صورتی که پیام با موفقیت ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
message_id integer message_id پیام ارسال شده برای کاربر می‌باشد.

ارسال صدا
....
$message_id = $gap->sendVoice($chat_id, $voice, $caption, $reply_keyboard, $inline_keyboard, $form);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
voice string Yes مسیر فایل صدای مورد نظر، بطور مثال: voice/voice.ogg
caption string No توضیحات مربوط به فایل صدا
reply_keyboard string No افزودن کیبورد از نوع reply keyboard به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard string No افزودن کیبورد از نوع inline به پیام. (توضیحات مربوط به inline_keyboard)
form string No افزودن فرم به پیام. (توضیحات مربوط به form)
در صورتی که پیام با موفقیت ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
message_id integer message_id پیام ارسال شده برای کاربر می‌باشد.

ارسال شماره تلفن
....
$message_id = $gap->sendContact($chat_id, $name, $phone, $reply_keyboard, $inline_keyboard, $form);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
name string Yes نام
phone string Yes شماره تلفن
reply_keyboard string No افزودن کیبورد از نوع reply keyboard به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard string No افزودن کیبورد از نوع inline به پیام. (توضیحات مربوط به inline_keyboard)
form string No افزودن فرم به پیام. (توضیحات مربوط به form)
در صورتی که پیام با موفقیت ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
message_id integer message_id پیام ارسال شده برای کاربر می‌باشد.

ارسال موقعیت جغرافیایی
....
$message_id = $gap->sendLocation($chat_id, $lat, $long, $caption, $reply_keyboard, $inline_keyboard, $form);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
lat string Yes عرض جغرافیایی
long string Yes طول جغرافیایی
caption string No توضیحات
reply_keyboard string No افزودن کیبورد از نوع reply keyboard به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard string No افزودن کیبورد از نوع inline به پیام. (توضیحات مربوط به inline_keyboard)
form string No افزودن فرم به پیام. (توضیحات مربوط به form)
در صورتی که پیام با موفقیت ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
message_id integer message_id پیام ارسال شده برای کاربر می‌باشد.

ارسال Action
....
$gap->sendAction($chat_id ,$action);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
action string Yes نوع Action ارسالی
انواع Action های قابل استفاده:
مقدار Description
typing نمایش پیام 'در حال نوشتن پیام ...' به کاربر در پیام رسان

ویرایش پیام ارسال شده
....
$gap->editMessage($chat_id, $message_id, $data, $inline_keyboard);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
message_id integer Yes message_id پیامی که قصد ویرایش آن را دارید.
data string Yes محتوای جدید پیام
inline_keyboard array Yes کیبورد از نوع inline. (توضیحات مربوط به inline_keyboard)

نکته: در حال حاضر فقط ویرایش پیام‌های متنی امکانپذیر است.


حذف پیام ارسال شده
....
$gap->deleteMessage($chat_id, $message_id);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
message_id integer Yes message_id پیامی که قصد حذف آن را دارید.

ارسال صورتحساب
....
$invoice_id = $gap->sendInvoice($chat_id, $amount, $description, $currency);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
amount integer Yes مبلغ صورتحساب که کاربر باید پرداخت کند.
currency string No این مقدار مشخص کننده واحد پولی صورتحساب است که می‌توانید یکی از مقادیر IRR (ریال) و یا USD (دلار) را وارد کنید. اگر این مقدار وارد نشود بطور پیشفرض صورتحساب ریالی صادر خواهد شد.
description string Yes توضیحات مربوط به صورتحساب پرداختی که به کاربر نمایش داده می‌شود.
در صورتی که صورتحساب با موفقیت ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
invoice_id string شناسه صورتحساب ارسالی شما که در واقع همان ref_id می‌باشد، که باید آن را جهت پیگیری‌های بعدی ذخیره کنید.


تایید صورتحساب
....
$invoice_verify = $gap->invoiceVerify($chat_id, $ref_id);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
ref_id string Yes invoice_id که در هنگام ارسال صورتحساب دریافت کرده‌اید.
در صورتی استفاده از این متود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
invoice_verify boolean مشخص کننده تایید یا عدم تایید صورتحساب ارسالی است.

استعلام صورتحساب
....
$invoice = $gap->invoiceInquiry($chat_id, $ref_id);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
ref_id string Yes invoice_id که در هنگام ارسال صورتحساب دریافت کرده‌اید.
در صورتی استفاده از این متود، پارامترهای ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
invoice array شامل مقادیر status و amount صورتحساب است.

پرداخت درون برنامه‌ای
....
$inline_keyboard = [
			[
				[
					'text' => 'دونیت',
					'amount' => 2000,
					'currency' => 'IRR',
					'ref_id' => 'XXXXXXX',
					'desc' => 'توضیحات مربوط به پرداخت برای نمایش در لیست تراکنش ها'
				],
			]
		];
$message_id = $gap->sendText($chat_id ,$message ,null ,$inline_keyboard);
key های قابل استفاده در inline keyboard هنگام ایجاد دکمه پرداخت درون برنامه‌ای
Key Type الزامی Description
text string Yes این مقدار در حقیقت برچسب دکمه پرداخت دورن برنامه‌ای است.
amount integer Yes این مقدار به منظور گرفتن وجه از کاربر به شکل پرداخت درون برنامه‌ای می‌باشد.
currency string Yes این مقدار مشخص کننده واحد پول است. که در حال حاضر می‌تواند برای پرداخت‌های ریالی مقدار IRR و پرداخت گپسی مقدار coin را دریافت کند.
ref_id string Yes یک رشته Base64 شامل حروف و ارقام می‌باشد که در واقع یک کد منحصر بفرد است که توسط توسعه دهنده ایجاد شده و برای شناسایی کاربر پس از انجام روال پرداخت استفاده می‌شود.
desc string Yes توضیحات مربوط به پرداخت که برای نمایش در لیست تراکنش‌ها استفاده می‌شود.

پارامترهای ارسالی:

نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
message string Yes متن و یا محتوای ارسالی شما
inline_keyboard string No افزودن کیبورد از نوع inline به پیام. (توضیحات مربوط به inline_keyboard)
در صورتی استفاده از این متود، پارامترهای ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
message_id integer message_id پیام ارسال شده برای کاربر می‌باشد.

تایید پرداخت درون برنامه‌ای
....
$pay_verify = $gap->payVerify($chat_id, $ref_id);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
ref_id string Yes ref_id که در هنگام ایجاد دکمه پرداخت درون برنامه‌ای مشخص کرده‌اید.
در صورتی استفاده از این متود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
pay_verify boolean مشخص کننده تایید یا عدم تایید پرداخت درون برنامه‌ای است.

استعلام پرداخت درون برنامه‌ای
....
$payment = $gap->payInquiry($chat_id, $ref_id);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
ref_id string Yes ref_id که در هنگام ایجاد دکمه پرداخت درون برنامه‌ای مشخص کرده‌اید.
در صورتی استفاده از این متود، پارامترهای ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
payment array شامل مقادیر status و amount پرداخت درون برنامه‌ای است.

Reply Keyboard

با استفاده از قابلیت Reply Keyboard می‌توانید پس از ارسال پیام به کاربر، امکان انتخاب چند گزینه از بین گزینه‌های موجود را برای وی فراهم کنید، یعنی در واقع با استفاده از این قابلیت در قسمت ورود متن به کاربر، چند دکمه که شما از قبل تعیین کرده‌اید نمایش داده خواهد شد که با کلیک کاربر بروی هر یک، دستوری که شما برای آن در نظر گرفته‌اید ارسال خواهد شد.

در مثال زیر سوالی از کاربر پرسیده خواهد شد که دو دکمه بلی و خیر به کاربر نشان داده خواهد شد که در صورت کلیک کاربر بروی بلی، دستور yes برای شما ارسال خواهد شد و در صورت کلیک بروی خیر دستور no طبق روال دریافت پیام برای شما ارسال خواهد شد.

....
$keyboard = [
	[
		['yes' => 'بلی'],
		['no' => 'خیر']
	]
];
$replyKeyboard = $gap->replyKeyboard($keyboard);
$gap->sendText($chat_id, 'آیا از محتوای ربات رضایت دارید ؟', $replyKeyboard);

دریافت شماره تلفن و موقعیت جغرافیایی از طریق کیبورد

برای دریافت شماره تلفن و یا موقعیت جغرافیایی کاربر می‌توانید مطابق مثال ذیل عمل نمایید. دقت داشته باشید که کاربر پس از کلیک بر روی دکمه موردنظر ابتدا یک پیغام مبنی بر اجازه دسترسی را مشاهده می‌کند که باید آن را تایید کند تا اطلاعات موردنظر برای شما ارسال شود.

....
$keyboard = [
	[
		['$contact' => 'تلفن'],
		['$location'  => 'موقعیت جغرافیایی']
	]
];
$replyKeyboard = $gap->replyKeyboard($keyboard);
$gap->sendText($chat_id, 'لطفا روی یکی از دکمه‌های ذیل کلیک کنید.', $replyKeyboard);

Inline Keyboard

inline keyboard یا دکمه شیشه‌ای نوع دیگری از دکمه‌ها هستند که در پیام رسان گپ قابل استفاده هستند، از این دکمه‌ها می‌توان برای ارسال مقادیر مختلف، ارسال لینک و یاپرداخت درون برنامه‌ای استفاده کرد.

....
$inline_keyboard = [
	[
		['text' => 'Yes', 'cb_data' => 'yes'],
		['text' => 'No', 'cb_data' => 'no'],
	],
	[
		['text' => 'help', 'url' => 'http://google.com'],
	]
];
$gap->sendText($chat_id, 'آیا از محتوای ربات رضایت دارید ؟', null, $inline_keyboard);

ارسال فرم

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

....
$form =	[
	[
		"name" => "name",
		"type" => "text",
		"label" => "نام"
	],
	[
		"name" => "married",
		"type" => "radio",
		"label" => "وضعیت تاهل",
		"options" => [
			["single" => "مجرد"],
			["married" => "متاهل"]
		]
	],
	[
		"name" => "city",
		"type" => "select",
		"label" => "شهر",
		"options" => [
			["msh" => "مشهد"],
			["thr" => "تهران"]
		]
	],
	[
		"name" => "address",
		"type" => "textarea",
		"label" => "نشانی"
	],
	[
		"name" => "agree",
		"type" => "checkbox",
		"label" => "شرایط را می‌پذیرم"
	],
	[
		"type" => "submit",
		"label" => "ارسال فرم"
	]
]
$gm->sendText($chat_id, 'لطفا فرم ذیل را تکمیل نمایید.', null, null, $form);

دریافت اطلاعات در فرم از طریق بارکد

دریافت اطلاعات فرم از طریق بارکدخوا‌‌ن گوشی موبایل هنگام ایجاد فرم.

....
$form = [
	[
		"name" => "name",
		"type" => "text",
		"label" => "نام"
	],
	[
		"name" => "test_bc",
		"type" => "inbuilt",
		"value" => "barcode",
		"label" => "بارکد"
	],
	[
		"name" => "test_qr",
		"type" => "inbuilt",
		"value" => "qrcode",
		"label" => "کیوآرکد"
	],
	[
		"type" => "submit",
		"label" => "ارسال"
	]
];
$gap->sendText($chat_id, 'لطفا فرم ذیل را تکمیل کنید', null, null, $form);

API گیم سنتر

معرفی

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


ارسال اطلاعات بازیکن
....
$save = $gap->setGameData($chat_id, $type, $data);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
type string Yes نوع data ارسالی را مشخص می‌کند که می‌تواند یکی از مقادیر: setting, meta, custom, high_score باشد.
data string Yes مقداری که قصد ذخیره کردن آن را دارید در این قسمت قرار می‌گیرد.
در صورتی که مقدار ارسالی با موفقیت ذخیره شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
save boolean این مقدار در صورت ذخیره موفق مقادیر true و در صورت عدم ذخیره false خواهد بود.

دریافت اطلاعات بازیکن
....
$game_data = $gap->getGameData($chat_id, $type, $data);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
type string Yes نوع data درخواستی را مشخص می‌کند که می‌تواند یکی از مقادیر: setting, meta, custom, high_score باشد.
در صورتی که درخواست بدرستی ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
game_data string مقادیری که قبلا با استفاده از gameData ارسال کرده‌اید را دریافت خواهید کرد.

دریافت جدول بازی
....
$leaderBoard = $gap->leaderBoard($chat_id, $type);
نام پارامتر Type الزامی Description
chat_id integer / string Yes توضیحات مربوط به chat_id
type string Yes نوع گزارشی که قصد دریافت آن را دارید مشخص می‌کند که می‌تواند یکی از مقادیر: all, month, week, day باشد.
در صورتی که درخواست بدرستی ارسال شود، پارامتر ذیل بعنوان خروجی دریافت می‌شود.
پارامتر Type Description
leaderBoard json یک آرایه json شامل جزییات مربوط به جدول قهرمانان، از جمله نام، نام کاربری، امتیاز و آواتار بازیکنان.