API Reference amarula v#0.4.5

Amarula — a WhatsApp Web client for Elixir.

A WhatsApp address — the consumer-facing way to name who/what a message is for or from. A friendly value you can build, inspect, and pass to sends, instead of juggling raw "user@server" jid strings.

Starts the library's process tree

Which upstream Baileys revision Amarula's port currently tracks.

A chat update derived from app-state sync — the consumer view of a mutation to a conversation. address is the chat (Amarula.Address: 1:1 or group); the other fields are the change carried by the mutation (nil = unchanged).

Connection config + the single source of truth for protocol/connection defaults.

A connection handle: everything Amarula knows about one connection, built once from its config at connect time and threaded through the protocol layer.

The per-connection process that owns the entire server conversation: the WebSocketClient, the noise cipher (frame encode/decode + counters), IQ correlation, login/handshake, send dispatch, and server-notification handling.

A contact update from app-state sync — the consumer view of a contactAction (a saved name) or the local push-name setting. address is the contact.

Contact discovery via USync. The consumer-facing half of Baileys' onWhatsApp / fetchStatus.

A received contact card (content of a %Amarula.Msg{type: :contact}, and each element of a :contacts array).

A received multi-contact card (content of a %Amarula.Msg{type: :contacts}).

A received message edit (content of a %Amarula.Msg{type: :edit}).

A received event (content of a %Amarula.Msg{type: :event}).

A received group-invite card (content of a %Amarula.Msg{type: :group_invite}) — a tap-to-join invite for a group.

A received keep-in-chat / undo (content of a %Amarula.Msg{type: :keep}).

The link-preview metadata a text message carries for a URL it contains — the title/description/thumbnail card WhatsApp shows under a link. Rides on an extendedTextMessage; a plain text message (or a reply/mention with no link) has none.

A received location (content of a %Amarula.Msg{type: :location}, and the :location of an event).

A received media attachment (content of a %Amarula.Msg{type: :media}) — an inbound image / video / audio / document / sticker. A plain snake_case struct, not the raw protobuf. Pass it (or the whole %Amarula.Msg{}) to Amarula.download_media/1 to fetch and decrypt the bytes — no live connection needed; the keys ride in this struct.

A received group member-label change (content of a %Amarula.Msg{type: :member_tag}).

An incoming interactive message that presents a set of choices — a list menu, a buttons message, a template-button message, or a native-flow interactive message. These are what WhatsApp Business / call-center / automated flows send to ask "pick one of these". A normal linked-device client can't send them, but it receives them; the user's reply comes back as an %Amarula.Content.Response{}.

A received order message (WhatsApp Business). Surfaces the few useful fields; for full detail read msg.raw.

A received pin / unpin (content of a %Amarula.Msg{type: :pin}).

A received poll (content of a %Amarula.Msg{type: :poll}).

A received poll vote (content of a %Amarula.Msg{type: :poll_vote}).

A received product message (WhatsApp Business). A linked-device client can receive these but not send them; this surfaces the few useful fields. For full catalog detail, read msg.raw.

A received control frame (content of a %Amarula.Msg{type: :protocol}) — a bare protocolMessage Amarula doesn't surface as a user message (ephemeral / setting changes and other unhandled types). Delivered on the :protocol_update event, not :messages_upsert.

A received reaction (content of a %Amarula.Msg{type: :reaction}).

A reply a user made to an interactive message — a button tap, list selection, template-button reply, or interactive response. Unified into one shape since they all share one shape: the user picked an option identified by id, shown as text.

A received delete-for-everyone (content of a %Amarula.Msg{type: :revoke}).

Group chats — the %Amarula.Group{} struct and every group operation.

A received message in consumer terms — the friendly view of a decrypted %Proto.Message{}. Delivered in {:amarula, :messages_upsert, %{messages: [%Msg{}]}}, so consumers never pattern-match the large WA protobuf.

Req-style plugin pipelines for a connection.

Example/reference plugin: a persistent message store.

Profile reads and writes: fetch a profile-picture URL, set/remove your (or a group's) picture, and set your status/bio. The consumer-facing half of Baileys' profilePictureUrl / updateProfilePicture / removeProfilePicture / updateProfileStatus.

The app-level profile -> Connection pid registry: the seam that enforces one connection per profile and lets a consumer refer to a connection by its :profile (restart-safe) rather than a raw pid.

Pluggable cache of recently-sent messages, so the library can re-encrypt and resend when a recipient asks for a retry (<receipt type="retry">).

On-disk Amarula.RetryCache adapter — survives restart.

In-memory Amarula.RetryCache adapter — the default.

A read-only Amarula.RetryCache adapter backed by your message store.

A retry-cache scope: the resolved adapter plus its state. Handed to a cache adapter (with the connection profile) on each call. Mirrors Amarula.Storage.Scope but for the separate retry-cache concern.

The built-in send-pipeline step that records each outgoing message in the Amarula.RetryCache, so it can be re-encrypted and resent if the recipient asks for a retry. Attached by default (see Amarula.Conn); a side-effect step that never transforms or halts.

Pluggable, connection-scoped persistence for a connection's protocol state.

Ergonomic base for writing an Amarula.Storage adapter.

DETS Amarula.Storage adapter for durable account state — a peer to Amarula.Storage.File.

Filesystem Amarula.Storage adapter — the default plugin.

A storage scope: the resolved adapter plus its per-connection state.

The process behind Amarula.child_spec/1 — a thin owner that ties one Amarula connection to your supervision tree, so a fixed set of (already-paired) profiles come up at boot.

:telemetry events emitted by Amarula — the operational-observability surface.

Test support for consumers of Amarula — drive your bot with synthetic inbound messages, with no WhatsApp connection.

Link (pair) a WhatsApp account to a named profile — by QR code or phone code.