سرویس گفتوگو
مدیریت پیامها و قابلیتهای گفتوگو با استفاده از سرویس چت. این سرویس ابزارهای جامعی برای مدیریت مکالمات، پیامها و تعاملات چت فراهم میکند: ایجاد و مدیریت گفتوگوها، ارسال و دریافت پیامها، مدیریت انواع مختلف پیام، مدیریت شرکتکنندگان چت و پیگیری تاریخچه و بهروزرسانیهای چت.
فهرست مطالب
متدهای گفتوگو
| متد | توضیحات | پارامترها |
|---|---|---|
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- اشتراکگذاری موقعیت مکانی
مراحل بعدی
- سرویس سفارش - مدیریت سفارشات و پرداختها
- سرویس آپلود - آپلود و مدیریت فایل
- سرویس جستجو - جستجو برای محصولات و موجودیتها