Medya

Medya ile iki yönde çalışırsınız: göndereceğiniz dosyayı Meta'ya yüklersiniz ve müşterinizin gönderdiği dosyayı indirirsiniz. Bu iki işlem farklı kimlikler kullanır.

#Dosya yükleyin

Dosyayı herkese açık bir adreste yayınlamadan doğrudan Meta'ya yükleyin. İstek multipart/form-data olmalıdır.

curl -X POST https://api.verimerkezi.app/wa/media \
  -H "Authorization: Bearer $VM_API_KEY" \
  -F "phone_number_id=1234567890" \
  -F "[email protected]"

const yuklenen = await vm.uploadMedia('1234567890', './police.pdf');
console.log(yuklenen.media_id);

yuklenen = vm.upload_media('1234567890', './police.pdf')
print(yuklenen['media_id'])

<?php
$yuklenen = $vm->uploadMedia('1234567890', './police.pdf');
echo $yuklenen['media_id'];

{
  "ok": true,
  "media_id": "1075907555339682",
  "type": "document",
  "mime_type": "application/pdf",
  "file_size": 183421,
  "phone_number_id": "1234567890",
  "expires_at": "2026-11-09T09:00:00Z",
  "mode": "live"
}

Dönen kimliği 30 gün içinde gönderimde kullanın:

{
  "phone_number_id": "1234567890",
  "to": "905550000000",
  "type": "document",
  "document": { "id": "1075907555339682", "filename": "police.pdf" }
}

#Sınırlar

• Dosyanın gerçek içeriği denetlenir; uzantısı yanıltıcıysa 415 media_invalid_format döner.
• Sınırı aşan dosya 413 media_too_large döner.
• Yükleme, medya hız sayacında (dakikada 60) sayılır.
• Test anahtarıyla Meta'ya istek gitmez; test.media. önekli bir kimlik döner.

#Sesli not gönderin

Sesi WhatsApp sesli notu (mikrofon simgeli) olarak göndermek için dosya OGG/Opus olmalıdır:

{
  "phone_number_id": "1234567890",
  "to": "905550000000",
  "type": "audio",
  "audio": { "id": "1138345975302799", "voice": true }
}

voice alanını göndermezseniz .ogg/.opus ile biten bağlantılar ve Meta'da audio/ogg olarak kayıtlı medya otomatik sesli not olarak gider. MP3, M4A, AAC ve AMR normal ses dosyası olarak gider.

#Gelen medyayı indirin

Müşteri görsel, video, ses, belge ya da çıkartma gönderdiğinde dosya sizin için hemen depolanır ve message.received olayında data.media.media_id olarak bildirilir:

"media": {
  "media_id": 13109,
  "path": "wa-media/inbound/2026/10/kgI9iKVlvNw3yFpXrzNVL8w2T023kEaznP3z5NHD.jpeg"
}

path yalnız bilgi amaçlıdır; doğrudan istenemez. Dosyayı kimlikle indirin:

curl -L https://api.verimerkezi.app/wa/media/13109 \
  -H "Authorization: Bearer $VM_API_KEY" \
  -o gelen-gorsel.jpeg

const fs = require('fs');
await vm.downloadMedia(13109, fs.createWriteStream('gelen-gorsel.jpeg'));

vm.download_media(13109, 'gelen-gorsel.jpeg')

<?php
$vm->downloadMedia(13109, '/tmp/gelen-gorsel.jpeg');

• Gerekli kapsam: inbox:read ya da messages:read.
• Yalnız kendi hesabınızın medyasına erişirsiniz. Başka hesabın kimliği 404 media_not_found döner; kaydın varlığı bile sızdırılmaz.
• Dosya Meta'dan alınamadıysa media alanı { "error": "media_download_failed", "meta_media_id": "..." } biçiminde gelir; bu durumda indirilecek dosya yoktur.
• Medya dosyaları süresiz saklanır.

#Üstveri, büyük dosyalar ve önbellek

• GET /media/{media_id}?meta=1 dosya yerine boyut, tür ve SHA-256 bilgisini JSON olarak döndürür.
• HEAD /media/{media_id} dosyayı aktarmadan Content-Length verir.
• Range: bytes=0-1048575 başlığıyla parça parça indirin (206 Partial Content); yarıda kalan indirmeyi sürdürün.
• Yanıttaki ETag değerini If-None-Match ile gönderin; dosya değişmediyse 304 Not Modified döner.

#Medya kayıtlarını listeleyin

curl "https://api.verimerkezi.app/wa/media?source=inbound&kind=image&limit=50" \
  -H "Authorization: Bearer $VM_API_KEY"

source için inbound, outbound ya da echo; kind için image, video, document, audio, sticker kullanın. İmleç paging.next_cursor alanındadır.

Tüm alanlar: Medya referansı.