Sending Media Messages

Send images, documents, videos, and audio files via the Chatbase WhatsApp API

Sending Media Messages

WhatsApp supports rich media in messages — images, PDFs, videos, and audio files. This guide covers how to send each type.

Supported Media Types

Method 1 — Public URL

The simplest way: provide a publicly accessible HTTPS URL for the media.

Send an Image

await api.post('/messages/send', {
  to: '919876543210',
  type: 'image',
  image: { link: 'https://yourcdn.com/product-photo.jpg' },
  caption: 'Check out our latest product!',
});

Send a Document

await api.post('/messages/send', {
  to: '919876543210',
  type: 'document',
  document: {
    link: 'https://yourcdn.com/invoice-1234.pdf',
    filename: 'Invoice-1234.pdf',
  },
  caption: 'Your invoice for order #1234',
});

Send a Video

await api.post('/messages/send', {
  to: '919876543210',
  type: 'video',
  video: { link: 'https://yourcdn.com/product-demo.mp4' },
  caption: 'Watch our 2-minute product demo',
});

Method 2 — File Upload

Upload a file directly using multipart/form-data. The file is hosted on Chatbase's servers and delivered via WhatsApp.

Using cURL

curl -X POST https://chatbase.in/api/v1/whatsapp/messages/send \
  -H "Authorization: Bearer wpapi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "to=919876543210" \
  -F "type=image" \
  -F "caption=Your delivery confirmation photo" \
  -F "file=@/path/to/photo.jpg"

Using Node.js (axios + FormData)

const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('to', '919876543210');
form.append('type', 'document');
form.append('caption', 'Your invoice');
form.append('file', fs.createReadStream('./invoice.pdf'), {
  filename: 'invoice.pdf',
  contentType: 'application/pdf',
});

const { data } = await api.post('/messages/send', form, {
  headers: form.getHeaders(),
});

Image in Template Header

You can also include an image in a template's header component:

await api.post('/messages/send', {
  to: '919876543210',
  type: 'template',
  template: {
    name: 'product_launch',
    language: { code: 'en_US' },
    components: [
      {
        type: 'header',
        parameters: [
          {
            type: 'image',
            image: { link: 'https://yourcdn.com/launch-banner.jpg' },
          },
        ],
      },
      {
        type: 'body',
        parameters: [
          { type: 'text', text: 'Rahul' },
        ],
      },
    ],
  },
});

Bulk Media Messages

Send the same media to many recipients at once:

await api.post('/messages/send/bulk', {
  recipients: ['919876543210', '919876543211', '919876543212'],
  type: 'image',
  image: { link: 'https://yourcdn.com/sale-banner.jpg' },
  caption: 'Our biggest sale of the year — 50% off all products!',
});

Media Size & Format Tips

• Compress images before sending — smaller files deliver faster and reduce WhatsApp quota usage
• Use PDF for documents customers need to save (cleaner than images for invoices/tickets)
• MP4 H.264 for videos — other codecs may be re-encoded by WhatsApp and lose quality
• Media uploaded via URL must be publicly accessible without authentication headers

Error Handling

try {
  await api.post('/messages/send', payload);
} catch (err) {
  const msg = err.response?.data?.message || '';
  if (msg.includes('media')) {
    console.error('Media error — check URL accessibility or file format');
  } else if (err.response?.status === 413) {
    console.error('File too large — compress it and retry');
  }
}

Next Steps

• Webhook Setup — Know when your media was delivered
• Send Message API — Full API reference