مستندات API WallMessage
API WallMessage به توسعه‌دهندگان اجازه می‌دهد تا به سادگی و به طور امن پیامهایی از انواع مختلف (متنی، رسانه‌ای، تماس و موقعیت جغرافیایی) را به کاربران ارسال کنند. این API به صورت استاندارد با استفاده از Swagger مستندسازی شده است که تجربه‌ای ساده و شفاف برای کاربران فراهم می‌کند.
Swagger چیست و چرا مهم است؟
Swagger یک ابزار مستندسازی API است که به توسعه‌دهندگان کمک می‌کند تا APIهای خود را به شکلی ساختارمند و شفاف مستند کنند. این ابزار از طریق ارائه یک رابط کاربری تعاملی به کاربران اجازه می‌دهد که Endpointهای مختلف API را مشاهده و حتی تست کنند.
مزایای Swagger برای مستندسازی API:
- رابط کاربری تعاملی: کاربران می‌توانند با استفاده از Swagger مستقیماً API را تست کنند.
- خوانایی و وضوح بالا: این ابزار کمک می‌کند تا مستندات API به شکل واضح و دقیق ارائه شوند.
- پشتیبانی سوئگر از OAS (OpenAPI Specification):به عنوان یکی از محبوب‌ترین ابزارها، از استانداردهای OpenAPI پیروی می‌کند.
- سرعت بیشتر در توسعه و تست API: توسعه‌دهندگان با کمک این ابزار به سرعت می‌توانند API را تست و اشکالات آن را برطرف کنند.
ساختار کلی API WallMessage
API WallMessage شامل ۸ Endpoint اصلی است که هر کدام برای ارسال نوعی پیام خاص استفاده می‌شوند. در ادامه، توضیح هر Endpoint و جزئیات مربوط به آن آورده شده است.
Endpoint 1
– ایجاد پیام متنی
- آدرس: /create-message
- روش: POST
- توضیحات: این Endpoint برای ایجاد پیام متنی جدید استفاده می‌شود.
درخواست
{
"appkey": "string",
"authkey": "string",
"to": "string",
"message": "string"
}
پاسخ
- کد وضعیت 200: پیام با موفقیت ایجاد شد.
Endpoint 2
– ارسال پیام متنی به مقصد مشخص
- آدرس: /sendMessage
- روش: POST
- توضیحات: این Endpoint پیام متنی را به یک مقصد مشخص ارسال می‌کند.
درخواست
{
"appkey": "string",
"authkey": "string",
"to": "string",
"message": "string"
}
پاسخ
- کد وضعیت 200: پیام با موفقیت ارسال شد.
Endpoint 3
– ارسال پیام با فایل
- آدرس: /sendFile
- روش: POST
- توضیحات: این Endpoint پیام متنی را به همراه فایل ارسال می‌کند.
درخواست
{
"appkey": "string",
"authkey": "string",
"to": "string",
"message": "string",
"file": "string($binary)"
}
پاسخ
- کد وضعیت 200: پیام با موفقیت ارسال شد.
Endpoint 4
– ارسال پیام متنی با داده base64
- آدرس: /sendBase64
- روش: POST
- توضیحات: این Endpoint پیام متنی را به همراه دادههای base64 و نوع MIME ارسال می‌کند.
درخواست
{
"appkey": "string",
"authkey": "string",
"to": "string",
"message": "string",
"base64": "string",
"mimetype": "string"
}
پاسخ
- کد وضعیت 200: پیام با داده base64 و نوع MIME با موفقیت ارسال شد.
Endpoint 5
– ارسال پیام حاوی اطلاعات تماس
- آدرس: /sendContact
- روش: POST
- توضیحات: این Endpoint پیام حاوی اطلاعات تماس ارسال می‌کند.
درخواست
{
"appkey": "string",
"authkey": "string",
"to": "string",
"display_name": "string",
"full_name": "string",
"org_name": "string",
"contact_number": "string",
"wa_number": "string"
}
پاسخ
- کد وضعیت 200: پیام حاوی اطلاعات تماس با موفقیت ارسال شد.
Endpoint 6
– ارسال پیام حاوی موقعیت جغرافیایی
- آدرس: /sendLocation
- روش: POST
- توضیحات: این Endpoint پیام حاوی موقعیت جغرافیایی ارسال می‌کند.
درخواست
{
"appkey": "string",
"authkey": "string",
"to": "string",
"latitude": "string",
"longitude": "string"
}
پاسخ
- کد وضعیت 200: پیام حاوی موقعیت جغرافیایی با موفقیت ارسال شد.
Endpoint 7
– دریافت اطلاعات چت با شناسه چت
- آدرس: /chats/{chatid}
- روش: GET
- توضیحات: این Endpoint اطلاعات یک چت خاص را بر اساس شناسه چت بازیابی می‌کند.
پارامترهای مسیر و کوئری
- chatid (مسیر): شناسه چت
- appkey (کوئری): کلید برنامه برای احراز هویت
- authkey (کوئری): کلید احراز هویت کاربر
پاسخ
- کد وضعیت 200: اطلاعات چت با موفقیت بازیابی شد.
Endpoint 8
– دریافت لیست چتها برای یک شماره خاص
- آدرس: /chats
- روش: GET
- توضیحات: این Endpoint لیست چتها را برای یک شماره خاص بازیابی می‌کند.
پارامترهای کوئری
- appkey: کلید برنامه برای احراز هویت
- authkey: کلید احراز هویت کاربر
پاسخ
- کد وضعیت 200: لیست چتها با موفقیت بازیابی شد.
نکات کلیدی برای استفاده از API WallMessage
- کنترل دسترسی: حتماً از appkey و authkey برای احراز هویت استفاده کنید.
- بررسی نوع MIME: در ارسال دادههای base64 نوع MIME را به درستی مشخص کنید.
- مدیریت فایل‌های باینری: مطمئن شوید که فایل‌های باینری مانند تصاویر به درستی کدگذاری و ارسال شده‌اند.
پرسش‌های متداول (FAQ)
آیا برای استفاده از API WallMessage نیاز به احراز هویت داریم؟
بله، شما باید از appkey و authkey برای احراز هویت استفاده کنید.
چگونه میتوان پیام با فایل ارسال کرد؟
با استفاده از Endpoint /sendFile میتوانید پیام متنی را همراه با فایل به صورت داده باینری ارسال کنید.
چگونه میتوان پیام با داده base64 ارسال کرد؟
در Endpoint /sendBase64، دادههای base64 و نوع MIME را در بدنه درخواست مشخص کنید.
آیا میتوان اطلاعات تماس را در پیام ارسال کرد؟
بله، با استفاده از Endpoint /sendContact میتوانید پیامهایی حاوی اطلاعات تماس ارسال کنید.
آیا میتوان به لیست چتها دسترسی داشت؟
بله، با Endpoint /chats میتوانید لیست چتها را برای یک شماره خاص بازیابی کنید.
