PushX.Message (PushX v0.12.0)

A struct representing a push notification message.

Provides a builder API for constructing notifications with title, body, badge, sound, and custom data.

Examples

# Simple message
message = PushX.Message.new("Hello", "World")

# Builder pattern
message = PushX.Message.new()
  |> PushX.Message.title("Order Update")
  |> PushX.Message.body("Your order has been shipped!")
  |> PushX.Message.badge(1)
  |> PushX.Message.sound("default")
  |> PushX.Message.data(%{order_id: "12345"})

Summary

Functions

badge(message, badge)

Sets the badge count (iOS).

body(message, body)

Sets the body of the message.

category(message, category)

Sets the notification category (iOS).

collapse_key(message, key)

Sets the collapse key for message deduplication.

data(message, data)

Sets custom data payload.

image(message, image_url)

Sets the image URL for rich notifications.

new()

Creates a new empty message.

new(title, body)

Creates a new message with title and body.

priority(message, priority)

Sets the priority (:high or :normal).

put_data(message, key, value)

Adds a key-value pair to the data payload.

sound(message, sound)

Sets the notification sound.

thread_id(message, thread_id)

Sets the thread ID for notification grouping (iOS).

title(message, title)

Sets the title of the message.

to_apns_options(message)

Translates the message's delivery fields into APNS send options.

to_apns_payload(message)

Converts the message to an APNS payload map.

to_fcm_android(message)

Translates the message's delivery fields into an FCM android block.

to_fcm_payload(message)

Converts the message to an FCM payload map.

ttl(message, ttl)

Sets the TTL (time to live) in seconds.

Types

t()

@type t() :: %PushX.Message{
  badge: non_neg_integer() | nil,
  body: String.t() | nil,
  category: String.t() | nil,
  collapse_key: String.t() | nil,
  data: map(),
  image: String.t() | nil,
  priority: :high | :normal | nil,
  sound: String.t() | nil,
  thread_id: String.t() | nil,
  title: String.t() | nil,
  ttl: non_neg_integer() | nil
}

Functions

badge(message, badge)

@spec badge(t(), non_neg_integer()) :: t()

Sets the badge count (iOS).

body(message, body)

@spec body(t(), String.t()) :: t()

Sets the body of the message.

category(message, category)

@spec category(t(), String.t()) :: t()

Sets the notification category (iOS).

collapse_key(message, key)

@spec collapse_key(t(), String.t()) :: t()

Sets the collapse key for message deduplication.

data(message, data)

@spec data(t(), map()) :: t()

Sets custom data payload.

image(message, image_url)

@spec image(t(), String.t()) :: t()

Sets the image URL for rich notifications.

new()

@spec new() :: t()

Creates a new empty message.

Examples

iex> PushX.Message.new()
%PushX.Message{title: nil, body: nil, data: %{}, priority: nil}

new(title, body)

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

Creates a new message with title and body.

Examples

iex> PushX.Message.new("Hello", "World")
%PushX.Message{title: "Hello", body: "World", data: %{}, priority: nil}

priority(message, priority)

@spec priority(t(), :high | :normal) :: t()

Sets the priority (:high or :normal).

put_data(message, key, value)

@spec put_data(t(), atom() | String.t(), any()) :: t()

Adds a key-value pair to the data payload.

sound(message, sound)

@spec sound(t(), String.t()) :: t()

Sets the notification sound.

thread_id(message, thread_id)

@spec thread_id(t(), String.t()) :: t()

Sets the thread ID for notification grouping (iOS).

title(message, title)

@spec title(t(), String.t()) :: t()

Sets the title of the message.

to_apns_options(message)

@spec to_apns_options(t()) :: keyword()

Translates the message's delivery fields into APNS send options.

Returns a keyword list suitable for merging into the opts of PushX.APNS.send/3 — explicit call-site options take precedence.

priority: :high → priority: 10, priority: :normal → priority: 5
ttl (seconds from now) → expiration (absolute Unix timestamp; ttl: 0 maps to expiration: 0, APNS's "attempt once, don't store")
collapse_key → collapse_id

Examples

iex> PushX.Message.new("Hi", "There") |> PushX.Message.priority(:normal) |> PushX.Message.to_apns_options()
[priority: 5]

to_apns_payload(message)

@spec to_apns_payload(t()) :: map()

Converts the message to an APNS payload map.

Note: when the message has a title but no explicit sound, "default" is injected — a titled notification is assumed to be user-visible. To send a visible-but-silent notification, build the raw APNS payload map yourself (omit "sound") instead of using the Message builder.

to_fcm_android(message)

@spec to_fcm_android(t()) :: map() | nil

Translates the message's delivery fields into an FCM android block.

Returns nil when none of priority, ttl, or collapse_key are set.

Examples

iex> PushX.Message.new("Hi", "There") |> PushX.Message.ttl(3600) |> PushX.Message.to_fcm_android()
%{"ttl" => "3600s"}

iex> PushX.Message.new("Hi", "There") |> PushX.Message.to_fcm_android()
nil

to_fcm_payload(message)

@spec to_fcm_payload(t()) :: map()

Converts the message to an FCM payload map.

ttl(message, ttl)

@spec ttl(t(), non_neg_integer()) :: t()

Sets the TTL (time to live) in seconds.