Contact integrations

Contact Integrations allow you to connect external services to pull additional information about contacts and display it in the Contact Profile Sheet during conversations.

Phase 1: Basic Setup (Current)

Accessing Integrations

Team-Level Management:

1. Navigate to the Integrations section in your team sidebar
2. View all team integrations at /integrations
3. Click "Add Integration" to create a new team-level integration
4. Attach integrations to multiple inboxes as needed

Inbox-Level Viewing:

1. Navigate to inbox settings: /inboxes/{inbox_id}/settings
2. Click on the "Integrations" tab to view attached integrations
3. Click "Manage Integrations" to access team-level management

Creating an Integration

Basic Information

• Name: A descriptive name for your integration (e.g., "Translayte Client Data")
• Description: Optional description of what this integration does

API Configuration (Configuration Tab)

• HTTP Method: Choose GET, POST, PUT, PATCH, or DELETE
• API Endpoint URL: The full URL to your external API
• HTTP Headers: Add custom headers like Authorization, Content-Type, etc.
• Request Body: JSON payload for POST/PUT/PATCH requests (supports variables)
• Query Parameters: URL parameters for GET/DELETE requests (supports variables)
• Cache Duration: How long (in minutes) to cache API responses (0-1440 minutes)

Testing (Testing Tab)

• Real-time API Testing: Test your integration with live API calls
• Response Preview: View actual API responses and error messages
• Performance Metrics: See execution time and success/failure status
• Sample Data Input: Test with different contact data

Display Templates (Template Tab)

• Custom Display Templates: Transform JSON responses into structured UI components
• Visual Template Editor: Drag-and-drop interface with live preview
• Multiple Section Types: Lists, tables, text, buttons, repeating sections for arrays
• Field Formatting: Automatic formatting for currency, dates, status badges, links

Inbox Attachment

• Multi-Inbox Support: Attach the same integration to multiple inboxes
• Flexible Assignment: Enable/disable per inbox as needed
• Team-Wide Sharing: Create once, use across multiple inboxes

Variable Support

You can use these variables in your API endpoint URL, headers, query parameters, and request body:

Contact & Conversation Variables

• {{contact.id}} - Contact ID
• {{contact.name}} - Contact name
• {{contact.email}} - Contact email
• {{contact.phone_number}} - Contact phone number
• {{contact.attributes.CUSTOM}} - Custom contact attributes
• {{conversation.id}} - Conversation ID
• {{conversation.subject}} - Conversation subject

Inbox & System Variables

• {{inbox.id}} - Inbox ID
• {{inbox.name}} - Inbox name

Variables are case-sensitive and will be replaced with actual values when the API call is made.

Examples

Translayte Integration

Name: Translayte Client Info
Description: Fetch client details from Translayte API
Method: POST
URL: https://translayte.com/api/v1/clients
Headers:
  - Authorization: Bearer your-api-token-here
  - Content-Type: application/json
Request Body:
{
  "email": "{{contact.email}}",
  "name": "{{contact.name}}"
}
Cache: 30 minutes
Display: Enabled
Active: Yes

Simple Customer Lookup

Name: Customer Data
Description: Get customer info from CRM
Method: GET  
URL: https://api.mycrm.com/customers?email={{contact.email}}
Cache: 15 minutes
Display: Enabled
Active: Yes

Coming in Phase 2

• Display Templates: Customize how data appears in contact profiles
• Testing Interface: Test integrations before saving
• Refresh Controls: Manual refresh of cached data
• Contact Profile Integration: Display retrieved data in ContactProfileSheet
• Service Layer: Actual API execution with caching
• Advanced Variable Support: More context variables and helper functions

Limitations

Current Phase 1 Limitations

• Simple caching without refresh controls
• No display template customization
• Data is fetched but not yet displayed in Contact Profile Sheet
• No testing interface yet
• Service layer not implemented (API calls don't execute yet)

Security Notes

• All integrations are scoped to specific inboxes
• Only team admins can create/edit integrations
• API credentials will be encrypted in Phase 2

Troubleshooting

Integration Not Working

1. Check that the integration is marked as "Active"
2. Verify the API endpoint URL is correct
3. Ensure the external service is accessible
4. Check Laravel logs for error details

Cache Issues

• Set cache duration to 0 for testing (disables caching)
• Cached data will refresh automatically after the specified duration
• Manual refresh controls coming in Phase 2

Implementation Status

✅ Phase 1 Complete: UI & CRUD components for Contact Integrations
✅ Phase 2 Complete: Integration & testing components
✅ Phase 3 Complete: ContactProfileSheet integration and display
✅ Phase 4 Complete: Custom Display Templates system
✅ Phase 5 Complete: Team-level architecture and advanced features

Phase 2 Additions:

• Reusable HTTP Request Service (HttpRequestService) shared between AgentAction and ContactIntegration
• Contact Integration Service (ContactIntegrationService) with caching support
• Testing Interface in Settings.vue with real-time API testing
• Backend APIs for testing integrations, fetching contact data, and cache management
• Full HTTP Configuration (headers, query parameters, request body) with variable replacement
• Unified Architecture - Both AgentAction and ContactIntegration now use the same HTTP execution engine

Phase 3 Additions:

• ContactProfileSheet Integration: External Data section displays integration results
• Auto-execution: Integrations run automatically when ContactProfileSheet opens
• Manual Refresh Controls: "Refresh All" and individual integration refresh buttons
• Cache Status Indicators: Shows if data is from cache or fresh
• Loading States: Individual and global loading indicators
• Error Handling: Graceful error display for failed integrations
• JSON Data Display: Formatted display of external API responses
• Performance Tracking: Shows execution time for each integration

Phase 4 Additions:

• Visual Template Builder: Drag-and-drop interface for creating display templates
• Template Renderer Engine: Converts JSON data to structured UI components
• Multiple Layout Types: Cards, tables, key-value lists, text sections, separators
• Dynamic Data Binding: {{variable}} syntax for connecting API data to templates
• Field Type Formatting: Automatic formatting for currency, dates, status badges, links
• Conditional Display Logic: Show/hide sections based on data values
• Live Preview: Real-time template preview with sample data
• Template Validation: Backend validation and XSS protection
• Preset Templates: Quick-start templates for common use cases

Phase 5 Additions:

• Team-Level Architecture: Refactored from inbox-specific to team-level integrations with multi-inbox attachments
• Centralized Management: Moved integration management to team sidebar, removed from individual inbox settings
• Multi-Tab Interface: Enhanced editor with separate tabs for Configuration, Testing, and Templates
• Repeating Sections: Support for array data with configurable item templates (orders, transactions, etc.)
• Link Support: Clickable links in both regular sections and repeating sections that open in new tabs
• Button Integration: Interactive buttons in templates with customizable styling and dynamic URLs
• Clean UI: Removed technical metadata (success badges, cache indicators, response times) for streamlined display
• Enhanced Navigation: Simplified access with inbox-level viewing and team-level management
• Flexible Attachment: Easy attach/detach integrations from multiple inboxes without duplication

User Experience

ContactProfileSheet External Data Section

When viewing a contact profile, users now see:

1. Automatic Loading: Active integrations execute automatically when the sheet opens
2. External Data Cards: Each integration displays in its own clean card
3. Custom Templates: Rich, formatted data using custom display templates instead of raw JSON
4. Interactive Elements: Clickable links and buttons that open in new tabs
5. Array Support: Repeating sections for multiple items (orders, tickets, etc.)
6. Individual Controls: Refresh button for each integration
7. Global Refresh: "Refresh All" button to update all integrations
8. Error Display: Clear error messages for failed integrations
9. Clean UI: Focused on data content without technical metadata clutter

Example Integration Flow

1. Team Setup: Admin configures a "Customer Data" integration in the team Integrations section
2. Multi-Inbox Attachment: Integration is attached to multiple support inboxes as needed
3. API Call: Integration calls https://api.example.com/customers/{{contact.email}}
4. Template Processing: Custom display template transforms the response into a structured layout
5. Rich Display: When viewing John Doe's profile, external data shows as formatted cards with:
   • Customer information with badges and status indicators
   • Financial data with currency formatting
   • Order history in repeating sections
   • Action buttons linking to external systems
6. User Actions: Agent can refresh data and interact with links/buttons in the display

Display Templates (Phase 4)

Admins can now create custom layouts for displaying external data:

1. Template Editor: Visual interface in Integration Settings with live preview
2. Multiple Layouts: Choose from cards, tables, key-value lists, and text sections
3. Smart Formatting: Automatic currency, date, and status formatting
4. Dynamic Content: Use {{variable}} syntax to bind API data
5. Conditional Logic: Show sections only when certain conditions are met

Example Template Output:

┌─ Customer Information ─────────────────┐
│ Customer ID     12345          [Gold]   │
│ Support Tier    Priority      [Active] │
│ ────────────────────────────────────── │
│ Financial Summary                      │
│ Lifetime Value  $2,850.00             │
│ Last Purchase   Jan 15, 2024          │
└────────────────────────────────────────┘

Instead of raw JSON, agents see beautifully formatted, actionable information.

Future Enhancements

Advanced Features:

• Custom Display Templates: JSON-to-UI template system for better data presentation
• Auto-execution Triggers: Run integrations on specific conversation events
• Conditional Logic: Execute based on conversation status or contact attributes
• Data Aggregation: Combine multiple API responses into unified views
• Integration Marketplace: Pre-built templates for popular services