Skip to Content
مستندات SDKPHPگفت‌وگو (چت)

سرویس گفت‌وگو

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

فهرست مطالب

متدهای گفت‌وگو

متدتوضیحاتپارامترها
createMessage()ایجاد پیامrequest: MessageRequest, userAgent, xClientInfo
createChat()ایجاد گفت‌وگوrequest: CreateChatRequest, xCreationTags, xUserSession, xClientInfo
getMessages()دریافت پیام‌های چتrequest: GetMessagesRequest
getChats()دریافت لیست گفت‌وگوهاrequest: GetChatsRequest
editMessage()ویرایش پیامrequest: EditMessageRequest, xClientInfo
deleteMessage()حذف پیام‌هاrequest: DeleteMessageRequest
deleteChats()حذف گفت‌وگوهاrequest: DeleteChatRequest
forwardMessage()فوروارد پیام‌ها به چت‌هاrequest: ForwardMessageRequest, userAgent, etc.
getUnseenChatCount()دریافت تعداد چت‌های خوانده نشدهNone

متدهای API بات

متدهای API بات به شما اجازه می‌دهند با عملکردهای مرتبط با بات تعامل داشته باشید. همه متدهای بات نیاز به یک توکن بات به فرمت: {bot_id}:{token_string} دارند (مثال: “123456789:ABCdefGHIjklMNOpqrsTUVwxyz”).

متدتوضیحاتپارامترها
getWebhookInfo()دریافت اطلاعات وب‌هوک (GET)token: string
getWebhookInfoPost()دریافت اطلاعات وب‌هوک (POST)token: string
logOut()خروج بات (GET)token: string
logOutPost()خروج بات (POST)token: string
deleteWebhookGet()حذف وب‌هوک (GET)token: string
deleteWebhookPost()حذف وب‌هوک (POST)token: string
deleteWebhookDelete()حذف وب‌هوک (DELETE)token: string
getMe()دریافت اطلاعات بات (GET)token: string
getMePost()دریافت اطلاعات بات (POST)token: string

همه متدهای بات BotApiResponse را با ویژگی‌های زیر برمی‌گردانند:

  • ok (bool) - نشان می‌دهد آیا درخواست موفق بوده است
  • result (mixed) - اطلاعات دقیق درباره بات یا عملیات (در صورت موجود بودن)
  • description (?string) - توضیحات پاسخ یا خطا
  • errorCode (?int) - کد خطا در صورت شکست درخواست

مثال‌ها

پیکربندی اولیه

<?php use Basalam\SDK\BasalamClient; use Basalam\SDK\Auth\PersonalToken; $auth = new PersonalToken( token: 'your_access_token', refreshToken: 'your_refresh_token' ); $client = new BasalamClient($auth);

ایجاد پیام

<?php use Basalam\SDK\Chat\Models\MessageRequest; use Basalam\SDK\Chat\Enums\MessageTypeEnum; use Basalam\SDK\Chat\Models\MessageInput; function createMessageExample(): object { global $client; $request = new MessageRequest( chatId: 123, messageType: MessageTypeEnum::TEXT, content: new MessageInput( text: 'سلام، چطور می‌تونم کمکتون کنم؟' ) ); $message = $client->createMessage(request: $request); return $message; }

ایجاد گفت‌وگو

<?php use Basalam\SDK\Chat\Models\CreateChatRequest; function createChatExample(): object { global $client; $request = new CreateChatRequest( userId: 123 ); $newChat = $client->createChat( request: $request, xCreationTags: 'web-app', xUserSession: 'session_token_here', xClientInfo: 'desktop' ); return $newChat; }

دریافت پیام‌ها

<?php use Basalam\SDK\Chat\Models\GetMessagesRequest; function getMessagesExample(): array { global $client; $request = new GetMessagesRequest( chatId: 123, messageId: 456, limit: 20, order: 'desc' ); $messages = $client->getMessages(request: $request); return $messages; }

دریافت لیست گفت‌وگوها

<?php use Basalam\SDK\Chat\Models\GetChatsRequest; use Basalam\SDK\Chat\Enums\MessageOrderByEnum; use Basalam\SDK\Chat\Enums\MessageFiltersEnum; function getChatsExample(): array { global $client; $request = new GetChatsRequest( limit: 30, orderBy: MessageOrderByEnum::UPDATED_AT, filters: MessageFiltersEnum::UNSEEN ); $chats = $client->getChats(request: $request); return $chats; }

ویرایش پیام

<?php use Basalam\SDK\Chat\Models\EditMessageRequest; use Basalam\SDK\Chat\Models\MessageInput; function editMessageExample(): object { global $client; $request = new EditMessageRequest( chatId: 123, messageId: 456, content: new MessageInput( text: 'متن پیام به‌روزرسانی‌شده' ) ); $editedMessage = $client->editMessage( request: $request, xClientInfo: 'web-app' ); return $editedMessage; }

حذف پیام

<?php use Basalam\SDK\Chat\Models\DeleteMessageRequest; function deleteMessageExample(): object { global $client; $request = new DeleteMessageRequest( chatId: 123, messageIds: [456, 457, 458] ); $result = $client->deleteMessage(request: $request); return $result; }

حذف گفت‌وگوها

<?php use Basalam\SDK\Chat\Models\DeleteChatRequest; function deleteChatsExample(): object { global $client; $request = new DeleteChatRequest( chatIds: [123, 124, 125] ); $result = $client->deleteChats(request: $request); return $result; }

فوروارد پیام

<?php use Basalam\SDK\Chat\Models\ForwardMessageRequest; function forwardMessageExample(): object { global $client; $request = new ForwardMessageRequest( fromChatId: 123, messageIds: [456, 457], toChatIds: [124, 125] ); $result = $client->forwardMessage( request: $request, userAgent: 'Mozilla/5.0', xClientInfo: 'web-app' ); return $result; }

دریافت تعداد چت‌های خوانده نشده

<?php function getUnseenChatCountExample(): int { global $client; $unseenCount = $client->getUnseenChatCount(); return $unseenCount; }

دریافت اطلاعات Webhook

دریافت اطلاعات فعلی وب‌هوک برای یک بات با استفاده از متد GET:

<?php function getWebhookInfoExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $webhookInfo = $client->getWebhookInfo(token: $botToken); if ($webhookInfo->getOk()) { echo 'Webhook URL: ' . $webhookInfo->getResult()['url'] ?? 'تنظیم نشده'; } return $webhookInfo; }

یا استفاده از متد POST:

<?php function getWebhookInfoPostExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $webhookInfo = $client->getWebhookInfoPost(token: $botToken); return $webhookInfo; }

خروج

خروج بات و باطل کردن توکن آن با استفاده از متد GET:

<?php function logOutExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $result = $client->logOut(token: $botToken); if ($result->getOk()) { echo 'بات با موفقیت خارج شد'; } else { echo 'خطا: ' . $result->getDescription(); } return $result; }

یا استفاده از متد POST:

<?php function logOutPostExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $result = $client->logOutPost(token: $botToken); return $result; }

حذف Webhook

حذف URL وب‌هوک برای یک بات با استفاده از متد GET:

<?php function deleteWebhookGetExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $result = $client->deleteWebhookGet(token: $botToken); if ($result->getOk()) { echo 'وب‌هوک با موفقیت حذف شد'; } return $result; }

یا استفاده از متد POST:

<?php function deleteWebhookPostExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $result = $client->deleteWebhookPost(token: $botToken); return $result; }

یا استفاده از متد DELETE (پیشنهادی):

<?php function deleteWebhookDeleteExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $result = $client->deleteWebhookDelete(token: $botToken); return $result; }

دریافت اطلاعات من

دریافت اطلاعات درباره بات با استفاده از متد GET:

<?php function getMeExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $botInfo = $client->getMe(token: $botToken); if ($botInfo->getOk()) { $bot = $botInfo->getResult(); echo 'شناسه بات: ' . $bot['id']; echo 'نام بات: ' . $bot['first_name']; echo 'نام کاربری بات: @' . $bot['username']; } return $botInfo; }

یا استفاده از متد POST:

<?php function getMePostExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $botInfo = $client->getMePost(token: $botToken); return $botInfo; }

کار با BotApiResponse

همه متدهای بات یک شیء BotApiResponse برمی‌گردانند. در اینجا نحوه کار با پاسخ آمده است:

<?php function handleBotResponseExample(): object { global $client; $botToken = '123456789:ABCdefGHIjklMNOpqrsTUVwxyz'; $response = $client->getMe(token: $botToken); // بررسی اینکه آیا درخواست موفق بوده است if ($response->getOk()) { // دسترسی به داده‌های نتیجه $botData = $response->getResult(); echo 'موفق! شناسه بات: ' . $botData['id']; } else { // مدیریت خطا echo 'کد خطا: ' . $response->getErrorCode(); echo 'توضیحات خطا: ' . $response->getDescription(); } // همچنین می‌توانید به آرایه تبدیل کنید $responseArray = $response->toArray(); return $response; }

انواع پیام

سرویس چت از انواع مختلف پیام پشتیبانی می‌کند (مشاهده MessageTypeEnum):

  • file - فایل‌های ضمیمه
  • product - کارت محصول
  • vendor - غرفه‌دار
  • text - پیام‌های متنی ساده
  • picture - پیام‌های تصویری (URL یا فایل)
  • voice - پیام‌های صوتی
  • video - پیام‌های ویدیویی
  • location - اشتراک‌گذاری موقعیت مکانی

مراحل بعدی

Last updated on