Class: Whatsapp::Media

Inherits:
Object
  • Object
show all
Includes:
ResponseHandling
Defined in:
lib/ruby/whatsapp/media.rb

Overview

Media class for uploading, retrieving, downloading, and deleting media assets. Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media

Defined Under Namespace

Classes: MediaError

Constant Summary

Constants included from ResponseHandling

ResponseHandling::MAX_ERROR_BODY

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client: Client.new, media_host_allowlist: Whatsapp.configuration.media_host_allowlist) ⇒ Media

Returns a new instance of Media.

Parameters:

  • client (Whatsapp::Client) (defaults to: Client.new) —

    The WhatsApp client instance

  • media_host_allowlist (Array<String>) (defaults to: Whatsapp.configuration.media_host_allowlist) —

    Hosts allowed to receive the bearer token during downloads (defaults to the global configuration).



18
19
20
21
 
# File 'lib/ruby/whatsapp/media.rb', line 18

def initialize(client: Client.new, media_host_allowlist: Whatsapp.configuration.media_host_allowlist)
  @client = client
  @media_host_allowlist = media_host_allowlist
end

Instance Attribute Details

#client ⇒ Whatsapp::Client

Returns:



13
14
15
 
# File 'lib/ruby/whatsapp/media.rb', line 13

def client
  @client
end

Instance Method Details

#delete(media_id:) ⇒ Boolean

Deletes a media asset.

Parameters:

  • media_id (String) —

    The media ID

Returns:

  • (Boolean) —

    true if successful

Raises:



82
83
84
85
86
87
88
89
90
 
# File 'lib/ruby/whatsapp/media.rb', line 82

def delete(media_id:)
  response = client.connection.delete(
    client.path_for(media_id),
    params: { phone_number_id: client.phone_id }
  )

  parsed = parse_json(handle_response!(response, error_class: MediaError, action: "delete media"))
  parsed.is_a?(Hash) && parsed["success"] == true
end

#download(url:, save_to:) ⇒ String

Downloads media from a media URL.

The bearer token is attached to the request, so the URL is validated first: it must be HTTPS and its host must be on the allowlist. This prevents the token being sent to an attacker-influenced URL (media URLs commonly arrive from inbound webhooks).

Parameters:

  • url (String) —

    The media URL (valid for 5 minutes)

  • save_to (String) —

    Path where to save the downloaded file

Returns:

  • (String) —

    Path to the saved file

Raises:

  • (MediaError) —

    if the URL is untrusted or the download fails



65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/ruby/whatsapp/media.rb', line 65

def download(url:, save_to:)
  uri = parse_download_url(url)

  response = HTTP.timeout(Client::DEFAULT_TIMEOUT)
    .auth("Bearer #{client.api_key}")
    .get(uri.to_s)

  handle_response!(response, error_class: MediaError, action: "download media")
  stream_to_file(response, save_to)

  save_to
end

#get_url(media_id:) ⇒ Hash

Retrieves the URL for a media asset.

Parameters:

  • media_id (String) —

    The media ID

Returns:

  • (Hash) —

    Hash containing url, mime_type, sha256, file_size, and id

Raises:



46
47
48
49
50
51
52
53
 
# File 'lib/ruby/whatsapp/media.rb', line 46

def get_url(media_id:)
  response = client.connection.get(
    client.path_for(media_id),
    params: { phone_number_id: client.phone_id }
  )

  parse_json(handle_response!(response, error_class: MediaError, action: "get media URL"))
end

#upload(file_path:, type:) ⇒ String

Uploads a media file to WhatsApp.

Parameters:

  • file_path (String) —

    Path to the file to upload

  • type (String) —

    MIME type of the file (e.g., "image/jpeg", "video/mp4")

Returns:

  • (String) —

    The media ID

Raises:

  • (MediaError) —

    if the file is missing or the upload fails



28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/ruby/whatsapp/media.rb', line 28

def upload(file_path:, type:)
  raise MediaError, "File not found: #{file_path}" unless File.exist?(file_path)

  response = client.connection.post(
    client.path_for(client.phone_id, "media"),
    form: {
      messaging_product: "whatsapp",
      file: HTTP::FormData::File.new(file_path, content_type: type),
    }
  )

  parse_json(handle_response!(response, error_class: MediaError, action: "upload media"))["id"]
end