مستندات API

مستندات 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 را به درستی مشخص کنید.
  • مدیریت فایل‌های باینری: مطمئن شوید که فایل‌های باینری مانند تصاویر به درستی کدگذاری و ارسال شده‌اند.

سؤالات متداول

بله، شما باید از appkey و authkey برای احراز هویت استفاده کنید.

با استفاده از Endpoint /sendFile می‌توانید پیام متنی را همراه با فایل به صورت داده باینری ارسال کنید.

در Endpoint /sendBase64، داده‌های base64 و نوع MIME را در بدنه درخواست مشخص کنید.

بله، با استفاده از Endpoint /sendContact می‌توانید پیام‌هایی حاوی اطلاعات تماس ارسال کنید.

بله، با Endpoint /chats می‌توانید لیست چت‌ها را برای یک شماره خاص بازیابی کنید.