From a7f066b4922f8fa20b3dadc6d79b191b2d117414 Mon Sep 17 00:00:00 2001
From: Leandro Campos <leandro.campos@nvoip.com.br>
Date: Tue, 28 Jul 2026 15:20:59 -0300
Subject: [PATCH] feat: add WhatsApp BSUID recipient examples (NN-3681)

---
 README.md                                     |  8 +++++
 src/main/java/br/com/nvoip/examples/Main.java | 31 ++++++++++++++++++-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6165d28..e1a1556 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,14 @@ java -cp target/classes br.com.nvoip.examples.Main wa-list
 java -cp target/classes br.com.nvoip.examples.Main wa-send
 ```
 
+### Destinatário WhatsApp
+
+O exemplo mantém `NVOIP_WA_DESTINATION` para telefone. Para o contrato tipado,
+use `NVOIP_WA_RECIPIENT_TYPE=phone|bsuid|parent_bsuid` e
+`NVOIP_WA_RECIPIENT_VALUE`, sem `destination`. BSUID é opaco; não use
+`@username` nem o coloque em campo de telefone. Exemplos mascarados:
+`US.MASKED_BSUID_001` e `PARENT.MASKED_BSUID_001`.
+
 ## SDK web
 
 Para o fluxo de popup com telefone e código, use em conjunto o repositório `nvoip-web-sdk`. Este repo cobre o consumo server-side da API.
diff --git a/src/main/java/br/com/nvoip/examples/Main.java b/src/main/java/br/com/nvoip/examples/Main.java
index 6a7ecd8..0d18e48 100644
--- a/src/main/java/br/com/nvoip/examples/Main.java
+++ b/src/main/java/br/com/nvoip/examples/Main.java
@@ -85,10 +85,39 @@ private static String buildWhatsAppPayload() {
         String bodyVariables = firstNonBlank(System.getenv("NVOIP_WA_BODY_VARIABLES"), "[]");
         String headerVariables = firstNonBlank(System.getenv("NVOIP_WA_HEADER_VARIABLES"), "[]");
         String toFlow = firstNonBlank(System.getenv("NVOIP_WA_TO_FLOW"), "false");
+        String recipientType = firstNonBlank(System.getenv("NVOIP_WA_RECIPIENT_TYPE"), "").toLowerCase();
+        String recipientValue = firstNonBlank(System.getenv("NVOIP_WA_RECIPIENT_VALUE"), "");
+        String recipientJson;
+
+        if (recipientType.isBlank()) {
+            String destination = env("NVOIP_WA_DESTINATION");
+            if (!destination.matches("\\+?[0-9]{8,20}")) {
+                throw new IllegalArgumentException("NVOIP_WA_DESTINATION must be a phone number; use recipient for BSUID");
+            }
+            recipientJson = "\"destination\":\"" + escapeJson(destination) + "\"";
+        } else {
+            if (!recipientType.matches("phone|bsuid|parent_bsuid") || recipientValue.isBlank()) {
+                throw new IllegalArgumentException("NVOIP_WA_RECIPIENT_TYPE must be phone, bsuid or parent_bsuid and requires NVOIP_WA_RECIPIENT_VALUE");
+            }
+            if (recipientValue.startsWith("@")) {
+                throw new IllegalArgumentException("@username is not a WhatsApp recipient; use a BSUID or parent BSUID");
+            }
+            if (recipientType.equals("phone") && !recipientValue.matches("\\+?[0-9]{8,20}")) {
+                throw new IllegalArgumentException("A phone recipient must contain only an optional leading + and 8 to 20 digits");
+            }
+            if (!recipientType.equals("phone") && (recipientValue.matches(".*\\s+.*") || recipientValue.length() > 256)) {
+                throw new IllegalArgumentException("A BSUID must be an opaque value without whitespace (maximum 256 characters)");
+            }
+            if (Boolean.parseBoolean(toFlow) && !recipientType.equals("phone")) {
+                throw new IllegalArgumentException("WhatsApp Flow and attendance require a phone recipient");
+            }
+            recipientJson = "\"recipient\":{\"type\":\"" + recipientType + "\",\"value\":\""
+                + escapeJson(recipientValue) + "\"}";
+        }
 
         return "{"
             + "\"idTemplate\":\"" + escapeJson(env("NVOIP_WA_TEMPLATE_ID")) + "\","
-            + "\"destination\":\"" + escapeJson(env("NVOIP_WA_DESTINATION")) + "\","
+            + recipientJson + ","
             + "\"instance\":\"" + escapeJson(env("NVOIP_WA_INSTANCE")) + "\","
             + "\"language\":\"" + escapeJson(firstNonBlank(System.getenv("NVOIP_WA_LANGUAGE"), "pt_BR")) + "\","
             + "\"bodyVariables\":" + bodyVariables + ","