Convert Media

Convert media files to WhatsApp-compatible formats (e.g., to OGG/Opus for voice notes).

POST

https://api.wawp.net/v2/media/convert?access_token=123456789&file=%7B%22url%22%3A%22https%3A%2F%2Fexample.com%2Faudio.mp3%22%2C%22filename%22%3A%22audio.mp3%22%2C%22mimetype%22%3A%22audio%2Fmpeg%22%7D&instance_id=123456789&outputFormat=ogg

Authentication Required

Test /v2/media/convert endpoint

Supports

POST

No query parameters required

This endpoint doesn't expect data in the URL.

File Limits

Check file size limits for different media types before uploading.

Mime Types

Ensure the correct MIME type is specified for the media file.

Best practices

Compress media files to save bandwidth and improve speed.
Use compatible formats (e.g., MP4 for video, JPEG/PNG for images).
Handle upload failures with retries.

The Transcoding Gateway: Architecting Format Fidelity for Global Mobile Distribution

In the heterogeneous world of digital media, "compatibility" is a moving target. For an enterprise handling millions of multi-format binary assets, the challenge is not just sending a file, but ensuring that the file is immediately consumable on any recipient device, regardless of their operating system or hardware age. The Media Convert endpoint is Wawp's specialized Transcoding Infrastructure, designed to bridge the gap between your raw business assets and WhatsApp's strict mobile-first requirements.

By acting as a real-time standardization layer, this endpoint transforms raw audio, video, and image signals into the exact bitrates, codecs, and containers optimized for the Meta network. This guide explores the strategic imperatives of media standardization and the architectural benefits of centralized transcoding.

🏗️ Architectural Philosophy: The Mandate of Standardization

To understand the necessity of the Media Convert API, one must first recognize the "Silent Rejection" problem in mobile messaging. If a business sends a high-bitrate .AVI file or an unoptimized .WAV through a WhatsApp channel, the recipient may receive the file, but their device may fail to play it natively, or it may appear as a "Generic Attachment" rather than an interactive media object.

1. Codec Optimization and the "Play-Ready" State

The Media Convert endpoint ensures that every asset is in a Play-Ready State.

Audio and the Opus Paradox: Standard MP3 files, while universal on the web, are handled by WhatsApp as "Audio Files." They appear with a generic icon and require the user to download them before playing. However, if that same audio is transcoded into the OGG container with the Opus codec, it is recognized by WhatsApp as a "Voice Note." This creates the signature blue-microphone experience, allowing for one-tap listening and variable-speed playback. The Media Convert API makes this transformation programmatic and effortless.
Video and Bitrate Balancing: Sending a 4K 60FPS video to a user on a low-end device or a limited data plan on the other side of the world often leads to a poor experience. The Transcoding Gateway applies "Strategic Compression," maintaining visual fidelity while optimizing file size for the rapid transit and display constraints of the mobile ecosystem.

2. Centralized vs. Distributed Transcoding

While a developer could manage their own FFmpeg cluster to handle these conversions, doing so introduces significant operational overhead, latency, and technical debt. Wawp's Media Convert API provides a Serverless Transcoding Layer. Your application simply provides a URL to the source media, and the API handles the compute-intensive task of re-encoding, returning a new, optimized binary URL ready for delivery. This allows your team to focus on business logic rather than binary mathematics.

🚀 Strategic Use Cases: Empowering Automated Media Flows

Centralized conversion is the "Secret Sauce" of premium automated customer experiences.

1. The "Human Bot" (Voice Note Automation)

Imagine a customer service bot that handles account inquiries. Instead of a text-only interaction, the bot responds with a voice message: "Hello! Your refund has been processed. Is there anything else I can help with today?" To achieve this, your system generates raw audio from a Text-to-Speech (TTS) engine, uses the Media Convert endpoint to standardize it into OGG/Opus, and delivers it as a native voice note. This adds a layer of empathy and personality to your automation that text alone cannot achieve.

2. Cross-Channel Content Synchronization

Your marketing team may produce high-quality videos for Instagram or YouTube. These videos are often high-resolution and high-bitrate. Before distributing these at scale through a WhatsApp Channel or a broadcast list, the Media Convert API can "Sandwich" them into a WhatsApp-compatible MP4 format. This ensures that every subscriber, from the latest iPhone user to a legacy Android user, sees the vision exactly as the creative team intended, with zero buffering or playback errors.

3. Safety and Sanitization through Transcoding

Malicious files are often disguised as media. By passing every user-uploaded image or document through a "Rounding" transcode process, you effectively "Sanitize" the file. The re-encoding process strips away non-essential metadata (EXIF data, potential macro-active code) and regenerates the binary from scratch. This creates a "Logical Firewall," ensuring that the files living in your enterprise storage are clean, standardized, and safe for your internal team to open.

🛡️ Administrative Mandate: Protecting the User Experience (UX)

Consistency is the cornerstone of brand trust. If your bot's media delivery is inconsistent—sometimes working, sometimes showing "Format not supported"—your users will lose confidence in the channel.

The "Frictionless Consumption" Guarantee

By religiously using the Media Convert endpoint for every outbound asset, you guarantee that your content is frictionless. You move the "Heavy Lifting" of compatibility from the user's phone (where battery life and data are precious) to the Wawp cloud. This respect for the user's resources is a subtle but powerful brand signal that separates enterprise-grade platforms from basic implementations.

Monitoring "Transcoding Velocity"

The Media Convert API should be integrated into your analytics dashboard. Track how long your average conversion takes. For time-sensitive alerts (like emergency updates or real-time news), use "Pre-transcoding"—prepare the WhatsApp-optimized version of an asset the moment it is uploaded to your CMS, so it is ready for instant delivery when the broadcast trigger is pulled.

🛡️ Operational Best Practices: Optimization and Resource Stewardship

The "Format First" Policy: Always check the source file's metadata before sending. If the file is already in a compatible format, skip the conversion to save time and resources. Use the Media Convert API only for "Legacy" or "High-Fidelity" sources that require standardization.
Caching Converted Assets: Media conversion is a deterministic operation. If you convert "WelcomeVideo.mov" into "WelcomeVideo.mp4" once, store that MP4 URL in your database. Do not re-convert the same asset for every user; reuse the cached version to minimize latency and costs.
Managing Aspect Ratios: WhatsApp favors certain aspect ratios for different UI elements (e.g., 1:1 for profile pictures, 9:16 for status updates). Use the "Orientation Aware" logic in your transcoding recipes to ensure your content is never stretched or distorted.

⚙️ Engineering Best Practices: The Validation Loop

Monitor Target MIME Types: Ensure you are requesting the correct output format for the intended message type. If you are sending a document, stick to PDF. If you are sending a voice note, always use OGG/Opus.
Handle Conversion Errors Gracefully: If a source file is corrupted or in an unsupported container (like an ancient .FLV), the conversion may fail. Your application should be prepared to "Fall back" to a lower-level document attachment or notify an administrator that the asset requires manual intervention.
Coordinate with Download Timings: Since the Media Convert API requires a public URL to the source, ensure your source server (e.g., S3) has granted appropriate "Read" permissions to the Wawp service. Use short-lived presigned URLs for security during the conversion transit.

🎯 Conclusion: Mastery of the Global Media Signal

The Media Convert endpoint is the "Translator" of your visual and auditory strategy. It bridge the gap between your enterprise content library and the diverse, global reality of the WhatsApp mobile network. By treating transcoding as a strategic prerequisite for engagement, you ensure that your brand's voice is always clear, your vision is always crisp, and your documents are always accessible. You move beyond "Hopeful Sending" and into the world of Engineered Compatibility, where every media interaction is a guaranteed win for the user's experience.

Request Parameters

Configure the parameters required to interact with this endpoint. All query and body arguments are listed below with their details.

Request Body

Sent as a JSON object

	`string`		Your unique WhatsApp Instance ID Example:
	`string`		Your API Access Token Example:
	`object`		File to convert (URL, filename, mimetype) Example:
	`string`		Desired output format (ogg, mp4, etc.) Example:

Request Samples

Use these ready-to-go code snippets to integrate our API into your project quickly and efficiently. Choose your preferred language and library.

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/media/convert";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "123456789"
6}).toString();
7const body = {
8  "file": {
9    "url": "https://example.com/audio.mp3",
10    "filename": "audio.mp3",
11    "mimetype": "audio/mpeg"
12  },
13  "outputFormat": "ogg"
14};
15
16fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
17  method: "POST",
18  headers: { "Content-Type": "application/json" },
19  body: JSON.stringify(body)
20})
21  .then(async (response) => {
22    if (response.ok) {
23      const data = await response.json();
24      console.log("Success:", data);
25      return data;
26    }
27    
28    // Error Handling
29    if (response.status === 400) {
30      console.error("Error 400: Bad Request - Missing Required Parameter(s)");
31    }
32    if (response.status === 400) {
33      console.error("Error 400: Bad Request (XML Format)");
34    }
35    if (response.status === 400) {
36      console.error("Error 400: Bad Request (Plain Text)");
37    }
38    if (response.status === 401) {
39      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
40    }
41    if (response.status === 401) {
42      console.error("Error 401: Unauthorized (XML Format)");
43    }
44    if (response.status === 404) {
45      console.error("Error 404: Not Found - Session Does Not Exist");
46    }
47    if (response.status === 404) {
48      console.error("Error 404: Not Found (XML Format)");
49    }
50    if (response.status === 500) {
51      console.error("Error 500: Internal Server Error - Unexpected Failure");
52    }
53    if (response.status === 500) {
54      console.error("Error 500: Internal Server Error (HTML)");
55    }
56    if (response.status === 502) {
57      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
58    }
59    if (response.status === 502) {
60      console.error("Error 502: Bad Gateway (XML Format)");
61    }
62
63    const errorText = await response.text();
64    console.error(`Error ${response.status}: ${errorText}`);
65  })
66  .catch((error) => console.error("Network Error:", error));

Interactive SamplesUTF-8

Ln 66, Col 1javascript

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Media converted successfully

4 Variants

Type:

Scenario:

application/json

string *

Example

{
"url": "https://wawp.net/media/converted.ogg",
"filename": "converted.ogg",
"mimetype": "audio/ogg; codecs=opus"
}

Bad Request - Missing Required Parameter(s)

3 Variants

Unauthorized - Invalid or Missing Access Token