Add comprehensive Webex Interact parser guide

- Detailed documentation for all 7 event types - Configuration instructions - Testing examples with cURL - Email organization tips - Troubleshooting section - Links to official API documentation
2026-01-22 16:58:40 +00:00
parent 1d336e4cac
commit 2a45e6430c
1 changed files with 380 additions and 0 deletions
@@ -0,0 +1,380 @@
 # Webex Interact Webhook Parser Guide
 ## Overview
 The Webex Interact parser (`/wxinteract`) formats SMS API webhook events from Webex Interact into clean, readable HTML emails. Each event type gets custom formatting with relevant emojis for easy identification.
 ## Configuration
 ### URL Format
 ```
 https://your-domain.com/{your-email}/wxinteract
 ```
 ### Example
 ```
 https://webhooks.dixon.cx/sms-notifications%40mycompany.com/wxinteract
 ```
 ## Supported Events
 The parser automatically detects the event type based on the `data.status` field in the webhook payload.
 ### 📤 Outbound SMS - Submitted
 **Status:** `submitted`
 Triggered when an SMS message is submitted to the carrier for delivery.
 **Fields displayed:**
 - Message ID
 - To (recipient phone number)
 - From (sender phone number)
 - Campaign ID
 - Submitted At (timestamp)
 - Message Content (formatted in a clean message box)
 **Example payload:**
 ```json
 {
  "data": {
    "status": "submitted",
    "message_id": "msg_123456789",
    "to": "+61412345678",
    "from": "+61387654321",
    "message": "Hello! Your appointment is confirmed for tomorrow at 2 PM.",
    "submitted_at": "2026-01-22T16:45:00Z",
    "campaign_id": "camp_987654321"
  }
 }
 ```
 ---
 ### ✅ Outbound SMS - Delivered
 **Status:** `delivered`
 Triggered when an SMS message is successfully delivered to the recipient.
 **Fields displayed:**
 - Message ID
 - To (recipient phone number)
 - From (sender phone number)
 - Campaign ID
 - Delivered At (timestamp)
 **Example payload:**
 ```json
 {
  "data": {
    "status": "delivered",
    "message_id": "msg_123456789",
    "to": "+61412345678",
    "from": "+61387654321",
    "delivered_at": "2026-01-22T16:46:15Z",
    "campaign_id": "camp_987654321"
  }
 }
 ```
 ---
 ### ❌ Outbound SMS - Failed
 **Status:** `failed`
 Triggered when an SMS message fails to deliver.
 **Fields displayed:**
 - Message ID
 - To (recipient phone number)
 - From (sender phone number)
 - Campaign ID
 - Failed At (timestamp)
 - Error Code (highlighted in error box)
 - Error Message (highlighted in error box)
 **Example payload:**
 ```json
 {
  "data": {
    "status": "failed",
    "message_id": "msg_987654321",
    "to": "+61499999999",
    "from": "+61387654321",
    "failed_at": "2026-01-22T16:47:00Z",
    "error_code": "ERR_INVALID_NUMBER",
    "error_message": "The destination number is invalid or not reachable",
    "campaign_id": "camp_987654321"
  }
 }
 ```
 ---
 ### 🔗 Shortlink Clicked
 **Status:** `shortlink_clicked`
 Triggered when a recipient clicks a tracked shortlink in an SMS message.
 **Fields displayed:**
 - Shortlink (clickable)
 - Original URL (clickable)
 - Phone Number (recipient who clicked)
 - Message ID
 - Campaign ID
 - Clicked At (timestamp)
 - IP Address (of the click)
 - User Agent (browser/device information)
 **Example payload:**
 ```json
 {
  "data": {
    "status": "shortlink_clicked",
    "shortlink": "https://wxint.co/abc123",
    "original_url": "https://example.com/special-offer",
    "clicked_at": "2026-01-22T17:30:45Z",
    "phone_number": "+61412345678",
    "message_id": "msg_123456789",
    "campaign_id": "camp_987654321",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15",
    "ip_address": "203.0.113.45"
  }
 }
 ```
 ---
 ### 📥 Inbound SMS Received
 **Status:** `received`
 Triggered when an inbound SMS is received from a recipient.
 **Fields displayed:**
 - Message ID
 - From (sender phone number)
 - To (your phone number)
 - Keyword (detected keyword)
 - Received At (timestamp)
 - Message Content (formatted in a clean message box)
 **Example payload:**
 ```json
 {
  "data": {
    "status": "received",
    "message_id": "msg_inbound_001",
    "from": "+61412345678",
    "to": "+61387654321",
    "message": "YES I would like to receive updates",
    "received_at": "2026-01-22T18:00:00Z",
    "keyword": "YES"
  }
 }
 ```
 ---
 ### 🚫 SMS Opt Out Received
 **Status:** `opt_out`
 Triggered when a recipient opts out of receiving SMS messages (typically by replying "STOP").
 **Fields displayed:**
 - Phone Number (who opted out)
 - From Number (your SMS number)
 - Keyword (e.g., "STOP")
 - Message ID
 - Opt Out At (timestamp)
 **Example payload:**
 ```json
 {
  "data": {
    "status": "opt_out",
    "phone_number": "+61412345678",
    "opt_out_at": "2026-01-22T18:15:00Z",
    "keyword": "STOP",
    "message_id": "msg_optout_001",
    "from": "+61387654321"
  }
 }
 ```
 ---
 ### 👤 Contacts Callback
 **Status:** `contact_created` or `contact_updated`
 Triggered when a contact is created or updated in your Webex Interact account.
 **Fields displayed:**
 - Contact ID
 - Phone Number
 - First Name
 - Last Name
 - Email
 - Status
 - Created At (timestamp)
 - Updated At (timestamp)
 - Custom Fields (if present, displayed in a separate section)
 **Example payload:**
 ```json
 {
  "data": {
    "status": "contact_created",
    "contact_id": "contact_abc123",
    "phone_number": "+61412345678",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "created_at": "2026-01-22T19:00:00Z",
    "updated_at": "2026-01-22T19:00:00Z",
    "custom_fields": {
      "company": "Acme Corporation",
      "department": "Sales",
      "customer_id": "CUST_12345"
    }
  }
 }
 ```
 ---
 ## Testing
 ### Using cURL
 Test individual event types using the sample payloads:
 ```bash
 # Test Outbound SMS Submitted
 curl -X POST https://your-domain.com/test%40example.com/wxinteract \
  -H "Content-Type: application/json" \
  -d '{"data": {"status": "submitted", "message_id": "msg_123", "to": "+61412345678", "from": "+61387654321", "message": "Test message", "submitted_at": "2026-01-22T16:45:00Z", "campaign_id": "camp_001"}}'
 # Test SMS Opt Out
 curl -X POST https://your-domain.com/test%40example.com/wxinteract \
  -H "Content-Type: application/json" \
  -d '{"data": {"status": "opt_out", "phone_number": "+61412345678", "opt_out_at": "2026-01-22T18:15:00Z", "keyword": "STOP", "message_id": "msg_005", "from": "+61387654321"}}'
 ```
 ### Using Test Samples
 A complete set of test samples for all event types is available in `wxinteract_test_samples.json`.
 ```bash
 # Test with submitted event
 cat wxinteract_test_samples.json | jq '.outbound_sms_submitted' | \
  curl -X POST https://your-domain.com/test%40example.com/wxinteract \
    -H "Content-Type: application/json" \
    -d @-
 ```
 ---
 ## Configuring in Webex Interact
 ### Step 1: Log in to Webex Interact
 Go to your Webex Interact dashboard at https://interact.webex.com/
 ### Step 2: Navigate to API Settings
 1. Click on **Settings** or **API** in the navigation menu
 2. Look for **Webhooks** or **API Callbacks** section
 ### Step 3: Configure Callback URL
 1. Enter your webhook URL: `https://your-domain.com/{your-email}/wxinteract`
 2. Select the events you want to receive:
   - ☑️ Outbound SMS - Submitted
   - ☑️ Outbound SMS - Delivered
   - ☑️ Outbound SMS - Failed
   - ☑️ Shortlink Clicked
   - ☑️ Inbound SMS Received
   - ☑️ SMS Opt Out Received
   - ☑️ Contacts Callback
 3. Save your configuration
 ### Step 4: Test the Integration
 1. Send a test SMS from Webex Interact
 2. Check your email inbox for the formatted webhook notification
 3. Verify the email contains the correct information
 ---
 ## Email Organization Tips
 ### Create Email Filters
 Set up filters based on the subject line patterns:
 - **All Webex Interact webhooks:** Subject contains "Webex Interact"
 - **Failed messages only:** Subject contains "❌ Webex Interact: Outbound SMS - Failed"
 - **Opt-outs only:** Subject contains "🚫 Webex Interact: SMS Opt Out"
 - **Click tracking:** Subject contains "🔗 Webex Interact: Shortlink Clicked"
 ### Use Plus Addressing
 Track different campaigns or environments:
 - Production: `sms-prod%40mycompany.com`
 - Staging: `sms-staging%40mycompany.com`
 - Campaign A: `sms+campaignA%40mycompany.com`
 ---
 ## Troubleshooting
 ### Parser Not Working
 If you're receiving raw webhook data instead of formatted emails:
 1. **Check URL:** Ensure `/wxinteract` is at the end of the URL
 2. **Check payload structure:** Parser expects `{"data": {"status": "...", ...}}`
 3. **Check PHP logs:** Look for any parser errors in your server logs
 ### Missing Fields
 If some fields are showing as "N/A":
 - The webhook payload may not include those fields for that event type
 - Check the Webex Interact documentation for the specific event
 - Use the raw webhook format (without `/wxinteract`) to see the complete payload
 ### Wrong Event Type
 If the event is being parsed as a generic event:
 - Check that `data.status` matches one of the supported values
 - Supported values: `submitted`, `delivered`, `failed`, `shortlink_clicked`, `received`, `opt_out`, `contact_created`, `contact_updated`
 ---
 ## API Documentation References
 Official Webex Interact webhook documentation:
 - [Outbound SMS - Submitted](https://docs.webexinteract.com/reference/sms-api-request-accepted)
 - [Outbound SMS - Delivered](https://docs.webexinteract.com/reference/outbound-sms-delivered)
 - [Outbound SMS - Failed](https://docs.webexinteract.com/reference/outbound-sms-failed)
 - [Shortlink Clicked](https://docs.webexinteract.com/reference/shortlink-clicked)
 - [Inbound SMS Events](https://docs.webexinteract.com/reference/inbound-sms-events)
 - [SMS Opt Out Received](https://docs.webexinteract.com/reference/sms-opt-out-received)
 - [Contacts Callback](https://docs.webexinteract.com/reference/contacts-callback)
 ---
 ## Support
 For issues with:
 - **This parser:** Open an issue on the GitHub repository
 - **Webex Interact API:** Contact Webex Interact support
 ---
 Built with ❤️ for better webhook debugging