Ask Button Node (Interactive Quick Replies)

Documentation for the Ask Button node in the SMSPort Visual Bot Builder. Learn how to send native WhatsApp quick reply buttons and capture the customer's selection.

The Ask Button card dispatches a native WhatsApp interactive message containing up to 3 clickable buttons. When the user taps a button, their choice is immediately transmitted back to the bot engine as an interactive selection and stored in memory.

Meta WhatsApp Cloud API Specifications & Limitations

[!IMPORTANT]
Meta enforces strict constraints on Interactive Quick Reply buttons:

Maximum Buttons: Exactly 1 to 3 buttons. (If you need 4 to 10 choices, use the Ask List Node).

Character Limit: Each button title must NOT exceed 20 characters. Longer titles will fail Meta validation with API error 100.

No URL Buttons: Quick reply buttons in conversational flows transmit text back to the bot. (For external website links, use Send Template).

Inspector Screen: Field-by-Field Guide

When you select an Ask Button node on the visual canvas, the property inspector provides:

1. Header Text (Optional)

Label on Screen: Header Text
What to Fill: Optional bold text displayed above the body message (e.g. Appointment Booking or Urgent Notice). Max 60 characters.

2. Message Body (`message`)

Label on Screen: Prompt / Body Text
Required: Yes
What to Fill: The primary question displayed to the customer.
Example: "Hello {{patient_name}}! Would you like to schedule an in-clinic consultation or an online tele-health call?"

3. Footer Text (Optional)

Label on Screen: Footer Text
What to Fill: Muted small text displayed beneath the buttons (e.g. Reply STOP to unsubscribe).

4. Buttons List (`options[]`)

Click + Add Button (Max 3).
Button 1: In-Clinic Visit (15 chars — valid)
Button 2: Video Call (10 chars — valid)
Button 3: Reschedule (11 chars — valid)

5. Output Variable (`outputVariable`)

Label on Screen: Store Choice In Variable
Default: user_choice
What to Fill: The variable name that subsequent cards can inspect (e.g. consultation_type).

Branching & Downstream Connections

The Ask Button card provides two wiring patterns:

Option-Specific Handles: Each button generates an output wire on the canvas:
- Wire option_In-Clinic Visit directly to Clinic Location card.
- Wire option_Video Call directly to Video Payment card.
Unified Output Handle: If you connect the main next handle, the selected button text is saved into {{consultation_type}} and you can evaluate it with a downstream Switch Node.

Practical Example: Clinic Confirmation Flow

graph TD
    Trigger([Reminder Scheduled]) --> AskBtn[Ask Button: Confirm Appointment?]
    AskBtn -->|Confirm| SendConfirmed[Send Text: Thank you! Your slot is confirmed.]
    AskBtn -->|Reschedule| FlowResched[Send WhatsApp Flow: Select New Date]
    AskBtn -->|Cancel| Handoff[Human Handoff: Desk clerk notified]

Ask Button Node Configuration:
- Body: "Reminder: You have an appointment with Dr. Sharma tomorrow at 10:00 AM. Please confirm your attendance:"
- Button 1: Confirm
- Button 2: Reschedule
- Button 3: Cancel
Handle Mapping:
- Connect Confirm -> Send Text
- Connect Reschedule -> Send WhatsApp Flow
- Connect Cancel -> Human Handoff

Common Issues & Troubleshooting

1. "Message failed with error: Param text must not exceed 20 characters"

Cause: One of your button labels has 21 or more characters (e.g. Book Teleconsultation = 21 chars).
Fix: Shorten the button title to 20 chars or fewer (e.g. Book Online Call = 16 chars).

2. "Customer typed text instead of pressing a button"

Behavior: If the customer manually types a message instead of tapping a button, SMSPort captures their typed text and stores it in the output variable.
Tip: Connect a Condition Node downstream to check if the input matches one of your expected button values.