How to use Dashboard Apps?

Dashboard apps in VowChat allow you to integrate custom applications within the agent dashboard, providing additional context like customer information, order history, or payment details right where your agents work.

What are Dashboard Apps?

Dashboard apps are custom applications that appear as tabs in the VowChat conversation window. They can display:

• Customer profiles from your CRM

• Order history and tracking information

• Payment and subscription details

• Custom business data

• Third-party integrations

This keeps all customer context in one place, eliminating the need to switch between applications.

How to Create a Dashboard App

Step 1. Go to Settings → Integrations → Dashboard Apps

Step 2. Click Configure for Dashboard Apps

Step 3. Click Add new dashboard app

Step 4. Fill in the app details:

• App Name: The name that will appear in the tab

• Hosting URL: The URL where your dashboard app is hosted (must be HTTPS)

Step 5. Click Create

Your dashboard app will now appear as a new tab in the conversation window!

How Dashboard Apps Work

Once configured, your dashboard app receives data from VowChat and can display custom information to your agents.

Data Flow

1. Agent opens a conversation

2. VowChat loads your dashboard app in an iframe

3. VowChat sends conversation, contact, and agent data to your app

4. Your app displays relevant customer information

5. Agent views the data alongside the conversation

Building a Dashboard App

Receiving Data from VowChat

Your dashboard app receives data through JavaScript postMessage events.

Event Listener Example:

window.addEventListener("message", function (event) {
  // Validate JSON
  if (!isJSONValid(event.data)) {
    return;
  }

  const eventData = JSON.parse(event.data);
  
  // eventData contains conversation, contact, and agent information
  console.log('Conversation ID:', eventData.conversation.id);
  console.log('Contact Email:', eventData.contact.email);
  console.log('Agent Name:', eventData.currentAgent.name);
});

function isJSONValid(str) {
  try {
    JSON.parse(str);
    return true;
  } catch (e) {
    return false;
  }
}

Requesting Data On-Demand

Your app can also request fresh data when needed:

// Request updated conversation data
window.parent.postMessage('vowchat-dashboard-app:fetch-info', '*');

VowChat will respond with the latest conversation, contact, and agent information.

Data Payload Structure

VowChat sends a JSON payload with this structure:

{
  "event": "vowchat:contact-info",
  "conversation": {
    "id": 123,
    "inbox_id": 456,
    "status": "open",
    "messages": [
      {
        "id": 789,
        "content": "Customer message",
        "created_at": "2024-01-15T10:30:00Z",
        "message_type": "incoming"
      }
    ],
    "meta": {
      "sender": {
        "id": 101,
        "name": "John Doe",
        "email": "john@example.com",
        "phone_number": "+1234567890"
      }
    },
    "custom_attributes": {
      "subscription_plan": "pro",
      "signup_date": "2023-06-15"
    }
  },
  "contact": {
    "id": 101,
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "+1234567890",
    "custom_attributes": {
      "customer_tier": "gold",
      "lifetime_value": 5000
    }
  },
  "currentAgent": {
    "id": 11,
    "name": "Agent Name",
    "email": "agent@company.com",
    "role": "agent"
  }
}

Example Use Cases

Customer Order History

Display recent orders and tracking information:

window.addEventListener("message", function (event) {
  const data = JSON.parse(event.data);
  const customerEmail = data.contact.email;
  
  // Fetch orders from your system
  fetch(`https://api.yourcompany.com/orders?email=${customerEmail}`)
    .then(response => response.json())
    .then(orders => {
      // Display orders in your dashboard app
      displayOrders(orders);
    });
});

Subscription Details

Show subscription status and billing information:

window.addEventListener("message", function (event) {
  const data = JSON.parse(event.data);
  const customerId = data.contact.id;
  
  // Fetch subscription data
  fetch(`https://api.yourcompany.com/subscriptions/${customerId}`)
    .then(response => response.json())
    .then(subscription => {
      displaySubscription(subscription);
    });
});

CRM Integration

Display customer profile from your CRM:

window.addEventListener("message", function (event) {
  const data = JSON.parse(event.data);
  const email = data.contact.email;
  
  // Fetch CRM data
  fetch(`https://crm.yourcompany.com/api/contacts?email=${email}`)
    .then(response => response.json())
    .then(profile => {
      displayCRMProfile(profile);
    });
});

Best Practices

Security

• Use HTTPS: Dashboard apps must be hosted on secure URLs

• Validate data: Always validate incoming message data

• Authenticate requests: Verify requests to your backend APIs

• Sanitize output: Prevent XSS attacks by sanitizing displayed data

Performance

• Load quickly: Keep initial load time under 2 seconds

• Cache data: Store frequently accessed data locally

• Lazy load: Load heavy content only when needed

• Optimize images: Use compressed images and lazy loading

User Experience

• Match VowChat design: Use similar colors and fonts for consistency

• Responsive layout: Ensure your app works in the iframe size

• Loading states: Show spinners while fetching data

• Error handling: Display friendly error messages

• Empty states: Handle cases where no data is available

Troubleshooting

App not loading?

• Verify the hosting URL is accessible and uses HTTPS

• Check browser console for errors

• Ensure your server allows iframe embedding

• Add appropriate CORS headers if making API calls

Not receiving data?

• Verify your event listener is set up correctly

• Check that you're parsing the JSON payload properly

• Use console.log to inspect incoming messages

• Ensure you're listening for the correct event type

Data is outdated?

• Request fresh data using postMessage('vowchat-dashboard-app:fetch-info', '*')

• Implement auto-refresh at appropriate intervals

• Listen for conversation update events

Learn More

For a complete tutorial on building dashboard apps, check out our YouTube tutorial with step-by-step instructions.