Notify batch

POST https://api.pushwoosh.com/messaging/v2/notify/batch

ส่งหลายข้อความในการเรียกครั้งเดียว ทุกรายการเป็น Notify อิสระ: จะถูกตรวจสอบเหมือนกับคำขอ Notify แบบเดี่ยว และจะได้รับผลลัพธ์ของตัวเอง

NotifyBatch ไม่ได้ส่งข้อความเร็วกว่าการเรียก Notify โดยตรง หากการผสานรวมของคุณสามารถส่งคำขอพร้อมกันได้อยู่แล้ว การรัน Notify ใน threads/workers แบบขนานจะให้ปริมาณงานเท่ากัน — HTTP/2 จัดการสิ่งนั้นโดยการออกแบบ ใช้ NotifyBatch เพื่อความสะดวกเมื่อการผสานรวมของคุณไม่ได้สร้างขึ้นมาเพื่อการทำงานพร้อมกัน ไม่ใช่เพื่อความเร็ว

โครงสร้างคำขอ

{
  "items": [
    {
      "item_id": "caller-defined-id",
      "request": { ... }
    }
  ]
}

ฟิลด์	ประเภท	คำอธิบาย
`items`	array of `NotifyBatchItem`	จำเป็นต้องมี 1 ถึง 500 รายการ (ขีดจำกัดที่กำหนดค่าโดยเซิร์ฟเวอร์) รายการต่างๆ จะถูกประมวลผลพร้อมกัน ผลลัพธ์จะกลับมาตามลำดับของคำขอเสมอ

NotifyBatchItem

ฟิลด์	ประเภท	คำอธิบาย
`item_id`	string	ID ความสัมพันธ์ที่ผู้เรียกให้มา (ไม่บังคับ) ซึ่งจะถูกส่งกลับมาในผลลัพธ์ที่ตรงกัน Pushwoosh ไม่ได้ใช้ค่านี้ในกรณีอื่น
`request`	`NotifyRequest`	เนื้อหาเดียวกับการเรียก `Notify` ครั้งเดียว — รวมถึง `segment` หรือ `transactional`, `transaction_id` จำเป็นต้องมี

ตั้งค่า transaction_id ใน request ของแต่ละรายการ การเรียกซ้ำด้วย transaction_id เดียวกันจะคืนค่า message_code เดียวกันสำหรับรายการนั้นภายในช่วงเวลา 5 นาทีของการขจัดข้อมูลซ้ำซ้อนที่อธิบายไว้ในหน้า Notify — ดังนั้นการลองส่ง batch ทั้งหมดซ้ำหลังจากเกิดข้อผิดพลาดทางเครือข่ายจะไม่ทำให้ข้อความที่ส่งไปแล้วซ้ำซ้อน

ตัวอย่าง

curl -X POST https://api.pushwoosh.com/messaging/v2/notify/batch \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "item_id": "order-1001",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["user-123"] },
            "payload": {
              "content": {
                "localized_content": {
                  "en": { "ios": { "body": "Your order has shipped." } }
                }
              }
            },
            "schedule": { "at": "2026-05-01T12:00:00Z" },
            "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
            "transaction_id": "order-1001-shipped"
          }
        }
      },
      {
        "item_id": "order-1002",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["user-456"] },
            "payload": {
              "content": {
                "localized_content": {
                  "en": { "ios": { "body": "Your order has shipped." } }
                }
              }
            },
            "schedule": { "at": "2026-05-01T12:00:00Z" },
            "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
            "transaction_id": "order-1002-shipped"
          }
        }
      }
    ]
  }'

การตอบกลับ

{
  "results": [
    {
      "item_id": "order-1001",
      "index": 0,
      "result": {
        "message_code": "XXXXX-XXXXX-XXXXX",
        "unknown_identifiers": []
      }
    },
    {
      "item_id": "order-1002",
      "index": 1,
      "error": {
        "code": 3,
        "message": "invalid argument",
        "reason": "EmptySchedule",
        "domain": "api.pushwoosh.com"
      }
    }
  ],
  "succeeded": 1,
  "failed": 1
}

ฟิลด์	ประเภท	คำอธิบาย
`results`	array of `NotifyBatchResult`	หนึ่งรายการต่อหนึ่งรายการที่ร้องขอ ตามลำดับของคำขอ
`succeeded`	integer	จำนวนรายการที่คืนค่าผลลัพธ์
`failed`	integer	จำนวนรายการที่คืนค่าข้อผิดพลาด

NotifyBatchResult

ฟิลด์	ประเภท	คำอธิบาย
`item_id`	string	การส่งกลับ `item_id` ของรายการคำขอ
`index`	integer	ตำแหน่งของรายการในคำขอที่เริ่มจากศูนย์ ใช้สิ่งนี้เพื่อเชื่อมโยงผลลัพธ์เมื่อ `item_id` ถูกเว้นว่างไว้
`result`	object	ตั้งค่าเมื่อรายการสำเร็จ — รูปแบบเดียวกับการตอบกลับของ `Notify` ครั้งเดียว: `message_code` และ `unknown_identifiers`
`error`	`NotifyBatchError`	ตั้งค่าเมื่อรายการล้มเหลว

NotifyBatchError

ฟิลด์	ประเภท	คำอธิบาย
`code`	integer	รหัสสถานะ gRPC (`google.rpc.Code`) เช่น `3` สำหรับ `INVALID_ARGUMENT`
`message`	string	ข้อความแสดงข้อผิดพลาดสำหรับนักพัฒนา เป็นภาษาอังกฤษ
`reason`	string	ชื่อสถานะแบบย่อ — ค่าเดียวกับการเรียก `Notify` ครั้งเดียวจะคืนค่า เช่น `EmptySchedule`
`domain`	string	โดเมนข้อผิดพลาด `api.pushwoosh.com`

ข้อผิดพลาด

ข้อผิดพลาดใช้ error envelope มาตรฐานของ gRPC-Gateway: { "code": ..., "message": ..., "details": [...] } นี่คือข้อผิดพลาดระดับ envelope ที่ทำให้คำขอทั้งหมดล้มเหลว — รายการแต่ละรายการที่ล้มเหลวจะสร้าง error ต่อรายการใน results[] แทน (ดู NotifyBatchError ด้านบน) ไม่ใช่หนึ่งในข้อผิดพลาดเหล่านี้

สถานะ HTTP	เงื่อนไข
`400`	`items` ว่างเปล่า
`400`	`items` มีมากกว่าขีดจำกัดที่กำหนดค่าโดยเซิร์ฟเวอร์ (ค่าเริ่มต้นคือ 500)
`400`	หนึ่งในรายการขาด `request`

ตัวอย่าง

การส่ง 501 รายการเมื่อขีดจำกัดคือ 500 จะคืนค่า HTTP 400:

{
  "code": 3,
  "message": "items must not exceed 500 entries, got 501",
  "details": []
}

ที่เกี่ยวข้อง

Notify

Cancel

การอ้างอิง Payload

ภาพรวม Messaging API v2

การย้ายจาก v1