# `ExWapp.Messages`
[🔗](https://github.com/elchemista/ex_wapp/blob/v0.1.5/lib/ex_wapp/messages.ex#L1)

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"
    )

# `send_opts`

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

# `build_audio_proto`

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

Builds an audio message protobuf from uploaded media metadata.

# `build_contact_proto`

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

Builds a single WhatsApp contact-card protobuf.

# `build_context_info`

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

Builds context info for replies and mentions.

# `build_document_proto`

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

Builds a document message protobuf from uploaded media metadata.

# `build_event_proto`

```elixir
@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`

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

Builds an image message protobuf from uploaded media metadata.

# `build_location_proto`

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

Builds a static or live GPS location protobuf.

# `build_message_node`

```elixir
@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`

```elixir
@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`

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

Builds a presence subscription request.

# `build_receipt_node`

```elixir
@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`

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

Builds a text message protobuf.

# `build_typing`

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

Builds a typing indicator node.

# `build_typing`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

Sends a read receipt for messages.

# `send_text`

```elixir
@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

---

*Consult [api-reference.md](api-reference.md) for complete listing*