Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gateway.connexease.com/llms.txt

Use this file to discover all available pages before exploring further.

The media download endpoint is under active development and will be available soon. This page will be updated when the feature is released.
When a user sends you an image, voice note, document, or video, the webhook payload contains a media_id rather than the file itself. The Connexease Gateway provides a proxy endpoint that handles Meta authentication on your behalf — you call it with your API key and receive the binary file directly.

​
How It Works

​
Endpoint

GET https://api.gateway.connexease.com/v1/wa/media/{media_id}
​
Authorization
string
required
Your API key in Bearer pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx format.
​
media_id
string
required
The media ID from an incoming message webhook — e.g. image.id, audio.id, document.id.
​
phone_number_id
string
required
The Meta phone number ID that received the message. Found in value.metadata.phone_number_id of the incoming webhook payload. Used to look up the correct WABA credentials.
Response: Binary file content with the appropriate Content-Type header (e.g. image/jpeg, audio/ogg, application/pdf).

​
Example

async function downloadMedia(mediaId, phoneNumberId) {
  const res = await fetch(
    `https://api.gateway.connexease.com/v1/wa/media/${mediaId}?phone_number_id=${phoneNumberId}`,
    {
      headers: { 'Authorization': `Bearer ${process.env.CONNEXEASE_API_KEY}` }
    }
  );

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`${err.errors.code}: ${err.errors.description}`);
  }

  const mimeType = res.headers.get('content-type');
  const buffer = Buffer.from(await res.arrayBuffer());
  return { buffer, mimeType };
}

// Usage inside your webhook handler:
setImmediate(async () => {
  const value = body?.entry?.[0]?.changes?.[0]?.value;
  const msg = value?.messages?.[0];
  const phoneNumberId = value?.metadata?.phone_number_id;

  if (msg?.type === 'image') {
    const { buffer, mimeType } = await downloadMedia(msg.image.id, phoneNumberId);
    // Save to S3, disk, database, etc.
  }
});

​
Where to Find phone_number_id

The phone_number_id is in every incoming message webhook under value.metadata: 
{
  "entry": [{
    "changes": [{
      "value": {
        "metadata": {
          "phone_number_id": "PHONE_NUMBER_ID_123",
          "display_phone_number": "905321234567"
        },
        "messages": [{ "type": "image", "image": { "id": "MEDIA_ID_789" } }]
      }
    }]
  }]
}
Store the phone_number_id alongside the media_id when you receive the webhook so you have both values ready when you call the media endpoint.

​
Media ID Expiry

Media IDs expire after 30 days. Download and store the file on your own infrastructure promptly after receiving the webhook.

​
Supported Media Types

TypeFormatsMax Size
ImageJPEG, PNG5 MB
AudioMP3, AAC, AMR, OGG (Opus)16 MB
DocumentPDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT100 MB
VideoMP4, 3GPP16 MB
StickerWebP500 KB

​
Tips

Call this endpoint asynchronously — never block your webhook handler while downloading. Return HTTP 200 immediately and process media in a background job.
Media downloads do not count against your message send rate limit (80 req/s). A separate quota applies.