@spec canonical_jid(conn(), String.t()) :: String.t()

Canonicalize jid to its phone-number identity.

WhatsApp's multi-device addresses a contact by either a LID (<n>@lid) or a phone number (<n>@s.whatsapp.net); the same person can appear under both. Amarula tracks the mapping internally — this is the public way to read it.

If jid is a LID with a known PN mapping, returns the equivalent <pn>@s.whatsapp.net (preserving any device suffix). Any other jid — an already-canonical PN, a group, or a LID we have no mapping for — is returned unchanged, so it's safe to call on every inbound jid.

Amarula.canonical_jid(conn, "111111111111111@lid")
#=> "5511999999999@s.whatsapp.net"   # if mapped

@spec connect(
  Amarula.Conn.t(),
  keyword()
) :: {:ok, conn()} | {:error, {:already_running, pid()}} | {:error, term()}

Start a built Amarula.Conn and begin connecting. Returns the running conn handle (a pid). Pair with new/1:

{:ok, pid} = Amarula.new(config) |> Amarula.connect()

Only one connection per profile may run at a time (within the registry's reach — one per node by default; see Amarula.ProfileRegistry). Connecting a profile that's already live returns {:error, {:already_running, pid}} — use whereis/1 to get the existing one.

opts:

• :parent_pid — process to receive {:whatsapp, ..} events (default: caller)
• :name — optional registered name for the connection

@spec connection_state(conn()) :: atom()

Current connection state (e.g. :disconnected, :connecting, :connected).

@spec disconnect(conn()) :: :ok | {:error, term()}

Close the connection's websocket without taking the supervision tree down. Pair with reconnect/1 to bring it back up; use stop/1 to release the profile entirely. Returns :ok | {:error, reason}.

@spec download_media(Amarula.Msg.t()) :: {:ok, binary()} | {:error, term()}

Download + decrypt an incoming media file. Inbound messages carry only media metadata (directPath/mediaKey), not the bytes — call this to fetch them lazily, passing a %Amarula.Msg{type: :media} (or its content.media struct

• kind). Returns {:ok, bytes} or {:error, reason} (:bad_mac on a failed integrity check).

  %Amarula.Msg{type: :media} = msg {:ok, bytes} = Amarula.download_media(msg)

@spec fetch_history(conn(), message_key(), integer(), non_neg_integer()) ::
  send_result()

Ask the phone for older history of a chat (a PEER_DATA_OPERATION on-demand request). oldest_key is the oldest message you already have, oldest_ts its millisecond timestamp, and count how many older messages to request. The history arrives asynchronously later via the normal :history_sync event. Returns {:ok, request_msg_id} or {:error, :not_authenticated}.

Fetch users' status/bio text. See Amarula.Contacts.fetch_status/2.

@spec group_accept_invite(conn(), String.t()) :: {:ok, String.t()} | {:error, term()}

Join a group by invite code. Returns the joined group's jid.

@spec group_create(conn(), String.t(), [String.t()]) ::
  {:ok, Amarula.Group.t()} | {:error, term()}

Create a group named subject with the given participant jids. Returns the new group's metadata.

@spec group_ephemeral(conn(), String.t(), non_neg_integer()) :: :ok | {:error, term()}

Toggle disappearing messages. 0 = off; otherwise seconds of expiration.

@spec group_invite_code(conn(), String.t()) :: {:ok, String.t()} | {:error, term()}

Fetch the group's invite code.

@spec group_invite_info(conn(), String.t()) ::
  {:ok, Amarula.Group.t()} | {:error, term()}

Look up group metadata from an invite code without joining.

@spec group_join_approval_mode(conn(), String.t(), :on | :off) ::
  :ok | {:error, term()}

Turn join-approval (admin approves joiners) :on/:off.

@spec group_leave(conn(), String.t()) :: :ok | {:error, term()}

Leave a group.

@spec group_member_add_mode(conn(), String.t(), :admin_add | :all_member_add) ::
  :ok | {:error, term()}

Who may add members: :admin_add (admins only) or :all_member_add.

@spec group_metadata(conn(), jid()) :: {:ok, Amarula.Group.t()} | {:error, term()}

Fetch a group's metadata (%Amarula.Group{}). group is an Address or jid.

@spec group_participants(
  conn(),
  String.t(),
  [String.t()],
  Amarula.Protocol.Groups.Ops.action()
) ::
  {:ok, [affected()]} | {:error, term()}

Add/remove/promote/demote participants. action is :add/:remove/:promote/ :demote. Returns the affected participants with per-jid status.

@spec group_request_update(conn(), String.t(), [String.t()], :approve | :reject) ::
  {:ok, [affected()]} | {:error, term()}

Approve/reject pending join requests for participants. action is :approve/:reject.

@spec group_requests(conn(), String.t()) :: {:ok, [map()]} | {:error, term()}

List pending join-approval requests (a list of attr maps).

@spec group_revoke_invite(conn(), String.t()) :: {:ok, String.t()} | {:error, term()}

Revoke + regenerate the group's invite code. Returns the new code.

@spec group_setting(conn(), String.t(), Amarula.Protocol.Groups.Ops.setting()) ::
  :ok | {:error, term()}

Change a group setting: :announcement/:not_announcement (only admins post), :locked/:unlocked (only admins edit info).

@spec group_update_description(conn(), String.t(), String.t() | nil) ::
  :ok | {:error, term()}

Set (or clear, with nil/"") a group's description.

@spec group_update_subject(conn(), String.t(), String.t()) :: :ok | {:error, term()}

Change a group's subject (title).

@spec list_groups(conn()) :: {:ok, [Amarula.Group.t()]} | {:error, term()}

List all groups we participate in ([%Amarula.Group{}]).

@spec list_profiles(
  Amarula.Storage.Scope.t()
  | Amarula.Conn.t()
  | {module(), keyword()}
  | keyword()
) ::
  {:ok, [Amarula.Storage.profile()]} | {:error, term()}

List every profile that has stored credentials in storage.

Takes a storage source rather than a live connection: a Amarula.Storage.Scope.t/0, a built %Amarula.Conn{} (use its scope), or a {adapter, opts} / bare-opts storage spec (the same value new/1 accepts as :storage). Returns the profile names that have a :creds entry — what you'd pass as :profile to reconnect.

Amarula.list_profiles(root: "./amarula_data")
#=> {:ok, [:primary, "work"]}

{:error, :not_supported} if the storage adapter can't enumerate profiles.

@spec list_profiles_with_metadata(
  Amarula.Storage.Scope.t()
  | Amarula.Conn.t()
  | {module(), keyword()}
  | keyword()
) :: {:ok, [Amarula.Storage.profile_info()]} | {:error, term()}

Like list_profiles/1, but each entry carries the logged-in identity read from that profile's stored creds — for building a friendlier account picker:

Amarula.list_profiles_with_metadata(root: "./amarula_data")
#=> {:ok, [%{profile: :primary, jid: "5511...@s.whatsapp.net",
#           lid: "12345@lid", name: "Alice"}]}

Costs one extra storage read per profile. name/jid/lid are nil for a profile that hasn't finished pairing. Accepts the same storage sources as list_profiles/1.

@spec mark_read(conn(), [String.t(), ...], jid(), jid() | nil) :: :ok

Send a read receipt for message_ids in chat jid (pass participant for a group sender). Marks those messages read on the sender's side.

@spec new(map()) :: Amarula.Conn.t()

Build a connection value (Amarula.Conn) from config, without starting it.

This is the start of the Req-style builder: attach plugins, then connect/2.

Amarula.new(%{profile: :primary})
|> MyPlugin.attach(opts)
|> Amarula.connect()

Connection/protocol defaults are filled in (see Amarula.Config), so config need only carry :profile (+ :auth and any overrides).

Offline (sandbox) mode

offline: true runs the connection with no socket: it never reaches WhatsApp, and every send_* short-circuits to {:ok, msg_id} without encrypting or emitting a frame. Combined with Amarula.Testing.deliver_* (which feeds synthetic inbound messages), this lets you run your bot end to end — receive a message, reply to it — with no real-world effect. See Amarula.Testing.

Check which phone numbers are on WhatsApp. See Amarula.Contacts.on_whatsapp/2.

@spec own_address(conn()) :: Amarula.Address.t()

This connection's own identity as an Amarula.Address — our phone-number address, carrying our companion device id (creds.me.id).

Total: before login (no identity yet) it returns Amarula.Address.empty/0, so you never have to nil-guard. own_address(conn).device is nil for the primary device / phone, or the linked-device number (e.g. 29) for a companion like this app.

Use it to detect messages this app/device itself sent — e.g. to ignore the agent's own self-chat sends and avoid a feedback loop. This does a call into the connection, and our own device is constant after login, so read it once and reuse the device:

own_device = Amarula.own_address(conn).device

# then, per received message:
if msg.from_me and msg.from.device == own_device do
  :ignore   # this device sent it
end

@spec own_chat?(conn(), Amarula.Msg.t()) :: boolean()

Whether msg is in our own chat (the "Message Yourself" chat): from_me and addressed to our own account. The check a self-chat command channel needs — drive an agent by messaging yourself.

Handles the LID/PN duality: the self chat may be addressed by our PN or our LID, so it matches msg.to against both of our own identities (see Amarula.Connection.own_chat?/2).

On a single connection there's no feedback loop — a reply this connection sends to the self chat is not delivered back to it (the sender's own device is excluded from delivery), so you don't need to filter your own sends. Dedupe by msg_id only when running two connections on the same account.

@spec presence_subscribe(conn(), jid()) :: :ok

Subscribe to a contact's presence updates.

Fetch a profile-picture URL. See Amarula.Profile.picture_url/3.

@spec reconnect(conn()) :: :ok | {:error, term()}

(Re)open the connection's websocket on an already-started connection — the inverse of disconnect/1. Runs the handshake and logs in again with the profile's stored credentials. Returns :ok | {:error, reason}.

Remove a profile picture. See Amarula.Profile.remove_picture/2.

@spec request_pairing_code(conn(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Request a link-code (phone-number) pairing code for phone (E.164 digits; any +, spaces, or dashes are stripped).

Call this during the QR window while unregistered — on the first :connection_update carrying a qr. Returns {:ok, code} with an 8-char code the user types into WhatsApp → Linked Devices → "Link with phone number". Amarula finishes the handshake internally; the usual 515 restart then logs in (watch for :pairing_success then connection: :open). The same code is also delivered as a :pairing_code event.

opts: :custom_code — a fixed 8-char code to use instead of a random one.

@spec request_resend(conn(), message_key()) :: send_result()

Ask the phone to re-deliver a message by key (a PEER_DATA_OPERATION placeholder-resend). The message arrives asynchronously later via the normal :messages_upsert event. Returns {:ok, request_msg_id}.

Resolve + persist a contact's LID↔PN mapping. See Amarula.Contacts.resolve_lid/2.

@spec resolve_quoted(conn(), Amarula.Msg.t()) ::
  {:ok, Amarula.Msg.t()} | {:requested, String.t()} | {:error, term()}

Resolve the original message a reply quotes.

1. If the reply carries the inline copy WhatsApp ships (msg.quoted.message), return it immediately — {:ok, %Amarula.Msg{}}.
2. Otherwise ask the server to re-deliver the original — {:requested, id}; it re-arrives async via :messages_upsert.

{:error, :not_a_reply} if msg doesn't quote anything.

Amarula does not keep an inbound-message store — delivery ends at :messages_upsert (the message, its mentions, and the inline quote are all there). If you want to resolve a quote from your own history, look it up in whatever store you keep and skip this; this function only handles the inline copy and the server round-trip.

@spec send_chatstate(conn(), jid(), :composing | :recording | :paused) :: :ok

Send a typing indicator to jid: :composing, :recording, or :paused.

@spec send_contact(conn(), jid(), String.t(), String.t()) :: send_result()

Send a contact (display_name + vCard string) to jid.

@spec send_contacts(conn(), jid(), String.t(), [{String.t(), String.t()}, ...]) ::
  send_result()

Send multiple contacts to jid: pairs is [{display_name, vcard}, ...].

@spec send_edit(conn(), message_key(), String.t()) :: send_result()

Edit a message we sent, replacing its text.

@spec send_location(conn(), jid(), float(), float(), keyword()) :: send_result()

Send a location to jid. opts: :name, :address, :url, :is_live.

@spec send_media(conn(), media_type(), jid(), binary(), keyword()) :: send_result()

Send media of type (:image/:video/:audio/:document/:sticker). opts may carry :mimetype, :caption, :width, :height, :seconds, :ptt, :file_name, :title.

@spec send_message(conn(), jid(), Amarula.Protocol.Proto.Message.t()) :: send_result()

Send a pre-built %Proto.Message{} to jid.

@spec send_poll(conn(), jid(), String.t(), [String.t(), ...], keyword()) ::
  {:ok, String.t(), binary()} | {:error, term()}

Send a poll to jid. Returns {:ok, msg_id, message_secret} — keep the message_secret to tally incoming votes (Amarula.Protocol.Messages.Poll). opts: :selectable (max picks, default 1), :announcement, :message_secret.

@spec send_reaction(conn(), message_key(), String.t()) :: send_result()

React to a message with emoji (empty string removes the reaction).

@spec send_revoke(conn(), message_key()) :: send_result()

Delete a message for everyone (revoke).

@spec send_text(conn(), jid(), String.t()) :: send_result()

Send a 1:1/group text message to jid.

@spec set_presence(conn(), :available | :unavailable) :: :ok | {:error, term()}

Set your global presence: :available (online) or :unavailable. Needs a profile name.

@spec stop(conn() | profile()) :: :ok | {:error, :not_found}

Stop a connection entirely — the whole supervision tree — and release its profile so it can be started again (here or, with a cluster registry, on another node).

Unlike disconnect/1 (which only closes the websocket; the supervised tree stays up and may reconnect), stop/1 takes the tree down and frees the profile slot. Accepts a connection pid or a profile (resolved via the default registry). Returns :ok | {:error, :not_found}.

Set a profile picture from JPEG bytes. See Amarula.Profile.update_picture/3.

Set your profile status/bio. See Amarula.Profile.update_status/2.

@spec via(profile()) :: {:via, module(), {atom(), profile()}}

A :via handle for profile — usable anywhere a conn() is accepted, so calls route to whatever pid currently holds the profile (restart-safe). Assumes the default registry; for a custom one, build it from the Conn via Amarula.ProfileRegistry.via/2.

@spec whereis(profile()) :: pid() | nil

The live connection pid for profile, or nil. A restart-safe handle: the pid changes if the connection restarts, but the profile resolves to the current one.

Assumes the default Amarula.ProfileRegistry. With a custom :registry config, pass the Conn (or config) as the first arg: whereis(conn, profile).

@spec whereis(Amarula.Conn.t() | map(), profile()) :: pid() | nil

As whereis/1, but resolves through conn_or_config's :registry.

@spec wipe_credentials(conn()) :: :ok | {:error, term()}

Destructively forget this connection's profile: unlink the companion on WhatsApp's side (the phone drops the device), wipe all local storage for it (creds, sessions, keys, mappings), then disconnect. After this the profile must be re-paired to use again.

For a non-destructive teardown that keeps the credentials, use disconnect/1 (websocket only) or stop/1 (the whole tree, freeing the profile slot).