kenar-docs

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

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

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

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

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

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

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

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

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

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

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

```http request POST https://api.divar.ir/v2/open-platform/conversations//messages Content-Type: application/json x-api-key: x-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](#ButtonGrid) | شامل پیکربندی دکمه‌ها برای فرستنده               |
| receiver_buttons | [ButtonGrid](#ButtonGrid) | شامل پیکربندی دکمه‌ها برای گیرنده                |

### ButtonGrid

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


### ButtonRow

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


### Button

| Field Name | Field Type                 | Description                                     |
|------------|----------------------------|-------------------------------------------------|
| action     | [Action](/widgets/actions) | اکشنی که پس از کلیک کاربر بر روی دکمه رخ می‌دهد |
| icon_name  | String                     | نام آیکون نمایش داده‌شده بر روی دکمه            |
| caption    | String                     | متنی که بر روی دکمه نمایش داده می‌شود           |

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

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


### خطاها

ممکن است در پاسخ این درخواست خطا به صورت زیر دریافت شود:
```HTTP
HTTP/1.1  412
{
    "code": 9,
    "message": "message delivery failed due to recipient's restriction"
}

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

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

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

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

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

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

{
    "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"
}