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.
