کتابخانه PHP کار با 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;

تنظیم توکن

$gm = new Api($token);

پارامتر ورودی	نوع	الزامی	توضیحات
token	string	بلی	توکنی که پس از ساخت سرویس دریافت کرده‌اید. (دریافت توکن)

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

....

$gm->sendText($chat_id ,$message ,$reply_keyboard ,$inline_keyboard ,$form);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
message	string	بلی	متن پیام مورد نظر که قصد ارسال آن را دارید.
reply_keyboard	string	خیر	افزودن کیبورد از نوع reply به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard	array	خیر	افزودن کیبورد از نوع inline به پیام.
form	array	خیر	افزودن فرم به پیام.

200 Success Request

پارامتر	توضیحات
id	شناسه پیام ارسالی شما. در واقع همان message_id می‌باشد.

ارسال Action

....

$gm->sendAction($chat_id ,$action);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
action	string	بلی	نوع Action

انواع Action های قابل استفاده در گپ:

نام	توضیحات
typing	نمایش پیام 'در حال نوشتن پیام ...' به کاربر در پیام رسان

ارسال تصویر

....

$gm->sendImage($chat_id, $image, $caption, $reply_keyboard, $inline_keyboard, $form);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
image	string	بلی	مسیر فایل تصویر مورد نظر، بطور مثال: `images/test.jpg`
caption	string	خیر	توضیحات تصویر
reply_keyboard	string	خیر	افزودن کیبورد از نوع reply به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard	array	خیر	افزودن کیبورد از نوع inline به پیام.
form	array	خیر	افزودن فرم به پیام.

200 Success Request

پارامتر	توضیحات
id	شناسه پیام ارسالی شما. در واقع همان message_id می‌باشد.

ارسال ویدئو

....

$gm->sendVideo($chat_id, $video, $caption, $reply_keyboard, $inline_keyboard, $form);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
video	string	بلی	مسیر ویدئو مورد نظر، بطور مثال: `videos/test.mp4`
caption	string	خیر	توضیحات ویدئو
reply_keyboard	string	خیر	افزودن کیبورد از نوع reply به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard	array	خیر	افزودن کیبورد از نوع inline به پیام.
form	array	خیر	افزودن فرم به پیام.

200 Success Request

پارامتر	توضیحات
id	شناسه پیام ارسالی شما. در واقع همان message_id می‌باشد.

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

....

$gm->sendAudio($chat_id, $audio, $caption, $reply_keyboard, $inline_keyboard, $form);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
video	string	بلی	مسیر فایل صوتی مورد نظر، بطور مثال: `audio/test.mp4`
caption	string	خیر	توضیحات فایل صوتی
reply_keyboard	string	خیر	افزودن کیبورد از نوع reply به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard	array	خیر	افزودن کیبورد از نوع inline به پیام.
form	array	خیر	افزودن فرم به پیام.

200 Success Request

پارامتر	توضیحات
id	شناسه پیام ارسالی شما. در واقع همان message_id می‌باشد.

ارسال فایل

....

$gm->sendFile($chat_id, $file, $caption, $reply_keyboard, $inline_keyboard, $form);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
video	string	بلی	مسیر فایل مورد نظر، بطور مثال: `file.zip`
caption	string	خیر	توضیحات فایل صوتی
reply_keyboard	string	خیر	افزودن کیبورد از نوع reply به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard	array	خیر	افزودن کیبورد از نوع inline به پیام.
form	array	خیر	افزودن فرم به پیام.

200 Success Request

پارامتر	توضیحات
id	شناسه پیام ارسالی شما. در واقع همان message_id می‌باشد.

ارسال صدا (Voice)

....

$gm->sendVoice($chat_id, $voice, $caption, $reply_keyboard, $inline_keyboard, $form);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
voice	string	بلی	مسیر voice مورد نظر، بطور مثال: `test.ogg`
caption	string	خیر	توضیحات
reply_keyboard	string	خیر	افزودن کیبورد از نوع reply به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard	array	خیر	افزودن کیبورد از نوع inline به پیام.
form	array	خیر	افزودن فرم به پیام.

200 Success Request

پارامتر	توضیحات
id	شناسه پیام ارسالی شما. در واقع همان message_id می‌باشد.

ارسال Location

....

$gm->sendLocation($chat_id, $lat, $long, $caption, $reply_keyboard, $inline_keyboard, $form);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
lat	float	بلی	عرض جغرافیایی
long	float	بلی	طول جغرافیایی
caption	string	خیر	توضیحات
reply_keyboard	string	خیر	افزودن کیبورد از نوع reply به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard	array	خیر	افزودن کیبورد از نوع inline به پیام.
form	array	خیر	افزودن فرم به پیام.

200 Success Request

پارامتر	توضیحات
id	شناسه پیام ارسالی شما. در واقع همان message_id می‌باشد.

ارسال Contact

....

$gm->sendContact($chat_id, $name, $phone, $reply_keyboard, $inline_keyboard, $form);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
name	string	بلی	نام
phone	string	بلی	شماره تلفن
reply_keyboard	string	خیر	افزودن کیبورد از نوع reply به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard	array	خیر	افزودن کیبورد از نوع inline به پیام.
form	array	خیر	افزودن فرم به پیام.

200 Success Request

پارامتر	توضیحات
id	شناسه پیام ارسالی شما. در واقع همان message_id می‌باشد.

ویرایش پیام

....

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

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
message_id ‍	integer	بلی	شناسه پیامی که قصد ویرایش آن را دارید.
data	string	خیر	محتوای جدید پیام
inline_keyboard	array	خیر	کیبورد از نوع inline

حذف پیام

....

$gm->deleteMessage($chat_id, $message_id);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
message_id ‍	integer	بلی	شناسه پیامی که قصد حذف آن را دارید.

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

....

$invoiceId = $gm->sendInvoice($chat_id, $amount, $description);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
amount ‍	integer	بلی	مقدار هزینه صورتحساب منتشر شده شما که کاربر باید پرداخت کند به ریال.
description	string	بلی	توضیحات صورت حساب.

200 Success Request

پارامتر	توضیحات
id	شناسه صورتحساب ارسالی شما که در واقع همان ref_id می‌باشد، که باید آن را جهت پیگیری‌های بعدی ذخیره کنید.

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

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

....

$gm->invoiceVerify($chat_id, $ref_id);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
ref_id ‍	integer	بلی	invoice_id که در هنگام ارسال صورتحساب برای توسعه دهنده ارسال شده است.

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

....

$gm->invoiceInquiry($chat_id, $ref_id);

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
ref_id ‍	integer	بلی	invoice_id که در هنگام ارسال صورتحساب برای توسعه دهنده ارسال شده است.

200 Success Request

پارامتر	توضیحات
amount	این مقدار مشخص کننده مبلغ صورتحساب است.
status	مشخص کننده وضعیت صورتحساب است. که یکی از حالت‌های [error, verified]

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

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

یک مثال از ایجاد پرداخت درون برنامه‌ای:

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

پارامتر ورودی	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت `989123456789+` وارد کنید.
message	string	بلی	متن پیام مورد نظر که قصد ارسال آن را دارید.
reply_keyboard	string	خیر	افزودن کیبورد از نوع reply به پیام. برای ساخت کیبورد ابتدا باید از متود replyKeyboard استفاده کنید، سپس مقدار دریافتی از این متود را به عنوان مقدار reply_keyboard ارسال نمایید.
inline_keyboard	array	خیر	افزودن کیبورد از نوع inline به پیام.

200 Success Request

پارامتر	توضیحات
id	شناسه پیام ارسالی شما. در واقع همان message_id می‌باشد.

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

همه پرداخت‌‌هایی که بصورت درون برنامه‌ای انجام می‌شود، پس از پرداخت توسط کاربر باید توسط توسعه دهنده تایید شوند.

....

$gm->payVerify($chat_id, $ref_id);

نام داده	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
ref_id ‍	integer	بلی	ref_id که در هنگام ایجاد دکمه پرداخت توسط توسعه دهنده تولید شده است.

200 Success Request

پارامتر	توضیحات
amount	این مقدار مشخص کننده مبلغ پرداخت است.
status	مشخص کننده وضعیت پرداخت است. که مقدار آن برابر است با یکی از مقادیر [error, verified]

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

....

$gm->payInquiry($chat_id, $ref_id);

نام داده	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
ref_id ‍	integer	بلی	ref_id که در هنگام ایجاد دکمه پرداخت توسط توسعه دهنده تولید شده است.

200 Success Request

پارامتر	توضیحات
amount	این مقدار مشخص کننده مبلغ است.
status	مشخص کننده وضعیت پرداخت است. که مقدار آن برابر است با یکی از مقادیر [error, verified]

answerCallback

....

$gm->answerCallback($chat_id, $callback_id, $text, $show_alert);

نام داده	نوع	الزامی	توضیحات
chat_id	integer	بلی	شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
callback_id ‍	integer	بلی	این مقدار هنگام کلیک بر روی دکمه توسط گپ برای توسعه دهنده ارسال می‌شود.
text	string	بلی	متن پیغام
show_alert	boolean	خیر	نمایش پیام بصورت دیالوگ

ارسال به همراه Reply Keyboard

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

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

....

$keyboard = [
    [['yes' => 'بلی'], ['no' => 'خیر']]
];

$replyKeyboard = $gm->replyKeyboard($keyboard);

$gm->sendText($chat_id, 'آیا از محتوای سرویس رضایت دارید ؟', $replyKeyboard);

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

برای دریافت شماره تلفن و یا لوکیشن کاربر می‌توانید مطابق مثال ذیل عمل نمایید.

$keyboard = [
        [
            ['$contact' => 'تلفن'],
            ['$location' => 'لوکیشن']
        ],
    ];

$replyKeyboard = $gm->replyKeyboard($keyboard);

$gm->sendText($chat_id, 'لطفا روی یکی از دکمه‌های ذیل کلیک کنید.', $replyKeyboard);

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

ارسال به همراه Inline Button

Inline Button هم دارای قابلیت‌هایی مشابه Reply Keyboard می‌باشد. برای اطلاعات بیشتر مستندات Inline Button مشاهده کنید.

....

$inline_keyboard = [
    [
        ['text' => 'Yes', 'cb_data' => 'yes'],
        ['text' => 'No', 'cb_data' => 'no'],
    ],
    [
        ['text' => 'help', 'url' => 'http://google.com'],
    ]
];

$gm->sendText($chat_id, 'آیا از محتوای سرویس رضایت دارید ؟', null, $inline_keyboard);

ارسال به همراه Form

برای اطلاعات بیشتر این بخش Form را مشاهده کنید.

....

$form = [
    ["name" => "name", "type" => "text", "label" => "Name"],
    ["name" => "married", "type" => "radio", "options" => [["y" => "Yes"], ["n" => "No"]], "label" => "Married"],
    ["name" => "city", "type" => "select", "options" => [["mah" => "Mashhad"], ["teh" => "Tehran"]], "label" => "City"],
    ["name" => "address", "type" => "textarea", "label" => "Address"],
    ["name" => "agree", "type" => "checkbox", "label" => "I agree"],
    ["type" => "submit", "label" => "Save"],
];
$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" => "ارسال"],
];
$gm->sendText($chat_id, 'برای پرداخت قبض فرم را تکمیل کنید', null, null, $form);