WaitWhile Integration

Integration type: Inbound webhook receiver (WaitWhile → SMSDESK)

Endpoint: POST https://{host}/api/http/waitwhile/main.ashx?key={api_key}

How It Works

1. A customer joins a waitlist or books an appointment in WaitWhile
2. WaitWhile sends a webhook event to the SMSDESK endpoint
3. SMSDESK verifies the webhook signature using the client's API key as the secret
4. SMSDESK looks up the client (e.g., clinic name, SMS channel) using the API key
5. SMSDESK dispatches an SMS to the customer's phone number with relevant details

Prerequisites

• A SMSDESK account with an active SMS channel
• An API key generated from the SMSDESK portal (per client/user)
• A WaitWhile account with webhook configuration access
• The customer's phone number must be captured in WaitWhile for SMS to be sent

Webhook URL

Configure this URL in your WaitWhile webhook settings:

https://{host}/api/http/waitwhile/main.ashx?key={your_api_key}

Example URL

https://desk.sms.com.na/api/http/waitwhile/main.ashx?key=FLeJPVIDcmJB8coAb7xcnA7T

Authentication

Authentication is handled via the key query parameter in the webhook URL. This key is the SMSDESK API key stored in client_user.api_key for the specific client/user.

When a webhook event arrives:

1. SMSDESK extracts the key from the URL
2. Looks up the client in the database via the get-user backend endpoint
3. Retrieves clientid, client_name, channel, userid, and user_email
4. Uses the same API key as the HMAC-SHA256 secret for signature verification
5. Dispatches SMS using the client's configured channel

Signature Verification

WaitWhile signs each webhook request with an HMAC-SHA256 signature. SMSDESK verifies this signature to ensure the request is genuinely from WaitWhile.

Header

X-Waitwhile-Signature: Base64(HMAC-SHA256(secret, url + payload))

How It Works

• Secret: The SMSDESK API key (same value as the key query parameter)
• Message: The full request URL concatenated with the raw request body
• Algorithm: HMAC-SHA256, Base64-encoded

If the X-Waitwhile-Signature header is present but the signature doesn't match, the request is rejected with 401 Unauthorized. If the header is absent, the request is still processed (for testing purposes), but it's recommended to always enable signatures in WaitWhile.

Supported Events

SMSDESK processes the following WaitWhile webhook event types:

Visit States

WaitWhile visits can be in the following states:

• WAITING — Customer is in the queue
• SERVING — Customer's turn has arrived
• COMPLETE — Visit is finished
• BOOKED — Appointment is booked (for scheduled visits)

SMS Templates

SMS messages are dynamically generated using the client's name and visit data. The client name is fetched from the SMSDESK database — it is not hardcoded.

visit.created — Waitlist (state: WAITING)

Dear {customerName}, you have been added to the waitlist at {clientName}. Your ticket number is {ticket}. You are at position {position}. Estimated wait time: {waitMinutes} minutes. We will notify you when it's your turn. {clientName}.

visit.created — Booking (state: BOOKED)

Dear {customerName}, your appointment at {clientName} has been confirmed for {formattedDate}. Your booking reference is {ticket}. We look forward to seeing you. {clientName}.

visit.updated — State: SERVING

Dear {customerName}, it's now your turn at {clientName} (Ticket: {ticket}). Please proceed to the reception. {clientName}.

visit.updated — State: COMPLETE

Dear {customerName}, your visit at {clientName} is now complete. Thank you for your patience. For follow-up appointments, please contact us. {clientName}.

visit.removed — Cancellation

Dear {customerName}, your visit at {clientName} (Ticket: {ticket}) has been cancelled. Please contact us to reschedule if needed. {clientName}.

Response Format

All responses are JSON with Content-Type: application/json.

Success Response (200)

{
  "status": "ok",
  "eventType": "visit.created",
  "message": "SMS dispatched to 0812345678: OK:26514097:PENDING_ENROUTE"
}

Error Responses

Configure in WaitWhile

Step 1: Get Your SMSDESK API Key

1. Log in to your SMSDESK portal (e.g., https://{host}/portal/)
2. Navigate to your user settings or SMS channel settings
3. Copy your API key

Step 2: Set Up the Webhook in WaitWhile

1. Log in to your WaitWhile account
2. Go to Settings → Integrations → Webhooks
3. Click Add Webhook or New Webhook
4. Enter the webhook URL:

   https://{host}/api/http/waitwhile/main.ashx?key={your_api_key}

5. Set the webhook secret to your SMSDESK API key (same value as the key parameter)
6. Select the events to subscribe to:
   • visit.created — recommended
   • visit.updated — recommended
   • visit.removed — recommended
7. Save the webhook configuration

Step 3: Test the Webhook

1. In WaitWhile, use the "Send Test" or "Test Webhook" button if available
2. Alternatively, add a test visit to your waitlist with a real phone number
3. Check that an SMS is received on the test phone number

Configure in SMSDESK

No special configuration is required in SMSDESK beyond having:

• An active client account with a configured SMS channel
• A user with a valid API key in client_user.api_key
• The SMS channel must be active and have sufficient credits

The integration is fully dynamic — the client name, SMS channel, and user info are all looked up from the database at runtime using the API key. Multiple WaitWhile clients can use the same SMSDESK deployment with different API keys.

Testing

Manual Test with cURL

You can emulate a WaitWhile webhook event to test the integration:

curl -X POST \
  "https://{host}/api/http/waitwhile/main.ashx?key={your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "evt_test_001",
    "type": "visit.created",
    "data": {
      "id": "visit_001",
      "state": "WAITING",
      "firstName": "Test",
      "lastName": "User",
      "phone": "0812345678",
      "name": "Test User",
      "ticket": "A001",
      "position": 5,
      "estWaitDuration": 368
    }
  }'

Expected Response

{
  "status": "ok",
  "eventType": "visit.created",
  "message": "SMS dispatched to 0812345678: OK:26514097:PENDING_ENROUTE"
}

Testing with Signature

To test with signature verification, compute the HMAC-SHA256 of url + payload using your API key as the secret:

# Python example
import hmac, hashlib, base64, urllib.request, json

api_key = "your-api-key"
url = "https://{host}/api/http/waitwhile/main.ashx?key=" + api_key
payload = json.dumps({
    "id": "evt_test_001",
    "type": "visit.created",
    "data": {
        "state": "WAITING",
        "firstName": "Test",
        "lastName": "User",
        "phone": "0812345678",
        "ticket": "A001",
        "position": 5,
        "estWaitDuration": 368
    }
})

signature = base64.b64encode(
    hmac.new(api_key.encode(), (url + payload).encode(), hashlib.sha256).digest()
).decode()

req = urllib.request.Request(url, data=payload.encode(), method="POST")
req.add_header("Content-Type", "application/json")
req.add_header("X-Waitwhile-Signature", signature)
response = urllib.request.urlopen(req)
print(response.read().decode())

Troubleshooting

No SMS Received

• Check phone number: The phone field in the WaitWhile event must not be empty. If no phone is recorded, SMS is skipped.
• Check API key: Ensure the API key in the webhook URL matches a valid client_user.api_key in the database.
• Check SMS credits: The client's SMS channel must have sufficient credits.
• Check logs: Webhook events are logged to ~/logs/waitwhile.{date}.log on the SMSDESK server.

401 Unauthorized — invalid_signature

• Ensure the webhook secret in WaitWhile is set to the same value as the API key in the URL
• The signature is computed as Base64(HMAC-SHA256(secret, url + payload)) where url is the full request URL including query string

401 Unauthorized — invalid_api_key

• The API key was not found in client_user.api_key
• Verify the key is correctly copied — no trailing spaces or encoding issues

SMS Sent But Not Delivered

• Check the SMS status in the SMSDESK portal
• Verify the phone number format is valid for the mobile network
• The response message includes the SMS ID and status for tracking

References & Official Documentation

• WaitWhile Webhooks Documentation — official guide to setting up webhooks in WaitWhile
• WaitWhile API Reference — full REST API documentation
• WaitWhile Event Types — complete list of webhook event types and data schemas
• SMSDESK Custom Integrations — overview of all platform-specific integrations
• SMSDESK SMS API v2 — the modern REST API for sending SMS