Skip to content

Latest commit

 

History

History
220 lines (177 loc) · 10.2 KB

send_message.md

File metadata and controls

220 lines (177 loc) · 10.2 KB
Raw

ارسال پیام در چت

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

نمایی از یک پیام ارسال شده توسط بات
نمایی از یک پیام ارسال شده توسط بات

⭐️ بهتر است پیامی که در چت ارسال می‌کنید برای هر دو طرف معنادار باشد و اطلاعات مفید در راستای خدمت دریافت شده ارائه دهد.

🛑 برای مقاصد تبلیغاتی یا معرفی امکانات و خدماتتان پیام ارسال نکنید.

دسترسی ارسال پیام در چت

برای اینکه بتوانید در یک چت پیامی ارسال کنید، نیاز است تا اجازهٔ دسترسی در دو نقطه فراهم شده‌باشد:
۱. برنامهٔ شما به صورت کلی دسترسی لازم را در پنل کنار دیوار گرفته‌باشد.
۲. از کاربر اجازه گرفته‌باشید و access_token ارسالی در درخواستتان این اجازه را داشته‌باشد:

  • SCOPE: CONVERSATION_SEND_MESSAGE
  • IDENTIFIER: CONVERSATION_ID

دو نوع دسترسی برای ارسال پیام در چت وجود دارد که برای هر کدام می‌توان جداگانه از کاربر اجازه گرفت. ارسال پیام در یک چت و ارسال پیام در چت‌های یک آگهی جزییات و پارامترهای لازم برای درخواست دسترسی و ایجاد access_token را در صفحهٔ احراز باز ببینید.

درخواست ارسال پیام در چت

در صورتی که اجازهٔ این درخواست رو طبق توضیحات بالا و صفحهٔ احراز باز داشته‌باشید، با ارسال درخواستی مشابه نمونهٔ زیر می‌توانید در چت مورد نظرتان پیام وارد کنید.

می‌توانید قسمت‌های فارسی را با مقادیر خودتان جایگزین کنید:

POST https://api.divar.ir/v2/open-platform/conversations/{{conversation_id}}/messages
Content-Type: application/json
x-api-key: {{apikey}}
x-access-token: {{access_token}}

{
  "type": "TEXT",
  "message": "متن پیام",
  "sender_buttons": {
    "rows": [
      {
        "buttons": [
          {
            "action": {
              "open_direct_link": "آدرس مورد نظر برای باز شدن بعد از کلیک"
            },
            "icon_name": "نام آیکون",
            "caption": "متن دکمه"
          },
          {
            "action": {
              "open_server_link": {
                "data": {
                  "my_key_1": "value",
                  "my_key_2": "value2"
                }
              }
            },
            "icon_name": "نام آیکون",
            "caption": "متن دکمه"
          }
        ]
      }
    ]
  },
  "receiver_buttons": {
    "rows": [
      {
        "buttons": [
          {
            "action": {
              "open_direct_link": "آدرس مورد نظر برای باز شدن بعد از کلیک"
            },
            "icon_name": "نام آیکون",
            "caption": "متن دکمه"
          },
          {
            "action": {
              "open_server_link": {
                "data": {
                  "my_key_1": "value",
                  "my_key_2": "value2"
                }
              }
            },
            "icon_name": "نام آیکون",
            "caption": "متن دکمه"
          }
        ]
      }
    ]
  }
}

درخواست

Field Name Field Type Description
type String نوع محتوا را مشخص می‌کند، در حال حاضر فقط "TEXT"
message String محتوای متن پیام
sender_buttons ButtonGrid شامل پیکربندی دکمه‌ها برای فرستنده
receiver_buttons ButtonGrid شامل پیکربندی دکمه‌ها برای گیرنده

ButtonGrid

Field Name Field Type Description
rows Array[ButtonRow] آرایه‌ای از ردیف دکمه‌ها. حداکثر ۳ ردیف

ButtonRow

Field Name Field Type Description
buttons Array[Button] آرایه‌ای از دکمه‌ها. حداکثر ۳ دکمه در هر ردیف

Button

Field Name Field Type Description
action Action اکشنی که پس از کلیک کاربر بر روی دکمه رخ می‌دهد
icon_name String نام آیکون نمایش داده‌شده بر روی دکمه
caption String متنی که بر روی دکمه نمایش داده می‌شود

در درخواست بالا، کاربران با زدن روی دکمهٔ پیام، در قالب webview یا pop-up به برنامهٔ شما وارد می‌شوند، در صورتی که نیاز به باز کردن صفحهٔ خود به صورت مستقیم در مرورگر دارید، می‌توانید ویژگی‌های دکمه را به شکل زیر تغییر دهید.

{
    "sender_btn": {
        "action": "DIRECT_LINK",
        "data": {
            "icon_name": "نام آیکون مورد نظر برای این دکمه",
            "direct_link": "آدرس صفحهٔ مورد نظر برای باز شدن هنگام کلیک",
            "caption": "متن دکمهٔ زیر پیام برای طرف فرستنده"
        }
    }
}

خطاها

ممکن است در پاسخ این درخواست خطا به صورت زیر دریافت شود:

HTTP/1.1  412
{
    "code": 9,
    "message": "message delivery failed due to recipient's restriction"
}

این خطا به چند دلیل می ‌تواند دریافت شود:

  • کاربر توسط کاربر مقابل در چت مسدود شده باشد
  • کاربر یا کاربر مقابل در بلک لیست باشند.
  • ...

دسترسی ارسال پیام در تمام مکالمات یک آگهی (آزمایشی)

دسترسی قبلی تنها مربوط به یک مکالمه می‌باشد، اما با داشتن این دسترسی می‌توانید در تمام مکالمات مربوط به یک آگهی از طرف آگهی گذار پیام بفرستید:

  • SCOPE: CHAT_POST_CONVERSATIONS_MESSAGE_SEND
  • IDENTIFIER: POST_TOKEN

کلیک کاربر روی دکمهٔ درج شده زیر پیام

در صورتی که کاربر روی دکمه‌ای که زیر پیام اضافه کرده‌اید کلیک کند، ابتدا دیوار یک درخواست به آدرسی که در ابتدا تنظیم کرده‌اید می‌زند. توضیحات بیشتر

به همراه این درخواست موارد زیر ارسال خواهند شد و سپس کاربر به آدرسی که در دکمهٔ مورد نظر درج شده‌است هدایت می‌شود.

نمونهٔ محتوای ارسالی درخواست از سمت دیوار

{
    "extra_data": {
        "provider_data": {"your_custom_key":"اطلاعاتی که در درخواست ارسال پیام در مرحلهٔ قبل فرستادید"}
    },
    "callback_url": "آدرسی که کاربر پس از انجام فرایند در سرویس شما باید به آن هدایت شود",
    "post_token":   "توکن آگهی",
    "user_id":      "شناسهٔ کسی که روی لینک کلیک کرده یا فرایند را شروع کرده",
    "peer_id":      "شناسهٔ طرف مقابل چت",
    "supplier": {
        "id": "شناسهٔ کاربر فروشنده (صاحب آگهی)"
    },
    "demand": {
        "id": "شناسهٔ کاربر خریدار"
    },
    "conversation_id": "شناسه مکالمه"
}

در پاسخ به این درخواست، می‌بایست آدرسی را به شکل زیر برگردانید. کاربر به أدرسی که در قسمت url پاسخ شماست هدایت می‌شود و با برنامهٔ تحت وب شما تعامل می‌کند.

{
  "status": "200",
  "message": "success",
  "url": "https://yourdomain.com/some/where/to/start"
}