Designing Rich Media Messaging Workflows (PDFs, Carousels) for WhatsApp Business

How-To-Articles
1

Designing Rich Media Messaging Workflows (PDFs, Carousels) for WhatsApp Business

What This Guide Covers

  • Implementing advanced WhatsApp Business messaging features, including PDF document delivery, interactive carousels, and quick-reply buttons within Genesys Cloud.
  • Architecting the back-end asset delivery pipeline to ensure high-bandwidth media (videos, documents) are delivered securely and reliably to customers.
  • The end result is a modern, interactive digital experience that moves beyond simple text chat into high-value self-service and document exchange.

Prerequisites, Roles & Licensing

  • Licensing: Genesys Cloud CX 1, 2, or 3 with WhatsApp Digital enabled.
  • WhatsApp Deployment: A verified WhatsApp Business Account (WABA) integrated via the Genesys Cloud Admin UI.
  • Permissions: Messaging > Platform > View, Messaging > Platform > Add, Architect > Flow > Edit.
  • Infrastructure: A public-facing web server or cloud storage (AWS S3, Azure Blob) to host media assets.

The Implementation Deep-Dive

1. Architecting the Media Asset Pipeline

Genesys Cloud does not “host” the media files you send via WhatsApp. It only passes the URL of the media to the WhatsApp platform.

The Trap:
Linking directly to internal file shares or non-publicly accessible URLs. If the WhatsApp/Meta servers cannot reach your media URL to download and cache the file, the message will fail with a “Media Download Error” on the customer’s phone.

Architectural Reasoning:
Use a Signed URL strategy.

  1. Store your PDFs and videos in a private S3 bucket.
  2. Use a Genesys Cloud Data Action to trigger a Lambda function that generates a time-limited Signed URL for the specific file.
  3. Pass this Signed URL to the WhatsApp message payload. This ensures that your assets are public only for the duration of the message delivery, protecting sensitive customer documents.

2. Implementing WhatsApp Carousels and Quick Replies

Interactive components significantly increase engagement compared to plain text lists.

Implementation Steps:

  1. Define the Structure: Use the Architect Inbound Message Flow and the “Show Digital Menu” or “Send Response” actions.
  2. Template Mapping: For business-initiated carousels, you must pre-register the carousel structure as a WhatsApp Message Template in the Meta Business Manager.
  3. Payload Construction: Use the v2.conversations.messages.{id}.details API to send complex interactive objects. The payload must follow the WhatsApp-specific interactive object schema:
{
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Select an Option" },
    "body": { "text": "Choose from the list below:" },
    "action": {
      "button": "View Services",
      "sections": [
        { "title": "Inquiry", "rows": [{ "id": "row1", "title": "Balance" }] }
      ]
    }
  }
}

The Trap:
Exceeding character limits in button labels. WhatsApp quick-reply buttons have a strict 20-character limit. If you exceed this, the entire interactive component will fail to render, and the customer will see a broken message bubble.

3. Handling Inbound Media and Document Collection

The real value of WhatsApp in a contact center is the ability for customers to send photos of documents (IDs, proof of insurance) directly to the agent.

Architectural Reasoning:
Ensure your Content Management Settings in Genesys Cloud allow the specific file types (PDF, JPG, PNG) for the WhatsApp channel. Configure an Architect Flow to detect attachments and use a Data Action to automatically upload these documents to your CRM (e.g., Salesforce “Files”) before the agent even accepts the interaction. This reduces Average Handle Time (AHT) significantly.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Video File Size Limits

  • The Failure Condition: Large video files fail to deliver to customers.
  • The Root Cause: WhatsApp enforces a strict 16MB limit for most media files and 64MB for certain video types.
  • The Solution: Implement an automated transcoding step in your asset pipeline (e.g., AWS Elemental MediaConvert) to ensure all videos are compressed below the 16MB threshold before the Signed URL is generated.

Edge Case 2: Template Variable Mismatch

  • The Failure Condition: A proactive carousel template fails to send.
  • The Root Cause: The number of variables (e.g., {{1}}, {{2}}) in your API call doesn’t match the approved template.
  • The Solution: Use the gc messaging whatsapp templates list command to verify the current “live” version of the template before sending the campaign.

Official References