Implementing Viber Business Messages Integration with Rich Media and Keyboard Buttons in Genesys Cloud CX

How-To-Articles
1

Implementing Viber Business Messages Integration with Rich Media and Keyboard Buttons in Genesys Cloud CX

What This Guide Covers

This guide details the configuration of a Viper Business Messages channel within Genesys Cloud CX, specifically focusing on provisioning the Digital Channel and constructing compliant rich media payloads via the Messaging API. The end result is an operational inbound and outbound messaging flow capable of delivering interactive keyboard buttons and image-based content directly to the Viber application while maintaining session state compliance with carrier policies.

Prerequisites, Roles & Licensing

Successful implementation requires specific licensing tiers and granular permissions within the Genesys Cloud CX organization. You must verify the following before attempting configuration:

Licensing Requirements:

  • Genesys Cloud CX Digital Channels License: Viber messaging is not included in the base voice license. It requires an active add-on or a higher tier of the Digital Channel bundle depending on your region.
  • Messaging Add-On: Access to the Messaging API and Webhook configuration requires the Messaging capability enabled at the organization level.

Granular Permissions:
The user performing the configuration requires the following permission strings within the Admin Panel:

  • Digital Channels > Channel > Create
  • Digital Channels > Channel > Edit
  • Digital Channels > Conversation > View
  • Integrations > Webhooks > Manage (For endpoint verification)

OAuth Scopes:
For API-driven message dispatch, the integration account or service principal must possess the following scopes:

  • messaging:write (Required for outbound rich media)
  • messaging:read (Required for inbound payload consumption)
  • conversation:read (Required for session state management)

External Dependencies:

  • Viber Business Account: A registered Viber Business account with a verified phone number or public page.
  • Carrier Whitelisting: Genesys Cloud must be whitelisted by the local Viber partner team in your specific region (e.g., EMEA, APAC, US). This is often handled during the initial provisioning request and cannot be self-serviced via the UI.

The Implementation Deep-Dive

1. Channel Provisioning and Webhook Verification

The foundational step involves registering the Viber channel within the Genesys Cloud Admin Console. Unlike standard SMS or Email channels, Viber requires a specific handshake between the Genesys webhook endpoint and the Viber Partner API to establish trust.

Configuration Steps:

  1. Navigate to Admin > Digital Channels.
  2. Select Messaging Channels and click Add Channel.
  3. Choose Viber from the provider list. Note that availability depends on your tenant region.
  4. In the configuration form, enter the Webhook URL. This is typically a Genesys Cloud-hosted endpoint or an external middleware endpoint (e.g., MuleSoft, Node.js) configured to forward traffic to Genesys.
  5. Enter the Viber Bot Token provided by your Viber Business Account settings.
  6. Save and wait for the status to transition from Pending to Active.

The Trap:
The most common misconfiguration occurs during the Webhook URL validation phase. Administrators often configure a generic endpoint without ensuring the specific Genesys Cloud IP allow-list is applied on their firewall or middleware layer. If the Viber Partner API attempts to verify the webhook signature and fails due to network restrictions, the channel status will remain in a Failed Verification state indefinitely. This causes silent failures where agents believe the channel is active but inbound messages never reach the conversation queue.

Architectural Reasoning:
We use the Genesys Cloud Messaging API abstraction layer rather than calling the raw Viber Partner API directly. The reason is session management and routing consistency. Genesys Cloud handles the state machine for the conversation (Open, Closed, Transferred) across all digital channels. If you bypass this layer to call the Viber API directly, you lose the ability to transfer a Viber conversation to a voice agent or another chat channel seamlessly. The abstraction ensures that the session context is preserved regardless of the underlying transport protocol.

JSON Payload for Channel Registration (Internal Reference):
While most configuration happens in the UI, understanding the internal object structure helps in debugging webhook payloads.

{
  "channelType": "VIBER",
  "name": "Customer Support Viber Bot",
  "webhookUrl": "https://api.genesyscloud.com/api/v2/external/webhooks/uuid-1234",
  "providerConfig": {
    "botToken": "xxxxxxxxxxxxxxxxxxxxx",
    "publicPageId": "xxxxxxxxxx"
  },
  "status": "ACTIVE"
}

2. Architecting Rich Media Payloads via Messaging API

Once the channel is active, the focus shifts to message composition. Viber supports rich media including images, video thumbnails, and button groups. The Genesys Cloud Messaging API accepts a standardized JSON structure but maps specific fields differently depending on the target channel.

Configuration Steps:

  1. Ensure your integration service has valid OAuth tokens with messaging:write scope.
  2. Construct the message payload targeting the specific Viber conversation ID.
  3. Include the content object with type keyboard or image.
  4. Validate the payload against the Genesys Cloud schema before transmission to avoid HTTP 400 errors.

The Trap:
A frequent failure mode involves the payload size limit. Viber imposes a strict maximum file size for images (typically 5MB) and specific aspect ratio requirements for thumbnails. If you attempt to send a high-resolution image directly through the API without pre-optimizing it, the request will fail at the transport layer. Furthermore, developers often confuse the image field with the video field in the generic payload schema. In Genesys Cloud CX, you must explicitly declare the media type within the channel-specific extension object, not just the generic content block. Failure to declare this results in the message being delivered as plain text or rejected entirely by the Viber client app.

Architectural Reasoning:
We construct rich media payloads using the Message Content Object hierarchy. This allows for a uniform approach across channels while permitting channel-specific overrides. For Viber, we utilize the keyboard object to define user actions. The architectural decision here is to separate the content (what the user sees) from the action (what the user triggers). This separation ensures that if you update the button labels via a content management system later, the underlying conversation logic remains intact. We do not embed raw URLs for media files within the API payload; instead, we reference pre-hosted assets or use Genesys Cloud’s built-in media hosting to ensure CDN performance and compliance with carrier bandwidth throttling policies.

Production-Ready JSON Payload (Outbound Rich Media):
This example demonstrates sending an image with a keyboard button group via the Genesys Cloud Messaging API.

POST https://platform.genesiscloud.com/api/v2/conversations/messages

{
  "channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
  "conversationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "MESSAGE",
  "messageType": "TEXT",
  "content": {
    "text": "Please review the product catalog below and select an option to proceed.",
    "mediaUrls": [
      "https://cdn.example.com/product-image-v2.jpg"
    ],
    "viberChannelSpecifics": {
      "image": {
        "url": "https://cdn.example.com/product-image-v2.jpg",
        "thumbnailUrl": "https://cdn.example.com/product-thumb.jpg",
        "altText": "Product Catalog 2024"
      },
      "keyboard": {
        "buttons": [
          {
            "actionType": "reply",
            "title": "View Prices",
            "payload": "VIEW_PRICES"
          },
          {
            "actionType": "reply",
            "title": "Contact Agent",
            "payload": "CONTACT_AGENT"
          }
        ],
        "defaultButtons": [
          {
            "actionType": "open-url",
            "title": "Website",
            "url": "https://example.com/home"
          }
        ]
      }
    }
  },
  "metadata": {
    "source": "api-integration",
    "timestamp": "2023-10-27T14:30:00Z"
  }
}

3. Session Management and Keyboard Persistence

Viber Business Messages operates on a session model that differs significantly from standard SMS or Email. A Viber conversation remains open for a specific window (typically 24 hours) after the last user interaction, during which you can send messages without requiring a new opt-in. However, keyboard buttons are transient by default unless configured correctly within the architecture.

Configuration Steps:

  1. Identify the conversation state in the Genesys Cloud Conversation API.
  2. Check for existing session metadata to determine if the user is still within the 24-hour window.
  3. Configure the keyboard buttons to persist across message exchanges within that session.
  4. Implement logic to handle the action payload returned by the Viber client (e.g., VIEW_PRICES).

The Trap:
The most critical failure point involves session expiration handling. Developers often attempt to send a follow-up message with keyboard buttons after the 24-hour session has expired. The Genesys Cloud API will accept the request, but the Viber carrier will reject it at the delivery level because the user has not re-initiated the conversation. This results in a “delivered” status from Genesys but no receipt by the user. Additionally, if the keyboard button payload does not match the expected format (e.g., sending an object instead of a string), the Viber client will drop the message silently to protect against injection attacks.

Architectural Reasoning:
We implement session state checks via the Conversation Metadata API before dispatching any outbound rich media. This ensures we do not waste API quota or violate carrier policies by sending messages outside the allowed window. If the session is closed, we trigger an opt-in flow instead of a direct message. For keyboard buttons, we treat them as distinct conversation events. The payload field in the button definition acts as a state machine trigger. We do not rely on the UI to remember the previous button; we store the interaction state in our backend database or Redis cache and update the next sent message’s keyboard configuration dynamically based on that state. This decouples the user interface from the backend logic, allowing for complex decision trees without bloating the Viber payload structure.

Validation Logic (Pseudo-code for State Check):

function canSendRichMedia(conversationId) {
    const conversation = getConversationDetails(conversationId);
    const lastInteractionTime = new Date(conversation.lastMessageDate);
    const sessionWindowMs = 24 * 60 * 60 * 1000; // 24 hours
    
    if (Date.now() - lastInteractionTime > sessionWindowMs) {
        return { 
            status: "EXPIRED", 
            action: "REQUIRE_OPT_IN" 
        };
    }
    return { 
        status: "ACTIVE", 
        action: "SEND_RICH_MEDIA" 
    };
}

Validation, Edge Cases & Troubleshooting

Edge Case 1: Webhook Signature Verification Failure

The Failure Condition: Inbound messages appear in the Genesys Cloud admin panel but never trigger a response flow or webhook callback to the backend.
The Root Cause: The Viber Partner API sends a signed header with every request. If the secret key used for signing is mismatched between the Viper Business Account and the Genesys configuration, or if the IP allow-list on the middleware layer blocks the request, the signature verification fails.
The Solution: Navigate to Admin > Digital Channels > Channel Configuration. Verify that the Bot Secret matches exactly. Check the webhook logs in the Genesys Cloud platform to see if the HTTP status code is 200 OK. If the status is 401 Unauthorized, regenerate the secret key in the Viber Business Portal and update it in Genesys Cloud immediately. Ensure your firewall allows traffic from the specific IP ranges listed in the Genesys Cloud IP Allow-list documentation for your region.

Edge Case 2: Image Rendering on Android vs iOS

The Failure Condition: The rich media image displays correctly on iOS devices but appears as a broken link or blank box on Android devices within the Viber application.
The Root Cause: This is often due to MIME type mismatches or compression artifacts in the image file. Viber enforces strict MIME types (usually image/jpeg or image/png) and expects specific compression levels for optimal rendering on mobile networks. If the image URL serves a generic application/octet-stream header, Android clients may block it.
The Solution: Ensure all media URLs point to HTTPS endpoints with correct HTTP headers (Content-Type: image/jpeg). Use an automated image optimization tool that converts images to WebP or optimized JPEG formats before uploading them to your CDN. Validate the URL using a browser console on both platforms before deploying to production.

Edge Case 3: Keyboard Button Payload Injection

The Failure Condition: A keyboard button click returns a malformed payload to the backend, causing the conversation flow logic to crash or branch incorrectly.
The Root Cause: The payload field in the Viber JSON schema is restricted to strings of a certain length. If the integration attempts to send complex JSON objects inside the payload string without proper encoding, the Viber client will truncate the data.
The Solution: Always URL-encode the payload content if it contains special characters. Keep payloads short and alphanumeric (e.g., ACTION_ID_102). Use a mapping table in your backend to translate these short codes into complex logic instructions. Never pass user-generated data directly into the keyboard button payload without sanitization.

Official References