ข้อความ¶

คู่มือนี้อธิบายวิธีการใช้ API สำหรับการดูประวัติข้อความ การส่งข้อความตามประเภท และการแปลข้อความ

ภาพรวม¶

ส่วนนี้อธิบายประเภทข้อความและวิธีการส่งที่ API รองรับ รวมถึงการแปลข้อความและฟีเจอร์เพิ่มเติม

ข้อความช่อง¶

• ข้อความที่ส่งไปยังผู้เข้าร่วมช่อง ซึ่งทำงานในลักษณะการกระจายเสียง
• ประวัติข้อความจะถูกจัดเตรียมตาม channelId

ข้อความตรง¶

• ข้อความที่ส่งตรงไปยังผู้ใช้คนอื่น ทำงานในลักษณะทางเดียว

ข้อความแจ้งเตือน¶

ข้อความแจ้งเตือนแบ่งออกเป็นข้อความแจ้งเตือนช่องและข้อความแจ้งเตือนผู้ใช้.

• ข้อความแจ้งเตือนช่อง: ส่งเฉพาะไปยังผู้ใช้ที่เชื่อมต่อกับ channelId ที่ระบุ
• ข้อความแจ้งเตือนผู้ใช้: ส่งเฉพาะไปยังผู้ใช้ที่มี playerId ที่ระบุ

ข้อความที่กำหนดเอง¶

• ข้อความที่กำหนดเองใช้เพื่อส่งข้อมูลจำนวนมาก แตกต่างจากข้อความแชทปกติ และไม่ใช่สำหรับการสนทนาระหว่างผู้ใช้

การแปลข้อความ¶

ส่วนนี้อธิบายฟีเจอร์การแปลอัตโนมัติและการแปลด้วยมือ รวมถึงรหัสภาษาที่มีให้สำหรับการแปล

การแปลอัตโนมัติ¶

• ไคลเอนต์เกมสามารถตั้งค่าได้ว่าจะเปิดใช้งานการแปลอัตโนมัติในแต่ละช่องทางหรือไม่ การตั้งค่าจะถูกรีเซ็ตเมื่อออกจากช่องทางหรือ断开การเชื่อมต่อจากเซิร์ฟเวอร์ซ็อกเก็ต
• ข้อความจะถูกแปลโดยใช้ รหัสภาษา ที่ตั้งค่าเมื่อเชื่อมต่อกับเซิร์ฟเวอร์ซ็อกเก็ต หากต้องการเปลี่ยนภาษาการแปล ให้เชื่อมต่อใหม่ด้วย รหัสภาษา ใหม่

การแปลด้วยตนเอง¶

• เรียกใช้ API การแปลข้อความ AI เพื่อทำการแปลข้อความต้นฉบับด้วย AI.

รหัสภาษา¶

ฟีเจอร์ข้อความเพิ่มเติม¶

ฟีเจอร์ที่สามารถเพิ่มลงในข้อความที่ส่งได้รวมถึงการถูกใจ, การกล่าวถึง, และการตอบกลับ.

• ถูกใจ: คุณสามารถเพิ่มหรือลบ 'ถูกใจ' ให้กับแต่ละข้อความในช่อง
• กล่าวถึง: คุณสามารถกล่าวถึงผู้ใช้เฉพาะในข้อความของช่องเพื่อส่งการแจ้งเตือน
• ตอบกลับ: คุณสามารถส่งการตอบกลับไปยังข้อความเฉพาะที่ส่งในช่อง

API การดึงประวัติข้อความช่อง¶

ดึงประวัติข้อความก่อนและหลัง messageId ที่ระบุในช่อง นี่สามารถขอได้เฉพาะเมื่อ chatHistoryAllowed เป็น true ในการตั้งค่าช่อง

ประวัติข้อความช่องจะถูกจัดเตรียมด้วยการแบ่งหน้าแบบใช้เคอร์เซอร์ และสามารถดึงข้อมูลประวัติข้อความจาก 30 วันที่ผ่านมาเท่านั้น

URL การร้องขอ¶

พารามิเตอร์เส้นทาง¶

พารามิเตอร์หัวเรื่อง¶

พารามิเตอร์การค้นหา¶

prevSize และ nextSize¶

prevSize และ nextSize กำหนดขอบเขตของข้อความที่จะถูกดึงมาในคำขอเดียว

prevSize จะดึงประวัติข้อความก่อนหน้า และ nextSize จะดึงประวัติข้อความถัดไปตามที่ระบุ messageId ตัวอย่างเช่น หากระบุ prevSize=10 และ nextSize=5 พร้อมกับ messageId จะดึงข้อความ 10 ข้อความก่อนหน้า messageId และ 5 ข้อความถัดไป

หากมีการเรียก API การดึงประวัติข้อความช่องโดยไม่ระบุ messageId จะมีการดึงข้อความล่าสุดเท่านั้นตามจำนวนที่ตั้งค่าโดย prevSize และค่าของ nextSize จะไม่ถูกนำมาใช้

เนื้อหาการตอบกลับ¶

เนื้อหาการตอบกลับ > ข้อมูล¶

• hasNext : หาก hasNext เป็น true จะมีประวัติข้อความถัดไปเพิ่มเติม ในกรณีนี้คุณสามารถดึงประวัติข้อความช่องเพิ่มเติมตาม messageId ที่ระบุโดย nextMessageId。
• hasPrev : หาก hasPrev เป็น true จะมีประวัติข้อความก่อนหน้านี้เพิ่มเติม ในกรณีนี้คุณสามารถดึงประวัติข้อความช่องเพิ่มเติมที่อยู่ก่อน messageId ที่ระบุโดย prevMessageId。

เนื้อหาของร่างตอบกลับ > ข้อมูล > เนื้อหา¶

เนื้อหาตอบกลับ > ข้อมูล > เนื้อหา > pluginData¶

• ข้อมูลต่อไปนี้จะถูกเพิ่มเฉพาะเมื่อมีการใช้ฟีเจอร์เพิ่มเติมของข้อความ

Response body > data > content > pluginData > like¶

เนื้อหาของการตอบกลับ > ข้อมูล > เนื้อหา > pluginData > การกล่าวถึง¶

เนื้อหาตอบกลับ > ข้อมูล > เนื้อหา > pluginData > การตอบกลับ¶

ตัวอย่างคำขอ¶

curl --request GET 'https://test-api-chat.withhive.com/api/v2/games/1/channels/open:1/messages?messageId=abcdefg&nextSize=10&prevSize=10&order=DESC' \
--header 'Authorization: hivechat 005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76'

ตัวอย่างการตอบกลับ¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "hasNext": true,
    "nextMessageId": "XY0QSDRezljxWI02",
    "hasPrev": true,
    "prevMessageId": "j2FwC8Zdq5vwX8kJ",
    "content": [
      {
        "gameIndex": 1,
        "from": 1111112,
        "messageId" : "0n4K8pkqjpWjkrUH",
        "extraData": "김하이브",
        "to": "open:10",
        "message": "안녕하세요.",
        "langCode": "ko",
        "timestamp": "2025-03-05T04:50:59.757Z",
        "timestampMillis": 1741150259757
      },
      {
        "gameIndex": 1,
        "from": 1111111,
        "messageId" : "J3N1YYimo5o7Mpb5",
        "extraData": "",
        "to": "open:10",
        "message": "하이브",
        "langCode": "ko",
        // 메시지 추가 기능을 사용하였을 경우
        "pluginData" : {
          // 좋아요
          "like": {
            "playerIds": [
              1
            ]
          },
          // 멘션
          "mentions": [
            {
              "playerId": 101
              }
          ],
          // 답글
          "reply": {
            "originalMessageId": "yIKzxKCihLVu9VR8",
            "originalMessage": "111",
            "originalExtraData": null,
            "originalTimestampMillis": 1752487464039
            }
        },
        "timestamp": "2025-03-05T04:51:01.689Z",
        "timestampMillis": 1741150261689
      },
      // 이하 동일한 형식의 객체
    ]
  }
}

API การส่งข้อความแจ้งเตือน¶

ส่งข้อความแจ้งเตือนไปยังผู้ใช้ที่เชื่อมต่อกับช่องทางเฉพาะหรือเซิร์ฟเวอร์ซ็อกเก็ต

URL การร้องขอ¶

พารามิเตอร์เส้นทาง¶

พารามิเตอร์หัวเรื่อง¶

เนื้อหาคำขอ¶

เนื้อหาคำขอ > channelId¶

• หากมีการระบุ channelId ข้อความจะถูกส่งไปยังผู้ใช้ทั้งหมดที่เชื่อมต่อกับช่องที่ระบุในฐานะ ข้อความแจ้งเตือนช่อง。
• หากไม่มีการระบุ channelId ข้อความจะถูกส่งไปยังผู้ใช้ทั้งหมดที่เชื่อมต่อกับเซิร์ฟเวอร์ซ็อกเก็ตในฐานะ ข้อความแจ้งเตือนผู้ใช้。

ร่างคำขอ > langCode¶

• หากมีการระบุ langCode ข้อความจะถูกส่งไปยังผู้ใช้ที่มีรหัสภาษาตรงกันเท่านั้น ตัวอย่างเช่น หาก langCode เป็น en ข้อความจะถูกส่งไปยังผู้ใช้ที่ตั้งค่า langCode เป็น en เท่านั้น
• หากไม่มีการระบุ langCode ข้อความจะถูกส่งไปยังผู้ใช้ทุกคนไม่ว่าจะเป็นภาษาใดก็ตาม

เนื้อหาการตอบกลับ¶

ตัวอย่างคำขอ¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/notice' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "channelId": "open:12345",
    "langCode": "en",
    "message": "서버 점검이 있습니다. 잠시 후 다시 접속해 주세요."
}'

ตัวอย่างการตอบกลับ¶

{
    "code": 0,
    "message": "Success."
}

API การส่งข้อความแจ้งเตือนผู้ใช้¶

ส่งข้อความแจ้งเตือนผู้ใช้ไปยังผู้ใช้ที่มี ID ผู้เล่นที่ระบุ

URL ที่ร้องขอ¶

พารามิเตอร์เส้นทาง¶

พารามิเตอร์หัวข้อ¶

เนื้อหาคำขอ¶

เนื้อหาของคำขอ > langCode¶

• หากมีการระบุ langCode ข้อความจะถูกส่งไปยังผู้ใช้ที่มีรหัสภาษาตรงกับ langCode ที่ระบุในขณะที่เชื่อมต่อกับเกมไคลเอนต์ ตัวอย่างเช่น หากผู้ใช้ที่มี playerId=1111 เชื่อมต่อด้วย langCode=en และมีการเรียก API นี้ด้วย playerId=1111, langCode=ja ข้อความจะไม่ถูกส่งไปยังผู้ใช้
• หากไม่มีการระบุ langCode ข้อความจะถูกส่งไปยังผู้ใช้ที่มี playerId ที่ระบุไม่ว่าจะเป็นภาษาใดก็ตาม

เนื้อหาการตอบกลับ¶

ตัวอย่างคำขอ¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/notice/users/123123' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "langCode": "en",
    "message": "123123 님에게 보내는 공지 메시지입니다."
}'

ตัวอย่างการตอบกลับ¶

{
    "code": 0,
    "message": "Success."
}

API การส่งข้อความที่กำหนดเองของช่อง¶

ส่งข้อความที่กำหนดเองไปยังผู้ใช้ทั้งหมดที่เข้าร่วมในช่องเฉพาะ

URL การร้องขอ¶

พารามิเตอร์เส้นทาง¶

พารามิเตอร์หัวเรื่อง¶

เนื้อหาคำขอ¶

เนื้อหาการตอบกลับ¶

ตัวอย่างคำขอ¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/custom-message/channels/public:123' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "message": "커스텀 메시지입니다."
}'

ตัวอย่างการตอบกลับ¶

{
    "code": 0,
    "message": "Success."
}

API การส่งข้อความที่กำหนดเองของผู้ใช้¶

ส่งข้อความที่กำหนดเองไปยังผู้ใช้ที่ระบุสูงสุด 10 คน

URL ที่ร้องขอ¶

พารามิเตอร์เส้นทาง¶

พารามิเตอร์หัวเรื่อง¶

เนื้อหาคำขอ¶

เนื้อหาการตอบกลับ¶

ตัวอย่างคำขอ¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/custom-message/users' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "playerIds": [
        123123
    ],
    "message": "커스텀 메시지입니다."
}'

ตัวอย่างการตอบกลับ¶

{
    "code": 0,
    "message": "Success."
}

API แปลข้อความ AI¶

แปลข้อความในข้อความไปยังภาษาที่กำหนด

URL การร้องขอ¶

พารามิเตอร์เส้นทาง¶

พารามิเตอร์หัวเรื่อง¶

เนื้อหาคำขอ¶

เนื้อหาการตอบกลับ¶

เนื้อหาการตอบกลับ > ข้อมูล¶

เนื้อหาการตอบกลับ > ข้อมูล > การแปล¶

※ เมื่อขอ API แปลภาษา รหัสภาษา Hive(เช่น en, ja, ar) ที่ระบุจะถูกใช้เป็นชื่อฟิลด์ {lang}

ตัวอย่างคำขอ¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/translate' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
    "text": "안녕하세요. 반갑습니다.",
    "from": "ko",
    "to": "en, ja, ar"
}'

ตัวอย่างการตอบกลับ¶

{
    "code": 0,
    "message": "Success.",
    "data": {     
        "translations": {
            "ar": "مرحبا. تشرفنا.",
            "ja": "こんにちは。はじめまして。",
            "en": "Hello. Nice to meet you."
        }
    }
}