پیام ها را دریافت کنید

پس از ثبت نام در پیام‌های تجاری ، می‌توانید پیام‌هایی را از طرف نماینده آزمایشی خود دریافت کنید. می‌توانید پس از ایجاد ، تأیید و راه‌اندازی نمایندگان برای آن مارک‌ها، پیام‌هایی را برای مارک‌هایی که مدیریت می‌کنید دریافت کنید.

وقتی مشتری پیامی را برای نماینده ای که شما مدیریت می کنید ارسال می کند، Business Messages یک بار JSON به وب هوک شما ارسال می کند که حاوی شناسه های مختلف، محتوای پیام و اطلاعات مکان است.

از صفحه گزارش های کنسول توسعه دهنده Business Communications برای رفع اشکال مشکلات تحویل پیام استفاده کنید.

مدیریت پیام های دریافتی

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

توجه: در صورتی که یک فیلد از محموله پیام گم شده باشد، نماینده شما همچنان باید پیام را به بهترین شکل ممکن پردازش کند.

پیام را تصدیق کنید

برای تأیید پیام دریافت شده توسط وب هوک خود، یک پاسخ HTTP معتبر به پیام های ارسال شده به وب هوک خود برگردانید.

اگر پیامی به دلیل مهلت زمانی تحویل، دسترسی به وب هوک، تغییر مسیر یا مشکلات مجوز تحویل داده نشود، Google پیام را با چندین بار تکرار، به مدت 7 روز یا تا زمانی که وب هوک شما با موفقیت پیام را دریافت کند، ذخیره و بازارسال می کند.

بررسی کنید که پیام از طرف Google باشد

قبل از پردازش محتوای پیام، باید تأیید کنید که Google پیام را ارسال کرده است.

برای تأیید اینکه Google پیامی را که دریافت کرده‌اید ارسال کرده است،

1. هدر X-Goog-Signature پیام را تجزیه کنید. این یک کپی هش شده و کدگذاری شده با base64 از بار بدنه پیام است.

2. با استفاده از توکن کلاینت خود (که هنگام پیکربندی وب هوک خود ارائه شد ) به عنوان یک کلید، یک SHA512 HMAC از بایت های بار پیام ایجاد کنید و نتیجه را در base64 رمزگذاری کنید.

   توجه: اگر در حین ثبت نام در Business Messages یک کلید شریک دریافت کردید، از آن به عنوان کلید SHA512 HMAC به جای رمز مشتری استفاده کنید. اگر وب‌هوک خود را به‌روزرسانی می‌کنید، از نشانه مشتری برای تأیید اعتبار پیام با پیکربندی جدید وب‌هوک استفاده کنید.

3. هش X-Goog-Signature را با هشی که ایجاد کردید مقایسه کنید.

   • اگر هش ها مطابقت دارند، تأیید کرده اید که Google پیام را ارسال کرده است.
   • اگر هش ها مطابقت ندارند، روند هش خود را در یک پیام شناخته شده خوب بررسی کنید. اگر فرآیند هش شما به درستی کار می کند و پیامی دریافت می کنید که فکر می کنید به طور تقلبی برای شما ارسال شده است،با ما تماس بگیرید (باید با حساب Google Business Messages وارد شوید).

نمونه تأیید پیام را در مخازن GitHub برای Echo Bots در جاوا ، Node.js و Python ببینید.

منطقه را شناسایی کنید

کاربران از مکان های مختلف و به زبان های زیادی ارتباط برقرار می کنند. Business Messages ترجیحات زبانی کاربران را با فیلدهای resolvedLocale و userDeviceLocale که بر اساس تنظیمات محلی دستگاه‌هایشان است. به محلی سازی و مناطق محلی مراجعه کنید.

در صورت امکان، پیام ها را مسیریابی کنید و پاسخ ها را بر اساس ترجیحات زبانی کاربران بنویسید.

پیام را بر اساس زمینه آن مسیریابی کنید

متن پیام نشان می دهد که کاربر ممکن است به دنبال چه نوع اطلاعاتی باشد. به عنوان مثال، اگر کاربری پیامی با مقدار placeId ارسال کند، برای یک مکان خاص (که توسط placeId مشخص شده است) پیام ارسال می‌کند و احتمالاً سؤالات مربوط به مکان را می‌پرسد. به طور مشابه، اگر یک پیام دارای مقدار nearPlaceId باشد که مکان نزدیک کاربر را مشخص می‌کند، کاربر احتمالاً می‌خواهد اطلاعات مربوط به مکان را بداند، اما نماینده باید مکانی را که کاربر می‌خواهد با آن چت کند قبل از شروع مکالمه تأیید کند.

با اطلاعات زمینه پیام، پیام را به مکان مناسب برای پاسخگویی هدایت کنید:

• اگر پیام در یک مکالمه جدید است و یک سؤال رایج است، ممکن است با خودکار پاسخ دهید.
• اگر اتوماسیون نمی تواند این سؤال را حل کند، آن را به یک عامل زنده هدایت کنید.
• اگر محلی پیام با محلی پیش‌فرض نماینده شما مطابقت ندارد، پیام را به یک عامل زنده هدایت کنید که می‌تواند آن منطقه را پشتیبانی کند.
• اگر سؤال در مورد مکان خاصی است، آن را به شخصی با اطلاعات مربوط به آن مکان هدایت کنید.
• اگر پیام در یک مکالمه در حال انجام است، آن را به نماینده زنده شرکت کننده در مکالمه هدایت کنید.

نوع پیامی که کاربر ارسال کرده است را مشخص کنید

کاربران می توانند سه نوع پیام ارسال کنند:

• پیام های متنی پاسخ های آزاد هستند.
• پیام های تصویری شامل یک URL امضا شده برای تصویری است که کاربر آپلود کرده است.
• پیام‌های پیشنهادی شامل داده‌های بازپس‌گیری و متن اقدام پیشنهادی یا پاسخ پیشنهادی است که کاربر روی آن ضربه زده است.

محتوای پیام را پردازش کنید

اگر نماینده شما از اتوماسیون استفاده می کند، محتوای پیام کاربر باید منطق نماینده شما و پاسخ بعدی در مکالمه را راهنمایی کند.

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

اگر کاربر یک پیام متنی ارسال کند، نماینده شما ممکن است پاسخ را برای کلمات کلیدی پشتیبانی شده تجزیه کند یا از درک زبان طبیعی استفاده کند (مانند ادغام Dialogflow برای پردازش پیام کاربر و شناسایی مسیر رو به جلو).

اگر نماینده شما نمی داند چگونه به پیام کاربر پاسخ دهد، باید با یک حالت خطا پاسخ دهد و سعی کند با درخواست از کاربر برای اطلاعات اضافی، با درخواست ورودی به روشی دیگر، یا با دادن پیام، مکالمه را ادامه دهد. گفتگو با یک نماینده زنده

به کاربر پاسخ دهید

پس از اینکه نماینده پاسخ صحیح را شناسایی کرد - چه از طریق اتوماسیون یا یک عامل زنده - پیامی ارسال می کند و به گفتگو با کاربر ادامه می دهد.

هنگام نوشتن پاسخ، محلی کاربر را در نظر بگیرید. همچنین می‌توانید با بازیابی مقادیر از شی userInfo در هر پیامی که دریافت می‌کنید، پاسخ‌ها را سفارشی کنید.

توجه: اگر پاسخ‌های خودکار را در ادغام Dialogflow فعال کنید، پیام‌های تجاری و Dialogflow از طرف شما با بهترین پاسخ منطبق به کاربران پاسخ می‌دهند.

انواع پیام

کد زیر نشان می دهد که نماینده شما چگونه پیام ها را دریافت می کند.

برای اطلاعات قالب‌بندی و ارزش، به UserMessage مراجعه کنید.

متن

متداول ترین راه برای پاسخگویی کاربران، متن ساده است. پیام های متنی دارای فرمت زیر هستند.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "message": {
    "messageId": "MESSAGE_ID",
    "name": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "text": "MESSAGE_TEXT",
    "createTime": "MESSAGE_CREATE_TIME",
  },
  "dialogflowResponse": {
    "autoResponded": "BOOLEAN",
    "faqResponse": {
      "userQuestion": "USER_QUESTION",
      "answers": [{
        "faqQuestion": "FAQ_QUESTION",
        "faqAnswer": "FAQ_ANSWER",
        "matchConfidenceLevel": "CONFIDENCE_LEVEL",
        "matchConfidence": "CONFIDENCE_NUMERIC",
      }],
    },
  },
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

برای گزینه‌های قالب‌بندی و مقدار، به Message مراجعه کنید.

تصویر

علاوه بر ارسال متن، کاربران می توانند تصاویر را به عنوان پیام برای نماینده شما ارسال کنند. Business Messages تصاویر به اشتراک گذاشته شده را به مدت 7 روز در نشانی‌های اینترنتی امضا شده ذخیره می‌کند و آن نشانی‌های اینترنتی را در قسمت text محموله پیام درج می‌کند.

اگر نماینده شما شامل اتوماسیون است، مطمئن شوید که اتوماسیون می داند اگر کاربر تصویری را به اشتراک بگذارد چگونه پاسخ دهد. برای نمایندگی‌های زنده، مطمئن شوید که تصاویر ارسال می‌شوند یا URLهای موجود در پیام‌ها قابل کلیک هستند.

...
"message": {
    "text": "https://storage.googleapis.com/business-messages-us/936640919331/jzsu6cdguNGsBhmGJGuLs1DS?x-goog-algorithm\u003dGOOG4-RSA-SHA256\u0026x-goog-credential\u003duranium%40rcs-uranium.iam.gserviceaccount.com%2F20190826%2Fauto%2Fstorage%2Fgoog4_request\u0026x-goog-date\u003d20190826T201038Z\u0026x-goog-expires\u003d604800\u0026x-goog-signedheaders\u003dhost\u0026x-goog-signature\u003d89dbf7a74d21ab42ad25be071b37840a544a43d68e67270382054e1442d375b0b53d15496dbba12896b9d88a6501cac03b5cfca45d789da3e0cae75b050a89d8f54c1ffb27e467bd6ba1d146b7d42e30504c295c5c372a46e44728f554ba74b7b99bd9c6d3ed45f18588ed1b04522af1a47330cff73a711a6a8c65bb15e3289f480486f6695127e1014727cac949e284a7f74afd8220840159c589d48dddef1cc97b248dfc34802570448242eac4d7190b1b10a008404a330b4ff6f9656fa84e87f9a18ab59dc9b91e54ad11ffdc0ad1dc9d1ccc7855c0d263d93fce6f999971ec79879f922b582cf3bb196a1fedc3eefa226bb412e49af7dfd91cc072608e98"
  }
...

برای گزینه‌های قالب‌بندی و مقدار، به Message مراجعه کنید.

پیشنهاد

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

پیام های پیشنهادی دارای فرمت زیر هستند.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "suggestionResponse": {
    "message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "postbackData": "POSTBACK_DATA",
    "createTime": "RESPONSE_CREATE_TIME",
    "text": "SUGGESTION_TEXT",
    "suggestionType": "SUGGESTION_TYPE",
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

برای گزینه‌های قالب‌بندی و مقدار، به SuggestionResponse مراجعه کنید.

درخواست احراز هویت

پیشنهاد درخواست احراز هویت به کاربران اجازه می‌دهد تا با ارائه‌دهنده OAuth وارد سیستم شوند تا جزئیات هویت را با نماینده ارائه دهند یا به نماینده اجازه دهند اقداماتی را از طرف کاربران انجام دهد. به تأیید اعتبار با OAuth مراجعه کنید.

اگر یک کاربر با موفقیت با ارائه دهنده OAuth مشخص شده وارد شود، نماینده یک بار با کد مجوز دریافت می کند. اگر کاربر در ورود به سیستم ناموفق باشد، نماینده یک بار با جزئیات خطا دریافت می کند.

پیام های درخواست احراز هویت دارای فرمت زیر هستند.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "authenticationResponse": {
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "REDIRECT_URI",
    "errorDetails": {
      "error": "ERROR",
      "errorDescription": "ERROR_DESCRIPTION",
    },
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

برای گزینه‌های قالب‌بندی و مقدار، AuthenticationResponse را ببینید.

زمینه پیام

هر پیام حاوی اطلاعات زمینه ای در مورد جایی است که پیام منشا گرفته است.

...
  "context": {
    "customContext": "CUSTOM_CONTEXT",
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "nearPlaceId": "NEARBY_LOCATION_PLACE_ID",
    "deflectedPhoneNumber": "DEFLECTED_PHONE_NUMBER",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
    "widget": {
      "url": "WEBSITE_URL",
      "widgetContext": "WIDGET_CONTEXT",
    },
  },
...

رشته	شرح
customContext	داده های زمینه مشخص شده توسط شریک.
entryPoint	سطح پیام رسانی که کاربر مکالمه را از آن آغاز کرد، همانطور که توسط EntryPoint تعریف شده است.
placeId	یک شناسه منحصر به فرد از پایگاه داده Google Places برای مکانی که کاربر پیام داده است. فقط در پیام هایی از نقاط ورودی خاص مکان ظاهر می شود.
nearPlaceId	یک شناسه منحصر به فرد از پایگاه داده Google Places برای اولین مکان در یک بسته محلی. مکان‌هایی را که کاربران می‌خواهند با دریافت مقادیر nearPlaceId با آن‌ها چت کنند، تأیید کنید.
deflectedPhoneNumber	شماره تلفنی که Business Messages هنگام شروع مکالمه، کاربر را از تماس منحرف کرد.
resolvedLocale	بهترین تطابق محاسبه‌شده بین زبان کاربر (گزارش‌شده در userDeviceLocale ) و محلی‌های پشتیبانی‌شده عامل (تعیین شده توسط تنظیمات مکالمه مشخص شده). به محلی سازی و شروع گفتگو مراجعه کنید. مقدار محلی یک تگ زبان IETF BCP 47 است که به خوبی شکل گرفته است.
userInfo.displayName	نام کاربری که پیام را ارسال کرده است. اگر کاربر از اشتراک‌گذاری هویت منصرف شود، این قسمت خالی است.
userInfo.userDeviceLocale	محل کاربر، که توسط دستگاه آنها گزارش شده است، به عنوان یک برچسب زبان IETF BCP 47 به خوبی شکل گرفته است.
widget.url	نشانی وب سایتی که صفحه مکالمه در آن راه اندازی شد.
widget.widgetContext	مقدار ویژگی data-bm-widget-context ویجت مورد استفاده برای شروع مکالمه.

تاریخچه مکالمه

Google سابقه مکالمه را ارائه نمی دهد. مکالمات تاریخی خود را به گونه ای مطابق با خط مشی رازداری و بهترین شیوه ها حفظ کنید تا بتوانید پاسخ های آگاهانه ای به پیام های بعدی کاربران ارسال کنید.