ExWapp.Messages (ExWapp v0.1.2)

Copy Markdown View Source

High-level helpers for constructing and sending WhatsApp messages.

This module handles:

  • Message ID generation
  • Message node construction
  • Protobuf payload encoding
  • Message routing (direct, group, broadcast)

Message Flow

1. User calls send_text/3
2. Message proto is built and encoded
3. Binary node is constructed with proper attributes
4. Signal encryption is applied (when implemented)
5. Node is sent via the connection

Example

# Simple text message
ExWapp.Messages.send_text(session, "1234567890@s.whatsapp.net", "Hello!")

# Reply to a message
ExWapp.Messages.send_text(session, jid, "Reply text",
  quoted_id: "ABC123",
  quoted_participant: "sender@s.whatsapp.net"
)

Summary

Types

send_opts()

Functions

build_audio_proto(upload, opts \\ [])

Builds an audio message protobuf from uploaded media metadata.

build_contact_proto(display_name, vcard, opts \\ [])

Builds a single WhatsApp contact-card protobuf.

build_context_info(opts)

Builds context info for replies and mentions.

build_document_proto(upload, opts \\ [])

Builds a document message protobuf from uploaded media metadata.

build_event_proto(name, start_time, opts \\ [])

Builds WhatsApp's calendar event message (E2E Message field 75).

build_image_proto(upload, opts \\ [])

Builds an image message protobuf from uploaded media metadata.

build_location_proto(latitude, longitude, opts \\ [])

Builds a static or live GPS location protobuf.

build_message_node(jid, message_id, payload, timestamp, opts \\ [])

Builds the binary XML node for a message.

build_placeholder_resend_proto(chat_jid, sender_jid, message_id, opts \\ [])

Builds a protocol message requesting resend of an unavailable placeholder.

build_presence_subscribe(jid)

Builds a presence subscription request.

build_receipt_node(jid, message_ids, type)

Builds a receipt node for read/played acknowledgments.

build_text_proto(text, opts \\ [])

Builds a text message protobuf.

build_typing(jid, composing \\ true)

Builds a typing indicator node.

build_typing(jid, from_jid, composing)

Builds a typing indicator node while preserving the legacy three-argument API. WhatsApp no longer accepts the local sender identity in chat-state attributes, so from_jid is intentionally ignored.

generate_id(own_jid \\ nil)

Generates a unique message ID matching whatsmeow/Baileys/whatsapp-rust format.

send_delivery_receipt(session, jid, message_id, participant \\ nil)

Sends a delivery receipt for a message.

send_read_receipt(session, jid, message_ids)

Sends a read receipt for messages.

send_text(session, jid, text, opts \\ [])

Sends a text message to a JID.

Types

send_opts()

@type send_opts() :: [
  quoted_id: String.t(),
  quoted_participant: String.t(),
  mentions: [String.t()]
]

Functions

build_audio_proto(upload, opts \\ [])

@spec build_audio_proto(
  ExWapp.Media.Upload.t(),
  keyword()
) :: WAWebProtobufsE2E.Message.t()

Builds an audio message protobuf from uploaded media metadata.

build_contact_proto(display_name, vcard, opts \\ [])

@spec build_contact_proto(String.t(), String.t(), keyword()) ::
  WAWebProtobufsE2E.Message.t()

Builds a single WhatsApp contact-card protobuf.

build_context_info(opts)

@spec build_context_info(keyword()) :: WAWebProtobufsE2E.ContextInfo.t() | nil

Builds context info for replies and mentions.

build_document_proto(upload, opts \\ [])

@spec build_document_proto(
  ExWapp.Media.Upload.t(),
  keyword()
) :: WAWebProtobufsE2E.Message.t()

Builds a document message protobuf from uploaded media metadata.

build_event_proto(name, start_time, opts \\ [])

@spec build_event_proto(String.t(), integer() | DateTime.t(), keyword()) ::
  WAWebProtobufsE2E.Message.t()

Builds WhatsApp's calendar event message (E2E Message field 75).

WhatsApp Web also attaches a 32-byte message secret to event messages; it is generated automatically unless :message_secret is supplied.

build_image_proto(upload, opts \\ [])

@spec build_image_proto(
  ExWapp.Media.Upload.t(),
  keyword()
) :: WAWebProtobufsE2E.Message.t()

Builds an image message protobuf from uploaded media metadata.

build_location_proto(latitude, longitude, opts \\ [])

@spec build_location_proto(number(), number(), keyword()) ::
  WAWebProtobufsE2E.Message.t()

Builds a static or live GPS location protobuf.

build_message_node(jid, message_id, payload, timestamp, opts \\ [])

@spec build_message_node(String.t(), String.t(), binary(), integer(), keyword()) ::
  ExWapp.Binary.Node.t()

Builds the binary XML node for a message.

build_placeholder_resend_proto(chat_jid, sender_jid, message_id, opts \\ [])

@spec build_placeholder_resend_proto(String.t(), String.t(), String.t(), keyword()) ::
  WAWebProtobufsE2E.Message.t()

Builds a protocol message requesting resend of an unavailable placeholder.

build_presence_subscribe(jid)

@spec build_presence_subscribe(String.t()) :: ExWapp.Binary.Node.t()

Builds a presence subscription request.

build_receipt_node(jid, message_ids, type)

@spec build_receipt_node(String.t(), [String.t()], String.t()) ::
  ExWapp.Binary.Node.t()

Builds a receipt node for read/played acknowledgments.

build_text_proto(text, opts \\ [])

@spec build_text_proto(String.t(), send_opts()) :: WAWebProtobufsE2E.Message.t()

Builds a text message protobuf.

build_typing(jid, composing \\ true)

@spec build_typing(String.t(), boolean()) :: ExWapp.Binary.Node.t()

Builds a typing indicator node.

build_typing(jid, from_jid, composing)

@spec build_typing(String.t(), String.t(), boolean()) :: ExWapp.Binary.Node.t()

Builds a typing indicator node while preserving the legacy three-argument API. WhatsApp no longer accepts the local sender identity in chat-state attributes, so from_jid is intentionally ignored.

generate_id(own_jid \\ nil)

@spec generate_id(String.t() | nil) :: String.t()

Generates a unique message ID matching whatsmeow/Baileys/whatsapp-rust format.

Format: "3EB0" + uppercase hex of SHA256(timestamp + ownJID@c.us + 16 random bytes)[:9] Total length: 22 characters (4 prefix + 18 hex).

send_delivery_receipt(session, jid, message_id, participant \\ nil)

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

Sends a delivery receipt for a message.

send_read_receipt(session, jid, message_ids)

@spec send_read_receipt(pid(), String.t(), [String.t()]) :: :ok | {:error, term()}

Sends a read receipt for messages.

send_text(session, jid, text, opts \\ [])

@spec send_text(pid(), String.t(), String.t(), send_opts()) ::
  {:ok, String.t()} | {:error, term()}

Sends a text message to a JID.

Options

  • :quoted_id - ID of message to reply to
  • :quoted_participant - JID of quoted message sender (for groups)
  • :mentions - List of JIDs to mention

Returns

  • {:ok, message_id} - Message was queued for sending
  • {:error, reason} - Failed to send