ส่งไฟล์สื่อด้วย UnifyPort: ตรวจสอบ URL และปัญหาการส่งถึงผู้รับ

หากต้องการส่งรูป วิดีโอ เสียง หรือเอกสารผ่าน UnifyPort ให้ใช้ POST /v1/messages พร้อม message.type ที่ช่องทางรองรับ และระบุแหล่งข้อมูลที่ไม่ว่างอย่างน้อยหนึ่งรายการใน message.url, message.file_url หรือ message.file_key URL ต้องเป็น HTTP(S) แบบเต็ม ชื่อไฟล์ในเครื่องไม่ใช่ URL ที่บริการเข้าถึงได้ และผลลัพธ์ status: accepted ไม่ได้ยืนยันว่าผู้รับได้รับไฟล์แล้ว

ประเด็นสำคัญ

• ตรวจสอบช่องทางของบัญชีรับส่งข้อความก่อนเปิดให้เลือกประเภทสื่อ
• เริ่มด้วย URL ที่ชัดเจนและเข้าถึงได้เพียงรายการเดียว อย่าเดาลำดับความสำคัญของหลายแหล่งข้อมูล
• โครงสร้าง message สำหรับส่งออกต่างจาก data.message.attachments[] ที่รับเข้ามา
• แยกตรวจการเข้าถึงไฟล์ การตรวจสอบคำขอ สถานะบัญชี และผลการส่งถึงผู้รับ

เลือกข้อกำหนดของ API ที่ใช้ก่อน

อินเทอร์เฟซที่ไม่เป็นทางการของ UnifyPort ใช้ข้อกำหนดการส่งสื่อ ไม่ใช่ LINE Messaging API หรือ Telegram Bot API ตัวอย่างเช่น เอกสารการส่งไฟล์ของ Telegram ระบุรหัสไฟล์ HTTP URL และการอัปโหลดแบบ multipart สำหรับเมธอดของ Telegram เอง นั่นไม่ได้หมายความว่า UnifyPort ยอมรับ Telegram file_id เป็น file_key หรือรับคำขออัปโหลดรูปแบบเดียวกัน

ฟิลด์	สิ่งที่เอกสาร UnifyPort ระบุ
message.type	มี image, video, audio, document, file แต่ต้องตรวจการรองรับรายช่องทาง
message.url หรือ message.file_url	URL แหล่งข้อมูลแบบเต็ม HTTP(S) ที่ไม่ว่าง
message.file_key	อีกทางเลือกที่มีในเอกสาร ไม่ใช่เหตุผลให้สร้าง key หรือ endpoint อัปโหลดขึ้นเอง
message.caption	คำบรรยายที่ไม่บังคับสำหรับรูป วิดีโอ เอกสาร และไฟล์
provider_data.seconds	ระยะเวลาเสียงและวิดีโอ WhatsApp แบบไม่บังคับ เป็นจำนวนเต็มไม่ติดลบ หน่วยวินาที

ระยะเวลาวิดีโอ WhatsApp มีช่วงค่าที่ระบุไว้คือ 0–4294967295 ส่วน provider_data.waveform ใช้กับเสียงเท่านั้น อย่าคัดลอก duration_ms จากข้อมูลขาเข้าไปใส่ฟิลด์วินาทีโดยตรง หากไม่ต้องใช้ข้อมูลระยะเวลา ให้ละไว้แทนการเดาค่า

ตารางความสามารถในการส่งข้อความ ปัจจุบันไม่ระบุการรองรับเสียงและเอกสาร/ไฟล์สำหรับ TikTok ระบุเสียงของ X ว่ารองรับบางส่วน และแยก whatsapp-protocol ออกจาก whatsapp แม้เริ่มจาก LINE ก็ควรตรวจใหม่เมื่อเพิ่มช่องทางอื่น endpoint เดียวกันไม่ได้รับประกันรูปแบบสื่อหรือข้อจำกัดที่เหมือนกัน

เตรียมไฟล์ก่อนสร้างคำขอ

ลำดับต่อไปนี้เป็นคำแนะนำสำหรับแอปพลิเคชัน ไม่ใช่การรับประกันเพิ่มเติมจากแพลตฟอร์ม:

1. ตรวจว่าผู้ปฏิบัติงานมีสิทธิ์ส่งจากบัญชีที่เลือกไปยังบทสนทนานั้น สำหรับกลุ่ม ให้ใช้ ID และประเภทของบทสนทนา ไม่ใช่ ID ผู้เขียนข้อความ
2. ตรวจสถานะการอนุญาตและ runtime_status แยกกัน การอนุญาตสำเร็จไม่ได้แปลว่าเชื่อมต่ออยู่
3. วางไฟล์ที่ต้องการในแหล่งข้อมูลที่ควบคุมและเข้าถึงได้ หน้าเว็บที่ต้องเข้าสู่ระบบในเบราว์เซอร์ไม่ใช่หลักฐานว่าบริการส่งข้อความจะอ่านไฟล์ได้
4. ทดสอบการอ่านจากสภาพแวดล้อมเซิร์ฟเวอร์แยกต่างหากโดยไม่ใช้ Cookie ของเบราว์เซอร์ ตรวจว่าได้เนื้อหาสื่อจริง ไม่ใช่หน้า HTML สำหรับเข้าสู่ระบบหรือแจ้งข้อผิดพลาด
5. หากใช้ URL ที่หมดอายุได้ ให้วางแผนอายุลิงก์ตามเวลารอคิวและการอ่านที่คาดไว้ เอกสารไม่ได้รับประกันกำหนดเวลาดึงไฟล์แบบเดียวสำหรับทุกกรณี และการตรวจล่วงหน้าสำเร็จไม่ได้ยืนยันว่าจะเข้าถึงได้ภายหลัง

แนะนำให้ใช้ HTTPS จำกัดสิทธิ์เท่าที่จำเป็น และใช้แหล่งจัดเก็บที่แอปอนุมัติ อย่าบันทึกพารามิเตอร์ URL ที่มีลายเซ็นหรือข้อมูลลับลง log ทั่วไป นี่เป็นแนวทางความปลอดภัย ไม่ใช่การอ้างว่า UnifyPort มีระบบกรองเครือข่ายที่ไม่ได้ระบุในเอกสาร

สร้างคำขอส่งสื่อจาก URL

ฟังก์ชัน JavaScript นี้สร้าง body จากบัญชี บทสนทนา และ URL ที่ได้รับอนุมัติในแอป ไม่ได้อัปโหลดไฟล์หรือพิสูจน์ว่าเซิร์ฟเวอร์เข้าถึงไฟล์ได้ ต้องตรวจสิทธิ์และการรองรับช่องทางก่อนเรียกใช้

function buildMediaRequest({ accountId, conversation, type, url, caption }) {
  const types = new Set(['image', 'video', 'audio', 'document', 'file']);
  if (!accountId || !conversation?.id || !conversation?.type) {
    throw new Error('Account and conversation are required');
  }
  if (!types.has(type)) throw new Error('Unsupported media type');

  const source = new URL(url);
  if (!['http:', 'https:'].includes(source.protocol) ||
      source.username || source.password) {
    throw new Error('Use an approved HTTP(S) media source');
  }

  const message = { type, url: source.href };
  if (caption !== undefined) {
    if (type === 'audio' || typeof caption !== 'string') {
      throw new Error('Caption is not valid for this request');
    }
    message.caption = caption;
  }

  return {
    account_id: accountId,
    to: { id: conversation.id, type: conversation.type },
    message,
  };
}

ส่ง JSON ที่ได้ไปยัง POST /v1/messages โดยใช้ X-Api-Key ฝั่งเซิร์ฟเวอร์และ Content-Type: application/json ฟังก์ชันตั้งใจระบุแค่ message.url เพราะเอกสารกำหนดให้มีอย่างน้อยหนึ่งแหล่งข้อมูล แต่ไม่ได้ระบุว่าถ้าหลายแหล่งขัดแย้งกันจะเลือกฟิลด์ใดก่อน

อย่านำออบเจ็กต์ไฟล์แนบขาเข้ามาวางเป็นคำขอส่งโดยตรง คู่มือการแมปสื่อขาเข้า อธิบาย attachments[].type, url, mimetype และข้อมูลที่เกี่ยวข้อง ซึ่งเป็นฟิลด์รับเข้า ไม่ใช่คำขอส่งออกที่ครบถ้วน หากลิงก์เดิมหมดอายุ ให้ใช้คู่มือกู้คืนลิงก์ดาวน์โหลด เพื่อเลือกวิธีตาม API ที่ใช้ก่อนพยายามส่งต่อ

ตรวจสอบตามจุดที่ล้มเหลว

อาการ	ตรวจต่อที่ใด	สิ่งที่ควรหลีกเลี่ยง
ใช้พาธในเครื่อง URL แบบสัมพัทธ์ หรือ data: URL	เตรียม HTTP(S) URL แบบเต็ม	เปลี่ยนชื่อพาธให้เป็น file_key
เปิดได้เฉพาะในเบราว์เซอร์ของคุณ	การเข้าสู่ระบบ อายุลิงก์ การเปลี่ยนเส้นทาง และเนื้อหาที่ตอบกลับจริง	คิดว่าเซสชันเบราว์เซอร์จะส่งต่อไปยังบริการ
unsupported_message_type	ช่องทางและประเภทสื่อ	ส่งคำขอเดิมซ้ำ
provider_not_ready	การอนุญาตและสถานะการทำงาน	เริ่มอนุญาตบัญชีใหม่โดยยังไม่วิเคราะห์
คำขอหมดเวลารอ	เก็บบันทึกการส่งและตรวจผลที่ยังไม่แน่นอน	ส่งซ้ำอัตโนมัติจนเกิดข้อความซ้ำ
ได้ accepted	เก็บรหัสที่ตอบกลับ และตรวจหลักฐานการส่งถึงที่รองรับแยกต่างหาก	แสดงว่าส่งถึงหรืออ่านแล้วทันที

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

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

การตรวจรับและคำถามที่พบบ่อย

ก่อนใช้งานจริง ควรออกแบบการทดสอบไฟล์ที่อ่านได้ แหล่งข้อมูลหมดอายุ หน้าเข้าสู่ระบบแทนไฟล์ คู่ช่องทาง/ประเภทที่ไม่รองรับ บัญชีขาดการเชื่อมต่อ และการสูญหายของคำตอบการส่ง บทความนี้ไม่ได้อ้างว่าได้รันทดสอบเหล่านี้กับระบบจริงแล้ว

อัปโหลดไฟล์ในเครื่องโดยตรงด้วย JSON นี้ได้หรือไม่?

คำขอที่มีเอกสารรองรับใช้ URL หรือ file key บทความนี้ไม่ได้ยืนยันว่ามี endpoint อัปโหลดแบบ multipart ให้นำไฟล์ไปไว้ในระบบจัดเก็บที่ได้รับอนุญาตแล้วใช้ URL ที่เข้าถึงได้

ใช้ Telegram file_id เป็น file_key ได้หรือไม่?

เอกสารไม่ได้ระบุความเทียบเท่านี้ ต้องแยกรหัสไฟล์ของ Telegram ออกจากฟิลด์แหล่งข้อมูลของ UnifyPort

accepted หมายถึงผู้รับได้ไฟล์แล้วหรือไม่?

ไม่ใช่ เป็นการรับคำขอ ไม่ใช่การยืนยันการส่งถึงหรือการอ่าน

ขั้นตอนถัดไปและแหล่งอ้างอิง

ทำตามคู่มือส่งรูปและไฟล์ ด้วยบทสนทนาทดสอบที่ได้รับอนุญาตหนึ่งรายการและแหล่งสื่อที่อนุมัติหนึ่งแห่ง ก่อนเปิดระบบคิวหรือการส่งอัตโนมัติ

ตรวจสอบแหล่งอ้างอิงเมื่อ 2026-10-09:

• UnifyPort: ส่งข้อความสื่อ
• UnifyPort: ความสามารถในการส่งข้อความ
• UnifyPort: เอกสารข้อผิดพลาด
• Telegram: การส่งไฟล์