send_message.md

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

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

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

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

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

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

برای اینکه بتوانید در یک چت پیامی ارسال کنید، نیاز است تا اجازهٔ دسترسی در دو نقطه فراهم شده‌باشد:
۱. برنامهٔ شما به صورت کلی دسترسی لازم را در پنل کنار دیوار گرفته‌باشد.
۲. از کاربر اجازه گرفته‌باشید و 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	متنی که بر روی دکمه نمایش داده می‌شود

خطاها

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

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

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

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

دسترسی ارسال پیام در تمام مکالمات یک آگهی

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

• SCOPE: CHAT_POST_CONVERSATIONS_MESSAGE_SEND
• IDENTIFIER: POST_TOKEN

دسترسی ارسال پیام در تمام مکالمات تمام آگهی‌های آگهی گذار

در صورتی که نیاز دارید در تمام چت‌هایی که کاربر سمت آگهی گذار می‌باشد، پیام ارسال کنید می‌توانید از اسکوپ زیر استفاده که RESOURCE_ID یا IDENTIFIER ندارد:

• SCOPE: CHAT_SUPPLIER_ALL_CONVERSATIONS_MESSAGE_SEND

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

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