Skip to main content

C.4 InApp Generic Action / Chat

InApp Generic Action / Chat enables brokers to integrate custom actions and support chat functionality directly within cTrader. This module provides a flexible framework for implementing broker-specific features and customer support while maintaining the seamless user experience.

Overview​

The InApp Generic Action / Chat module enables:

  • Custom broker actions within cTrader interface
  • Integrated support chat functionality
  • Flexible action framework for broker-specific features
  • Real-time communication capabilities
  • Extensible architecture for custom integrations

Prerequisites​

Before implementing InApp Generic Action / Chat, ensure completion of:

  • Part A: All foundation requirements
  • Part B: Either B.1 (Full SSO) or B.2 (Light Identity Handoff)

Architecture​

Integration Flow​

  1. User Initiation: User triggers custom action or chat in cTrader
  2. Token Generation: cTrader backend generates OT token for user context
  3. Screen Launch: Broker action/chat screen opens with token authentication
  4. Action Processing: User completes custom action or chat interaction
  5. Result Communication: Action result or chat status communicated back to cTrader

Authentication Methods​

  • Full SSO: Long-term tokens with broker-owned identity
  • Light Identity: One-time tokens with cTrader identity provider

Implementation Flow​

Generic Action Flow​

Stage 1: User Initiation​

  1. User triggers custom action

    • Triggers:
      • Custom button in cTrader interface
      • Menu item in broker section
      • InApp control/ribbon click
      • Automated workflow trigger
    • Context: User ID, account info, action type, parameters

  2. cTrader backend generates OT token

    • Endpoint: /ctid2/inAppOneTimeToken/data (Light Identity)
    • Context: User ID, account info, action type, custom parameters
    • Token: Short-lived token for broker authentication

Stage 2: Broker Screen Launch​

  1. cTrader opens broker action screen

    • URL: https://brokerCrmUrl.com/inapp/action
    • Parameters: token, actionType, actionParams, lang, source, theme
    • Method: Opens in embedded browser/modal within cTrader

  2. Broker screen validates and loads

    • Token Validation: Verify OT token validity and user context
    • Action Routing: Route to appropriate action handler
    • User Context: Load user-specific data and preferences
    • Action Initialization: Initialize specific action workflow

Stage 3: Action Processing​

  1. User completes custom action

    • Action Types:
      • Form submissions and requests
      • Account management operations
      • Educational content access
      • Promotional offer redemption
      • Survey or feedback collection

  2. Broker processes action

    • Business Logic: Execute broker-specific business logic
    • Data Processing: Process user input and data
    • System Integration: Integrate with broker backend systems
    • Result Generation: Generate action results

Stage 4: Completion and Communication​

  1. Action completion

    • Result Status: Success, failure, or partial completion
    • Data Updates: Update relevant broker systems
    • User Notification: Provide confirmation to user

  2. Result communication to cTrader

    • Callback: Notify cTrader of action result
    • State Updates: Update relevant cTrader state if needed
    • User Notification: Show result to user in cTrader

Support Chat Flow​

Stage 1: Chat Initiation​

  1. User initiates support chat

    • Triggers:
      • Click support/chat button in cTrader
      • Automatic trigger based on user behavior
      • Proactive chat invitation from broker
    • Context: User ID, account info, chat context, reason

  2. cTrader backend generates OT token

    • Endpoint: /ctid2/inAppOneTimeToken/data (Light Identity)
    • Context: User ID, account info, action type "chat"
    • Token: Short-lived token for broker authentication

Stage 2: Chat Screen Launch​

  1. cTrader opens broker chat screen

    • URL: https://brokerCrmUrl.com/inapp/chat
    • Parameters: token, chatReason, department, lang, source, theme
    • Method: Opens in embedded browser/modal within cTrader

  2. Broker chat system initializes

    • Token Validation: Verify OT token and user context
    • User Identification: Identify user in chat system
    • Chat History: Load relevant chat history if available
    • Agent Assignment: Assign to appropriate support agent

Stage 3: Chat Interaction​

  1. User engages in chat conversation

    • Real-time Messaging: Exchange messages with support agents
    • File Sharing: Share documents or screenshots if needed
    • Co-browsing: Potential co-browsing for complex issues
    • Resolution: Work toward issue resolution

  2. Broker manages chat session

    • Agent Interface: Support agent handles conversation
    • Knowledge Base: Access knowledge base for quick answers
    • Escalation: Escalate to specialized support if needed
    • Quality Assurance: Monitor chat quality and satisfaction

Stage 4: Chat Completion​

  1. Chat session conclusion

    • Resolution Status: Issue resolved, escalated, or follow-up required
    • Satisfaction Survey: Optional satisfaction survey
    • Transcript: Save chat transcript for reference

  2. Chat status communication

    • Callback: Notify cTrader of chat conclusion
    • Follow-up Actions: Schedule follow-up actions if needed
    • User Notification: Confirm chat completion to user

API Specifications​

cTrader Backend Endpoints​

OT Token Generation (Light Identity)​

GET /ctid2/inAppOneTimeToken/data
Authorization: Bearer {userSessionToken}

Response Example:

{
    "otToken": "abc123xyz789",
    "userId": 12345,
    "email": "user@example.com",
    "tradingLogin": 67890,
    "action": "generic",
    "actionType": "survey",
    "expiresAt": "2023-01-01T12:05:00Z"
}

Broker CRM Required Endpoints​

Token Validation​

POST /api/validate-token
Content-Type: application/json

Request Body:

{
    "token": "abc123xyz789"
}

Response Example:

{
    "valid": true,
    "userId": 12345,
    "email": "user@example.com",
    "tradingLogin": 67890,
    "userProfile": {
        "name": "John Doe",
        "accountType": "premium",
        "language": "en"
    }
}

Action Result Callback​

POST /ctrader/callback/action-result
Content-Type: application/json
Authorization: Bearer {crmApiToken}

Request Body:

{
    "tradingLogin": 67890,
    "actionType": "survey",
    "actionId": "survey_123456",
    "result": "completed",
    "data": {
        "satisfaction": 4.5,
        "feedback": "Great platform!"
    },
    "timestamp": "2023-01-01T12:00:00Z"
}

Required Screens​

Generic Action Screen​

  • URL: /inapp/action
  • Parameters: token, actionType, actionParams
  • Functionality:
    • Dynamic action loading based on actionType
    • Form rendering and validation
    • File upload capabilities
    • Progress tracking
    • Result display

Support Chat Screen​

  • URL: /inapp/chat
  • Parameters: token, chatReason, department
  • Functionality:
    • Real-time messaging interface
    • Chat history display
    • File attachment support
    • Agent information display
    • Satisfaction survey

Educational Content Screen​

  • URL: /inapp/education
  • Parameters: token, contentType, contentId
  • Functionality:
    • Educational content display
    • Video player integration
    • Progress tracking
    • Quiz/assessment functionality
    • Certificate generation

Implementation Requirements​

Broker CRM Requirements​

Action Framework​

  • Action Registry: Registry of available action types
  • Dynamic Routing: Route actions to appropriate handlers
  • Parameter Validation: Validate action parameters
  • Result Processing: Process and store action results

Chat Integration​

  • Chat Platform: Integration with chat platform (Intercom, Zendesk, etc.)
  • Agent Management: Support agent assignment and management
  • Knowledge Base: Integration with knowledge base systems
  • Quality Assurance: Chat quality monitoring and evaluation

Frontend Requirements​

Responsive Design​

  • Mobile Compatibility: Optimize for mobile devices
  • Touch Interface: Touch-friendly interaction design
  • Loading States: Clear loading indicators
  • Error Handling: User-friendly error messages

Real-time Communication​

  • WebSocket Integration: Real-time messaging capabilities
  • Connection Management: Handle connection drops and reconnection
  • Message History: Maintain message history
  • Typing Indicators: Show typing indicators for better UX

URL Examples​

Generic Action URLs​

<!-- Basic action URL -->
https://brokerCrmUrl.com/inapp/action?token=abc123&actionType=survey&lang=en

<!-- With parameters -->
https://brokerCrmUrl.com/inapp/action?token=abc123&actionType=promo&promoId=summer2023&lang=en

<!-- Educational content -->
https://brokerCrmUrl.com/inapp/education?token=abc123&contentType=video&contentId=forex101&lang=en

Chat URLs​

<!-- Basic chat URL -->
https://brokerCrmUrl.com/inapp/chat?token=abc123&lang=en

<!-- With chat reason -->
https://brokerCrmUrl.com/inapp/chat?token=abc123&chatReason=deposit_issue&department=support&lang=en

<!-- Proactive chat -->
https://brokerCrmUrl.com/inapp/chat?token=abc123&chatReason=proactive&agentId=john_doe&lang=en

Error Handling​

Action Errors​

{
    "error": "Action Failed",
    "message": "Unable to process action. Please try again.",
    "code": "ACTION_FAILED",
    "retryAllowed": true
}

Chat Connection Errors​

{
    "error": "Chat Unavailable",
    "message": "Chat service is currently unavailable. Please try again later.",
    "code": "CHAT_UNAVAILABLE",
    "retryAllowed": true,
    "retryAfter": 30
}

Invalid Action Type​

{
    "error": "Invalid Action",
    "message": "The specified action type is not supported.",
    "code": "INVALID_ACTION_TYPE",
    "supportedActions": ["survey", "promo", "education", "feedback"]
}

Security Considerations​

Data Protection​

  • User Privacy: Protect user privacy in all interactions
  • Data Encryption: Encrypt sensitive data transmission
  • Access Control: Implement proper access controls
  • Audit Trail: Maintain audit trail for all actions

Chat Security​

  • Message Encryption: Encrypt chat message transmission
  • Agent Authentication: Authenticate support agents
  • Data Retention: Implement appropriate chat data retention
  • Content Filtering: Filter inappropriate content if needed

Testing Requirements​

Functional Testing​

  • Action Processing: Test various action types and workflows
  • Chat Functionality: Test chat messaging and features
  • Error Scenarios: Test various error conditions
  • Cross-platform: Test across different platforms and devices

Performance Testing​

  • Concurrent Users: Test with multiple concurrent users
  • Message Throughput: Test chat message processing capacity
  • Action Performance: Test action processing performance
  • Load Testing: Test system performance under load

Security Testing​

  • Data Protection: Verify data protection measures
  • Access Control: Test access control mechanisms
  • Message Security: Test chat message security
  • Vulnerability Testing: Security vulnerability assessment

Business Benefits​

For Customer Support​

  • Accessibility: Easy access to support within trading platform
  • Context: Support agents have full trading context
  • Efficiency: Faster issue resolution with better context
  • Satisfaction: Improved customer satisfaction scores

For User Engagement​

  • Convenience: Access to services without leaving platform
  • Personalization: Personalized actions and recommendations
  • Education: Educational content easily accessible
  • Feedback: Easy feedback collection and implementation

For Operations​

  • Efficiency: Streamlined support and action workflows
  • Analytics: Better data on user interactions
  • Cost Reduction: Reduced support costs through efficiency
  • Scalability: Scalable support and action processing

Best Practices​

User Experience​

  • Clear Navigation: Intuitive navigation for actions and chat
  • Responsive Design: Mobile-first responsive design
  • Loading States: Clear loading and progress indicators
  • Error Recovery: Easy recovery from errors

Technical Implementation​

  • Async Processing: Use asynchronous processing for long operations
  • Connection Management: Robust connection management for real-time features
  • Logging: Comprehensive logging for debugging and monitoring
  • Monitoring: Real-time monitoring of system performance

Integration​

  • Modular Design: Modular architecture for easy extension
  • API Standards: Follow API design best practices
  • Documentation: Comprehensive API documentation
  • Testing: Automated testing for reliability

This InApp Generic Action / Chat integration provides a flexible framework for implementing broker-specific features and support functionality within cTrader, enhancing user experience and operational efficiency.