WhatsApp.Client (WhatsApp SDK v0.1.0)

WhatsApp API client. Holds credentials and executes requests.

Usage

# From application config (simplest)
client = WhatsApp.client()

# Explicit credentials
client = WhatsApp.client("access_token", phone_number_id: "12345")

# With options
client = WhatsApp.client("access_token",
  phone_number_id: "12345",
  business_account_id: "waba_67890",
  api_version: "v23.0",
  max_retries: 3
)

Summary

Types

t()

Functions

new()

Build a client from application config.

new(access_token, opts \\ [])

Build a client from an explicit access token and options.

request(client, method, path, opts \\ [])

Execute an API request.

request_url(client, url, opts \\ [])

Fetch an absolute URL directly (for pagination cursor URLs).

Types

t()

@type t() :: %WhatsApp.Client{
  access_token: String.t(),
  api_version: String.t(),
  app_secret: String.t() | nil,
  business_account_id: String.t() | nil,
  finch: atom(),
  max_retries: non_neg_integer(),
  open_timeout: pos_integer(),
  phone_number_id: String.t() | nil,
  read_timeout: pos_integer(),
  telemetry_enabled: boolean(),
  user_agent_extensions: [String.t()]
}

Functions

new()

@spec new() :: t()

Build a client from application config.

Reads the :whatsapp_sdk application environment for:

:access_token (required)
:phone_number_id
:business_account_id
:app_secret
:api_version
:max_retries
:open_timeout
:read_timeout
:finch

new(access_token, opts \\ [])

@spec new(
  String.t(),
  keyword()
) :: t()

Build a client from an explicit access token and options.

Options

:phone_number_id - WhatsApp phone number ID
:business_account_id - WhatsApp Business Account ID
:app_secret - Meta app secret for webhook verification
:api_version - API version prefix (default: "v23.0")
:max_retries - Max retry attempts (default: 0)
:open_timeout - Connection open timeout in ms (default: 30_000)
:read_timeout - Response read timeout in ms (default: 30_000)
:telemetry_enabled - Whether to emit telemetry events (default: true)
:finch - Finch instance name (default: WhatsApp.Finch)
:user_agent_extensions - Additional user-agent string segments

request(client, method, path, opts \\ [])

@spec request(t(), atom(), String.t(), keyword()) ::
  {:ok, map()} | {:ok, map(), WhatsApp.Response.t()} | {:error, term()}

Execute an API request.

Parameters

client - The client struct
method - HTTP method (:get, :post, :put, :delete, :patch)
path - URL path (e.g., "/v23.0/12345/messages")
opts - Request options:
- :json - Body to JSON-encode
- :multipart - Multipart form parts (list of Finch multipart tuples)
- :form - Form data to URL-encode
- :params - Query parameters (map or keyword list)
- :return_response - If true, return {:ok, data, %Response{}} instead of {:ok, data}
- :base_url - Override base URL (default: "https://graph.facebook.com")

Returns

{:ok, data} on success (2xx)
{:ok, data, %Response{}} on success when return_response: true
{:error, %{status: status, body: body}} on API error (4xx/5xx)
{:error, exception} on network/transport errors

request_url(client, url, opts \\ [])

@spec request_url(t(), String.t(), keyword()) ::
  {:ok, map()} | {:ok, map(), WhatsApp.Response.t()} | {:error, term()}

Fetch an absolute URL directly (for pagination cursor URLs).

Pagination cursors from the WhatsApp API return full URLs. This function requests those URLs directly without prepending the base URL.

Accepts the same options as request/4 except :base_url.