KakaoTalk

جميع الموصّلاتصندوق الواردKakaoTalk

قائمة الإعداد#

تعرض بطاقة KakaoTalk في Make Agent Fast هذه القائمة وقد مُلئت بقيمك الخاصة، لذا يُنجز معظم المالكين الخطوات من هناك. تتم كل خطوة في وحدة تحكم Kakao باستثناء الحقلين المشار إليهما أدناه.

1. أنشئ بوتًا في Kakao i Open Builder. يضم بوت واحد كل كتل السيناريو التي تُجيب بها القناة؛ تخطَّ هذه الخطوة إذا كانت القناة مرتبطة ببوت يمكنك تعديله.
2. أضف مهارة (skill) وعيّن عنوانها إلى Skill URL الخاص بالموصّل، ثم أضف ترويسة طلب مخصّصة X-Kakao-Bot-Secret تحمل Bot secret الخاص بك. لا توقّع Kakao طلبات المهارات، لذا فإن هذه الترويسة هي الدليل الوحيد على أن الاستدعاء جاء من بوتك.
3. وجّه كتلة الاحتياط (fallback) إلى المهارة حتى يصل إلى الوكيل كل سؤال لا تعالجه سيناريوهاتك. اربط كتلة سيناريو مسمّاة بالمهارة نفسها إذا كان يجب أن يجيب عنها الوكيل أيضًا.
4. فعّل خيار callback لتلك الكتلة. تتجاهل Kakao استجابة المهارة التي تستغرق أكثر من خمس ثوانٍ؛ ومع تفعيل callback يعيد Make Agent Fast فقاعة انتظار فورًا ثم ينشر الإجابة النهائية إلى userRequest.callbackUrl خلال الدقيقة التي نعدّ فيها هذا العنوان الذي يُستخدم مرة واحدة صالحًا.
5. اربط قناة KakaoTalk بالبوت، ثم الصق معرّف القناة نفسه في حقل Channel ID الخاص بالموصّل في Make Agent Fast.
6. انشر البوت. لا تصل تغييرات Open Builder إلى الزوار إلا بعد النشر، وكل تغيير لاحق في مهارة أو كتلة يحتاج إلى نشر آخر.

تمثّل بقية هذه الصفحة الشرح التفصيلي للخطوات الست نفسها.

تجهيز أصول Kakao#

أنشئ أو اختر تطبيق Kakao Developers وقناة KakaoTalk وبوت Kakao i Open Builder التي ستتولى التكامل. راجع وثائق Open Builder الرسمية من Kakao الخاصة بالمهارات والكتل.

اجمع هذه القيم أو أنشئها:

يُشترط وجود Bot secret في بيئات Make Agent Fast المنشورة لأن استدعاءات مهارات Kakao لا توفّر توقيعًا من المنصة. أنشئ قيمة فريدة عالية الإنتروبيا ولا تعيد استخدام REST API key كسر.

حفظ الموصّل#

افتح صفحة القنوات الخاصة بالوكيل، واختر KakaoTalk Channel، وأدخل القيم الثلاث جميعها، ثم اختر اتصال. يتحقق Make Agent Fast من REST API key حيثما تسمح أذونات Kakao، ويعرض Webhook URL الفريد للموصّل بعد الحفظ.

لا يستطيع Make Agent Fast إنشاء مهارة Open Builder أو ربطها بكتلة نيابةً عنك؛ يتم باقي العمل في وحدة تحكم Kakao.

ضبط مهارة Open Builder#

1. في Kakao i Open Builder، أنشئ مهارة للبوت المقصود.
2. عيّن عنوان المهارة إلى Webhook URL المنسوخ من الموصّل.
3. أضف ترويسة طلب مخصّصة باسم X-Kakao-Bot-Secret تطابق قيمتها تمامًا Bot secret.
4. اربط المهارة بكتلة الاحتياط أو كتلة السيناريو التي يجب أن تستدعي الوكيل.
5. فعّل خيار callback لتلك الكتلة حتى تتجاوز الإجابات البطيئة مهلة المهارة في Kakao البالغة خمس ثوانٍ.
6. احفظ إعدادات البوت وانشرها وفق آلية العمل في Kakao.

الترويسة غير حساسة لحالة الأحرف وفق قواعد HTTP، لكن قيمة السر يجب أن تطابق تمامًا. أي شخص يعرف عنوان webhook دون هذا السر يجب أن يتلقى استجابة غير مصرّح بها.

اختبار القدرات#

استخدم أداة الاختبار في Open Builder أولًا، ثم قناة KakaoTalk المرتبطة. أرسل سؤالًا نصيًا واقعيًا بالكورية أو بإحدى اللغات المدعومة، وتأكد من الإجابة المضمّنة ومن آخر رسالة ومن سلسلة المحادثات.

تنسخ بطاقة الموصّل نص الطلب أدناه؛ ويعمل النص نفسه مع curl على Skill URL. وهو لا يتضمن callbackUrl، لذا تعود الإجابة مضمّنة، وهذا أبسط ما يمكن التحقق منه أولًا.

{
  "intent": {
    "id": "5a56ec0cf65e53002d34e0f4",
    "name": "Fallback block"
  },
  "userRequest": {
    "timezone": "Asia/Seoul",
    "utterance": "What are your opening hours?",
    "lang": "kr",
    "user": {
      "id": "kakao-test-user",
      "type": "botUserKey",
      "properties": {
        "plusfriendUserKey": "kakao-test-user"
      }
    },
    "block": {
      "id": "5a56ec0cf65e53002d34e0f4",
      "name": "Fallback block"
    }
  },
  "bot": {
    "id": "5a56ec0cf65e53002d34e0f2",
    "name": "Your bot"
  },
  "action": {
    "id": "5a56ec0cf65e53002d34e0f6",
    "name": "Make Agent Fast skill",
    "params": {},
    "detailParams": {},
    "clientExtra": {}
  }
}

تستجيب المهارة السليمة ضمن مهلة الخمس ثوانٍ بمخرج simpleText واحد:

{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "simpleText": {
          "text": "We are open 9:00–18:00 on weekdays."
        }
      }
    ]
  }
}

عند تفعيل خيار callback للكتلة، يضيف Open Builder userRequest.callbackUrl إلى الطلب. عندها يردّ Make Agent Fast أولًا بفقاعة انتظار ثم يرسل الرد النهائي بطلب POST إلى ذلك العنوان الذي يُستخدم مرة واحدة:

{
  "version": "2.0",
  "useCallback": true,
  "data": {
    "text": "One moment — I am looking that up."
  }
}

عقد المهارة الحالي نصي فقط. يكون ردّ الوكيل skillResponse واحدًا من Kakao بالإصدار 2.0 مع مخرج simpleText، ضمن حدّ أقل من حد النص في Kakao، ويُعاد مضمّنًا أو على عنوان callback. الصوت والملفات والصور والإرسال الصوتي المنفصل غير مدعومة.

التدوير أو قطع الاتصال#

لتدوير Bot secret، حدّث الموصّل وترويسة Open Builder المخصّصة كتغيير منسّق واحد، ثم اختبر فورًا. أي عدم تطابق يوقف كل الطلبات الواردة. دوِّر REST API key في Kakao Developers وفي Make Agent Fast قبل إلغاء المفتاح القديم.

لا يؤدي تعطيل الموصّل أو إزالته إلى حذف مهارة Open Builder أو الكتلة. أزل هذه العناصر في جانب المزوّد أو افصلها عند إيقاف التكامل نهائيًا.

استكشاف الأخطاء وإصلاحها#

لا تعرض REST API key أو Bot secret في شيفرة العميل أو في الوثائق العامة.