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

معرفی

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

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

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

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

$ composer require GapAfzar/gap-sdp-api

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

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

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

تنظیم توکن

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

$gap = new Api($token);

chat_id

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

ارسال پیام متنی

....
$message_id = $gap->sendText($chat_id ,$message ,$reply_keyboard ,$inline_keyboard ,$form);

ارسال تصویر

....
$message_id = $gap->sendImage($chat_id, $image, $caption, $reply_keyboard, $inline_keyboard, $form);

ارسال ویدئو

....
$message_id = $gap->sendVideo($chat_id, $video, $caption, $reply_keyboard, $inline_keyboard, $form);

ارسال فایل صوتی

....
$message_id = $gap->sendAudio($chat_id, $audio, $caption, $reply_keyboard, $inline_keyboard, $form);

ارسال فایل

....
$message_id = $gap->sendFile($chat_id, $file, $caption, $reply_keyboard, $inline_keyboard, $form);

ارسال صدا

....
$message_id = $gap->sendVoice($chat_id, $voice, $caption, $reply_keyboard, $inline_keyboard, $form);

ارسال شماره تلفن

....
$message_id = $gap->sendContact($chat_id, $name, $phone, $reply_keyboard, $inline_keyboard, $form);

ارسال موقعیت جغرافیایی

....
$message_id = $gap->sendLocation($chat_id, $lat, $long, $caption, $reply_keyboard, $inline_keyboard, $form);

ارسال Action

....
$gap->sendAction($chat_id ,$action);

ویرایش پیام ارسال شده

....
$gap->editMessage($chat_id, $message_id, $data, $inline_keyboard);

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

حذف پیام ارسال شده

....
$gap->deleteMessage($chat_id, $message_id);

ارسال صورتحساب

....
$invoice_id = $gap->sendInvoice($chat_id, $amount, $description, $currency);

ارسال صورتحساب قبض

....
$invoice_id = $gap->sendBillInvoice($chat_id, $amount, $bill_id, $pay_id);

تایید صورتحساب

....
$invoice_verify = $gap->invoiceVerify($chat_id, $ref_id);

استعلام صورتحساب

....
$invoice = $gap->invoiceInquiry($chat_id, $ref_id);

پرداخت درون برنامه‌ای

....
$inline_keyboard = [
			[
				[
					'text' => 'دونیت',
					'amount' => 2000,
					'currency' => 'IRR',
					'ref_id' => 'XXXXXXX',
					'desc' => 'توضیحات مربوط به پرداخت برای نمایش در لیست تراکنش ها'
				],
			]
		];
$message_id = $gap->sendText($chat_id ,$message ,null ,$inline_keyboard);

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

تایید پرداخت درون برنامه‌ای

....
$pay_verify = $gap->payVerify($chat_id, $ref_id);

استعلام پرداخت درون برنامه‌ای

....
$payment = $gap->payInquiry($chat_id, $ref_id);

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 ارایه شده ذخیره و یا بازیابی کنید. همچنین با استفاده از اطلاعاتی که ارسال کرده اید، جدول بازی‌ را در بازه های زمانی مختلف دریافت و به کاربران نمایش دهید.

ارسال اطلاعات بازیکن

....
$save = $gap->setGameData($chat_id, $type, $data);

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

....
$game_data = $gap->getGameData($chat_id, $type, $data);

دریافت جدول بازی

....
$leaderBoard = $gap->leaderBoard($chat_id, $type);

دریافت اطلاعات مربوط به پیکربندی بازی

....
$game_configs = $gap->getGameConfig($chat_id, $key);

ثبت رخدادهای بازی

....
$gap->gameEvent($chat_id, $event, $value);