Viber

Connect with your customers via Viber messaging through PantheonCloud's API. Build rich conversational experiences with multimedia support.

Overview

PantheonCloud's Viber integration allows businesses to send and receive messages through the Viber messaging platform. With over 1 billion users worldwide, Viber provides an excellent channel for customer engagement, support, and marketing communications.

Rich Messaging

Send text, images, videos, files, and interactive messages.

Global Reach

Connect with users across 190+ countries worldwide.

Secure Communications

End-to-end encryption for all messages and media.

Key Features

Text & Rich Media Messages

Send text messages, photos, videos, documents, contacts, URLs, and locations through a simple API.

Two-way Communication

Send messages to users and receive replies through webhook callbacks.

Interactive Keyboard

Create interactive experiences with custom keyboards containing quick reply buttons and other interactive elements.

Rich Business Messages

Deliver structured messages with images, descriptions, and action buttons for enhanced engagement.

Message Status Tracking

Track the delivery and read status of messages to monitor communication effectiveness.

Group Chat Support

Engage with multiple users simultaneously through group chat functionality.

Getting Started

Step 1: Create a Viber Business Account

Before you can integrate with Viber, you need to create a Viber Business Account:

  1. Visit the Viber Partners Portal
  2. Register your business and follow the verification process
  3. Create your Viber bot or official account
  4. Obtain your Viber authentication token

The Viber Business Account approval process may take 3-5 business days.

Step 2: Configure Viber in PantheonCloud Dashboard

  1. Log in to your PantheonCloud account
  2. Navigate to the "Channels" section and select "Viber"
  3. Click on "Add Viber Channel"
  4. Enter your Viber authentication token and other required details
  5. Configure your webhook URL for receiving messages
  6. Click "Save" to complete the setup

Once configured, your Viber channel will be available for sending and receiving messages through the PantheonCloud API.

Step 3: Start Sending Messages

You're now ready to start sending messages via the PantheonCloud API. Here's a basic example of how to send a text message:

Send Text Message Example
POST https://api.bitpanyun.com/v1/messages/viber
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "to": "USER_ID",
  "from": "YOUR_BOT_ID",
  "type": "text",
  "text": "Hello from PantheonCloud Viber integration!",
  "reply_url": "https://your-server.com/webhook"
}

API Reference

Send Text Message

POST

https://api.bitpanyun.com/v1/messages/viber

Request Body

JSON Example
{
  "to": "VIBER_USER_ID",
  "from": "YOUR_BOT_ID",
  "type": "text",
  "text": "Welcome to our service! How can we help you today?",
  "keyboard": {
    "Type": "keyboard",
    "DefaultHeight": true,
    "BgColor": "#7B519D",
    "Buttons": [
      {
        "Columns": 6,
        "Rows": 1,
        "BgColor": "#FFFFFF",
        "ActionType": "reply",
        "ActionBody": "information",
        "Text": "Information"},{
        "TextSize": "medium"
      },
      {
        "Columns": 6,
        "Rows": 1,
        "BgColor": "#FFFFFF",
        "ActionType": "reply",
        "ActionBody": "support",
        "Text": "Support"},{"old_str":
        "TextSize": "medium"
      }
    ]
  },
  "reply_url": "https://your-server.com/webhook",
  "track_message": true
}

Response

JSON Example
{
  "message_id": "msg_abc123def456",
  "status": "sent",
  "to": "VIBER_USER_ID",
  "from": "YOUR_BOT_ID",
  "channel": "viber",
  "timestamp": "2023-07-15T10:30:00Z"
}

Send Image Message

POST

https://api.bitpanyun.com/v1/messages/viber

Request Body

JSON Example
{
  "to": "VIBER_USER_ID",
  "from": "YOUR_BOT_ID",
  "type": "image",
  "image": {
    "media": "https://example.com/images/promotion.jpg",
    "caption": "Check out our new promotion!",
    "thumbnail": "https://example.com/images/promotion-thumb.jpg"
  },
  "reply_url": "https://your-server.com/webhook",
  "track_message": true
}

Send Rich Business Message

POST

https://api.bitpanyun.com/v1/messages/viber

Request Body

JSON Example
{
  "to": "VIBER_USER_ID",
  "from": "YOUR_BOT_ID",
  "type": "rich_media",
  "rich_media": {
    "Type": "rich_media",
    "ButtonsGroupColumns": 6,
    "ButtonsGroupRows": 7,
    "BgColor": "#FFFFFF",
    "Buttons": [
      {
        "Columns": 6,
        "Rows": 3,
        "ActionType": "open-url",
        "ActionBody": "https://example.com/product/123",
        "Image": "https://example.com/images/product1.jpg"
      },
      {
        "Columns": 6,
        "Rows": 1,
        "ActionType": "reply",
        "ActionBody": "details",
        "Text": "View Details"},{
        "TextSize": "medium"
      },
      {
        "Columns": 6,
        "Rows": 1,
        "ActionType": "reply",
        "ActionBody": "buy",
        "Text": "Buy Now",
        "TextSize": "medium",
        "BgColor": "#10B981"
      }
    ]
  },
  "reply_url": "https://your-server.com/webhook",
  "track_message": true
}

Webhook Integration

To receive messages and message status updates from Viber, you need to set up a webhook endpoint on your server. Here's how to handle incoming webhooks:

Webhook Events

Your webhook endpoint will receive the following types of events:

  • message - When a user sends a message to your bot
  • delivered - When a message is delivered to the user
  • seen - When a user has read your message
  • failed - When a message could not be delivered
  • conversation_started - When a user starts a conversation with your bot

Sample Webhook Payload

Incoming Message Example
{
  "event": "message",
  "timestamp": 1626357600000,
  "message_token": "1234567890123456789",
  "sender": {
    "id": "VIBER_USER_ID",
    "name": "John Doe",
    "avatar": "https://example.com/avatar.jpg"
  },
  "message": {
    "type": "text",
    "text": "Hello, I need help",
    "tracking_data": "campaign-123"
  },
  "message_id": "msg_abc123def456",
  "channel": "viber"
}

Webhook Handler Example (Node.js)

Express.js Webhook Handler
const express = require('express');
const app = express();
app.use(express.json());

// Viber webhook endpoint
app.post('/webhook/viber', (req, res) => {
  const webhookData = req.body;
  
  // Log the incoming webhook data
  console.log('Received Viber webhook:', webhookData);
  
  // Handle different event types
  switch (webhookData.event) {
    case 'message':
      // Process incoming message
      handleIncomingMessage(webhookData);
      break;
      
    case 'delivered':
      // Handle message delivery confirmation
      updateMessageStatus(webhookData.message_token, 'delivered');
      break;
      
    case 'seen':
      // Handle message seen confirmation
      updateMessageStatus(webhookData.message_token, 'seen');
      break;
      
    case 'failed':
      // Handle message failure
      handleMessageFailure(webhookData);
      break;
      
    case 'conversation_started':
      // Handle new conversation
      welcomeNewUser(webhookData.sender);
      break;
  }
  
  // Always respond with 200 OK to acknowledge receipt
  res.status(200).send({ status: 'ok' });
});

function handleIncomingMessage(webhookData) {
  const userMessage = webhookData.message.text;
  const userId = webhookData.sender.id;
  
  // Process message and prepare response
  // This is where you would implement your business logic
  console.log(`User ${userId} sent: ${userMessage}`);
  
  // Example: Send a reply using the PantheonCloud API
  sendReply(userId, `Thank you for your message: ${userMessage}`);
}

function sendReply(userId, message) {
  // Implement API call to send reply through PantheonCloud
  // ...
}

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Best Practices

Get User Consent

Always ensure users have explicitly consented to receive messages from your business before sending them communications.

Respect Time Zones

Be mindful of the user's local time when sending messages, especially for time-sensitive information.

Provide Opt-Out Options

Always include clear opt-out instructions in your messages and honor unsubscribe requests immediately.

Optimize for Mobile

Design messages and rich media content with mobile users in mind, ensuring they display correctly on various screen sizes.

Secure Data Handling

Follow data protection regulations and best practices when collecting, storing, and processing user information.

Monitor and Analyze

Track message delivery, read rates, and user engagement to continuously optimize your communication strategy.

Error Codes

Code Description Resolution
VIBER_001 Invalid Viber authentication token Check your Viber authentication token in the dashboard
VIBER_002 User not subscribed to your bot User must first subscribe to your bot before receiving messages
VIBER_003 Invalid message type Check that you are using a supported message type (text, image, file, etc.)
VIBER_004 Media file too large Reduce the size of your media files before sending
VIBER_005 Webhook URL unreachable Ensure your webhook URL is valid and publicly accessible
VIBER_006 Rate limit exceeded Reduce the frequency of your API calls or contact support to increase limits
VIBER_007 Bot is suspended Check your Viber Business Account status in the Viber Partners Portal
VIBER_008 Invalid rich media template Ensure your rich media template follows Viber's formatting requirements