WhatsApp Message Exporter & Backup API | Messages & Media

Export WhatsApp chat history including messages and media attachments (images, videos, audio, documents) in well structured JSON including full metadata.

Quick Start - QR Code Authentication

On first run, you need to link your WhatsApp account:

1. Start the Actor and watch the logs
2. A QR code will appear in the terminal
3. Open WhatsApp on your phone > Settings > Linked Devices > Link a Device
4. Scan the QR code
5. Wait for history sync to complete

Pricing

This Actor uses Pay-Per-Event pricing. You only pay for what you export.

Pricing Tiers

Item	Price	Example
Messages	$0.10 per 1,000	10,000 messages = $1.00
Standard media	$0.003 each	100 images = $0.30
Video media	$0.03 each	10 videos = $0.30

Standard media: images, audio, documents, stickers Video media: all video formats (10x cost due to bandwidth/storage)

Cost Examples

Export Type	Messages	Media	Est. Cost
Text only	5,000	0	$0.50
Full backup (small)	10,000	200 images, 5 videos	$1.75
Full backup (large)	50,000	1,000 mixed, 50 videos	$9.50

Budget Control

Set a spending limit in your run configuration to prevent unexpected charges. The Actor will:

1. Export all messages first (highest value)
2. Download media until budget is reached
3. Stop gracefully and report what was exported

You are only charged for media that was successfully downloaded. Failed or expired media downloads incur no charge.

Billing Notes

• Estimated cost shown in export summary is approximate
• See your Apify invoice for actual charges
• Each run is billed separately (no cross-run deduplication)
• Prices subject to change; Apify Console configuration is authoritative

Input Options

Field	Type	Default	Description
messageLimit	integer	unlimited	Maximum total messages to export (most recent N across all chats)
messagesPerChat	integer	unlimited	Maximum messages per chat (most recent N per chat)
chatFilter	string	all	Include only these types: all, groups, or private
dateRange	string	all	Time period to include (e.g. last 30 days only): all, 7d, 30d, 3m, 6m, 12m
includeStatus	boolean	true	Include viewed WhatsApp Status updates (stories)
downloadMedia	array	[]	Media types to download: images, videos, documents, audio, stickers
maxMediaAgeDays	integer	30	Only download media from messages newer than X days (older media usually fails anyway)
maxFileSizeMB	integer	100	Skip files larger than X MB to prevent memory issues
downloadConcurrency	integer	5	Parallel media downloads (1-10)

Input Examples

Full backup with all media

Export everything including all media types. Ideal for complete WhatsApp archive.

{
  "downloadMedia": ["images", "videos", "documents", "audio", "stickers"],
  "maxMediaAgeDays": 90
}

Quick text-only export

Fast export without media downloads. Perfect for searching messages or text analysis.

{
  "downloadMedia": [],
  "dateRange": "30d"
}

Group chats archive

Export only group conversations from the last month with images and documents.

{
  "chatFilter": "groups",
  "dateRange": "30d",
  "downloadMedia": ["images", "documents"]
}

Output Format

Each dataset item represents one chat.

Group chat example

{
  "chatId": "120363012345678901@g.us",
  "chatType": "group",
  "chatName": "Weekend Tennis Group",
  "participants": [
    "111111111111111@lid",
    "222222222222222@lid",
    "333333333333333@lid",
    "444444444444444@lid"
  ],
  "messages": [
    {
      "id": "3EB0B430F6A2CC7B4D12",
      "from": "111111111111111@lid",
      "fromMe": false,
      "timestamp": "2024-12-04T07:00:00.000Z",
      "type": "conversation",
      "text": "Anyone up for doubles this Saturday? 🎾"
    },
    {
      "id": "3EB0C12A5F3D88E9B721",
      "from": "222222222222222@lid",
      "fromMe": false,
      "timestamp": "2024-12-04T07:05:17.000Z",
      "type": "conversation",
      "text": "Count me in! Same time as usual?"
    }
  ],
  "messageCount": 32,
  "firstMessageAt": "2024-01-15T10:00:00.000Z",
  "lastMessageAt": "2024-12-04T07:05:17.000Z"
}

Private chat example

{
  "chatId": "14155552671@s.whatsapp.net",
  "chatType": "private",
  "chatName": "Sarah Miller",
  "participants": ["14155552671@s.whatsapp.net"],
  "messages": [
    {
      "id": "3A72D8F376325FFF1196",
      "from": "14155552671@s.whatsapp.net",
      "fromMe": false,
      "timestamp": "2024-12-01T10:00:00.000Z",
      "type": "conversation",
      "text": "Hey! Are we still on for coffee tomorrow? ☕"
    },
    {
      "id": "3AF5CE32D28203B61E70",
      "from": "14155552671@s.whatsapp.net",
      "fromMe": true,
      "timestamp": "2024-12-01T10:05:00.000Z",
      "type": "extendedText",
      "text": "Absolutely! I'll be there at 10am 👍",
      "quotedMessageId": "3A72D8F376325FFF1196"
    },
    {
      "id": "AC4B6BB2C6A6571D4E29",
      "from": "14155552671@s.whatsapp.net",
      "fromMe": true,
      "timestamp": "2024-12-01T10:10:00.000Z",
      "type": "image",
      "text": "Found this great spot downtown, check it out!",
      "media": {
        "type": "image",
        "mimetype": "image/jpeg",
        "fileSize": 302796,
        "width": 1204,
        "height": 1600,
        "downloadStatus": "downloaded",
        "url": "https://api.apify.com/v2/key-value-stores/.../records/media-AC4B6BB2.jpg"
      }
    },
    {
      "id": "AC3D32D2F6E890F62EB2",
      "from": "14155552671@s.whatsapp.net",
      "fromMe": false,
      "timestamp": "2024-10-15T12:00:00.000Z",
      "type": "document",
      "media": {
        "type": "document",
        "mimetype": "application/pdf",
        "fileSize": 160325,
        "fileName": "menu.pdf",
        "downloadStatus": "expired",
        "downloadErrorCode": 403,
        "downloadErrorMessage": "Media expired or removed from WhatsApp CDN"
      },
      "text": "Here's their menu, looks amazing 🍰"
    }
  ],
  "messageCount": 4,
  "firstMessageAt": "2024-10-15T12:00:00.000Z",
  "lastMessageAt": "2024-12-01T10:10:00.000Z"
}

Message types: conversation (plain text), extendedText (links or quoted replies), image, video, audio, document, sticker

Media download status: downloaded (success with URL), expired (CDN removed it), skipped_by_age, skipped_too_large, skipped_budget (budget limit reached)

Export Summary

The final dataset item is an export summary with billing information:

{
  "type": "export_summary",
  "exportedAt": "2024-12-04T10:30:00.000Z",
  "chatsProcessed": 45,
  "messagesExported": 12500,
  "mediaDownloaded": {
    "total": 380,
    "images": 320,
    "videos": 10,
    "audio": 25,
    "documents": 20,
    "stickers": 5
  },
  "mediaSkipped": {
    "total": 45,
    "budgetExhausted": 0,
    "expired": 30,
    "tooLarge": 5,
    "tooOld": 8,
    "failed": 2
  },
  "billing": {
    "messagesCharged": 12500,
    "mediaStandardCharged": 370,
    "mediaVideoCharged": 10,
    "estimatedCostUSD": "$2.66",
    "note": "Estimate only. See Apify invoice for actual charges."
  },
  "budgetExhausted": false
}

Media Download Limitations

WhatsApp does not permanently store media on their servers:

• Recent messages (< 2 weeks): ~95-100% download success
• Older messages (2-4 weeks): ~50-80% success
• Old messages (> 4 weeks): Low success rate

This is expected WhatsApp platform behavior, not a bug. Even when media can't be downloaded, you still get all metadata (filename, size, type). Use dateRange filter if you're primarily interested in media.

Data Privacy

All exported data (messages and media) is stored exclusively in the private Key-Value Store of your Actor run. This means:

• Only you have access to your exported data
• The Actor developer has no access to your private runs
• Data is automatically deleted according to your Apify plan's retention policy
• Media files are accessible only via authenticated URLs from your run

Your WhatsApp session credentials are also stored in a separate private Key-Value Store (whatsapp-auth), which persists across runs for convenience but remains private to your account.

Troubleshooting

"Not enough time remaining for sync" Increase the Actor timeout in run configuration. The Actor needs at least 2 minutes.

Media downloads failing Expected for messages older than ~30 days. The message metadata is still exported.

"Max reconnection attempts exceeded" WhatsApp servers are overloaded. Wait a few minutes and try again.

---

📧 Support

Questions or issues? Contact: max@mapa.slmail.me