Skip to main content

📄 Send File Messages

Send documents, PDFs, and other files to WhatsApp contacts using the Whatspie API with support for various file formats and automatic file type detection.

📎 Universal File Support

Send any document type with automatic file detection, preview generation, and intelligent compression for optimal delivery.

🌐 Endpoint​

POST https://api.whatspie.com/messages

🔐 Authentication​

Bearer token required with proper JSON content headers.

📋 Request Parameters​

ParameterTypeRequiredDescription
devicestring✅Your registered WhatsApp device number
receiverstring✅Recipient's phone number (international format)
typestring✅Message type: "file" for file messages
paramsobject✅Message parameters containing file data
params.documentobject✅Document object with URL
params.document.urlstring✅Direct URL to the file
params.fileNamestring✅Display filename with extension
params.mimetypestring✅MIME type of the file
simulate_typinginteger❌Show typing indicator: 1 (yes) or 0 (no)

📁 Supported File Formats​

📋 Documents

  • PDF (.pdf)
  • Word (.doc, .docx)
  • Excel (.xls, .xlsx)
  • PowerPoint (.ppt, .pptx)
  • Text files (.txt)

🗜️ Archives

  • ZIP (.zip)
  • RAR (.rar)
  • 7-Zip (.7z)
  • TAR (.tar, .tar.gz)

💻 Development

  • JavaScript (.js, .jsx)
  • Python (.py)
  • Java (.java)
  • C/C++ (.c, .cpp, .h)
  • HTML/CSS (.html, .css)

🎵 Media Files

  • Audio (.mp3, .wav, .ogg)
  • Video (.mp4, .avi, .mov)
  • Images (.jpg, .png, .gif)
  • eBooks (.epub, .mobi)

🚀 Request Examples​

Basic File Message​

curl -X POST "https://api.whatspie.com/messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "device": "6281234567890",
    "receiver": "6289876543210",
    "type": "file",
    "params": {
      "document": {
        "url": "https://example.com/documents/report.pdf"
      },
      "fileName": "Monthly_Sales_Report_Q4_2024.pdf",
      "mimetype": "application/pdf"
    },
    "simulate_typing": 1
  }'

File with Description​

curl -X POST "https://api.whatspie.com/messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "device": "6281234567890",
    "receiver": "6289876543210",
    "type": "file",
    "params": {
      "document": {
        "url": "https://cdn.example.com/files/presentation.pptx"
      },
      "fileName": "Product_Launch_Presentation_Q1.pptx",
      "mimetype": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
    },
    "simulate_typing": 1
  }'

Technical Document​

curl -X POST "https://api.whatspie.com/messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "device": "6281234567890",
    "receiver": "6289876543210", 
    "type": "file",
    "file_url": "https://docs.example.com/api/documentation.pdf",
    "message": "📚 API Documentation v2.1\n\nLatest version with new endpoints and examples.",
    "simulate_typing": 1
  }'

📊 Response Format​

Success Response​

{
  "code": 200,
  "message": "File sent successfully",
  "data": {
    "id": "msg_file_12345",
    "status": "pending",
    "type": "file",
    "device": "6281234567890",
    "receiver": "6289876543210",
    "file_url": "https://example.com/document.pdf",
    "message": "📄 Important Document",
    "file_info": {
      "name": "document.pdf",
      "size": "2.5MB",
      "type": "application/pdf"
    },
    "timestamp": "2024-12-20T10:30:00Z"
  }
}

Error Response - Invalid File URL​

{
  "code": 400,
  "message": "Invalid file URL",
  "error": "File URL is not accessible or file too large (max 100MB)"
}

💡 Best Practices​

1. File URL Validation​

function validateFileUrl(url) {
  const urlPattern = /^https?:\/\/.+/;
  
  if (!urlPattern.test(url)) {
    throw new Error('File URL must use HTTP or HTTPS protocol');
  }
  
  // Check file extension
  const allowedExtensions = [
    'pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx',
    'txt', 'csv', 'zip', 'rar', '7z', 'tar', 'gz',
    'jpg', 'jpeg', 'png', 'gif', 'mp3', 'mp4', 'avi'
  ];
  
  const extension = url.split('.').pop().toLowerCase();
  
  if (!allowedExtensions.includes(extension)) {
    throw new Error(`File type .${extension} is not supported`);
  }
  
  return true;
}

2. File Description Best Practices​

function formatFileMessage(fileName, description, fileSize = null) {
  let message = '';
  
  // Add appropriate emoji based on file type
  const extension = fileName.split('.').pop().toLowerCase();
  const fileEmojis = {
    'pdf': '📄',
    'doc': '📝', 'docx': '📝',
    'xls': '📊', 'xlsx': '📊',
    'ppt': '📽️', 'pptx': '📽️',
    'zip': '📦', 'rar': '📦',
    'jpg': '🖼️', 'png': '🖼️',
    'mp3': '🎵', 'mp4': '🎬'
  };
  
  const emoji = fileEmojis[extension] || '📎';
  message += `${emoji} ${fileName}`;
  
  if (fileSize) {
    message += ` (${fileSize})`;
  }
  
  if (description) {
    message += `\n\n${description}`;
  }
  
  return message;
}

// Usage
const message = formatFileMessage(
  'quarterly-report.pdf',
  'Q3 financial results and market analysis',
  '3.2MB'
);
// Result: "📄 quarterly-report.pdf (3.2MB)\n\nQ3 financial results and market analysis"

3. Batch File Sending​

async function sendMultipleFiles(token, device, receiver, files, delay = 2000) {
  const results = [];
  
  for (const file of files) {
    try {
      const result = await sendFileMessage(
        token,
        device,
        receiver,
        file.url,
        file.message
      );
      
      results.push({
        file: file.name,
        success: true,
        messageId: result.data.id
      });
      
      // Delay between files to avoid rate limiting
      if (delay > 0) {
        await new Promise(resolve => setTimeout(resolve, delay));
      }
      
    } catch (error) {
      results.push({
        file: file.name,
        success: false,
        error: error.message
      });
    }
  }
  
  return results;
}

// Usage
const files = [
  {
    name: 'contract.pdf',
    url: 'https://docs.example.com/contract.pdf',
    message: '📋 Service Contract\n\nPlease review and sign.'
  },
  {
    name: 'invoice.pdf', 
    url: 'https://billing.example.com/invoice.pdf',
    message: '💳 Invoice #12345\n\nPayment due: Dec 30, 2024'
  }
];

const results = await sendMultipleFiles('YOUR_TOKEN', '6281234567890', '6289876543210', files);
console.log('Batch send results:', results);

⚠️ Limitations​

  • File size: Maximum 100MB per file
  • File URL: Must be publicly accessible via HTTP/HTTPS
  • File types: Limited to supported formats only
  • Upload time: Large files may take longer to process
  • Retention: Files cached temporarily for delivery optimization

🔗 Related Endpoints​