Chat window does not display

If the AlcmeonChat chat window does not display when users click on the chat button, this might be because you host the Alcmeon SDK on a DNS domain which has not been configured in the account's configuration page. Try to go to Parameters -> Accounts -> select account and edit the Allowed domains field to include the DNS domain of your website.

How can I generate mobile notifications for my in-app chat ?

Developers can register webhooks to be notified whenever a new reply is sent to a customer by an agent: they are then responsible to send via their notification framework of choice a notification to the user's device. More details about this here

Authentication flow schema for private chat

This schema shows how the authentication and the following calls work.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           CUSTOMER'S INFRASTRUCTURE                          │
│                                                                              │
│  ┌──────────────────┐                    ┌──────────────────────────────┐  │
│  │  User's Browser  │                    │   Customer's Backend Server  │  │
│  │                  │                    │                              │  │
│  │  ┌────────────┐  │                    │  ┌────────────────────────┐ │  │
│  │  │  Website   │  │  ① Fetch JWT      │  │  JWT Generator         │ │  │
│  │  │  (HTML/JS) │──┼───────────────────▶│  │  (Python/Node/PHP)     │ │  │
│  │  └────────────┘  │  ② Return JWT      │  │                        │ │  │
│  │        │         │◀───────────────────┼──│  Uses:                 │ │  │
│  │        │         │    {jwt: "eyJ..."}  │  │  - secret_key          │ │  │
│  │        │         │                    │  │  - customer_id         │ │  │
│  │        │         │                    │  │  - user attributes     │ │  │
│  │        ▼         │                    │  └────────────────────────┘ │  │
│  │  ┌────────────┐  │                    │                              │  │
│  │  │  Widget    │  │                    └──────────────────────────────┘  │
│  │  │  (iframe)  │  │                                                       │
│  │  │            │  │  ⚠️ Widget MUST be initialized with the JWT           │
│  │  │  Loaded    │  │     from step ②                                       │
│  │  │  with JWT  │  │                                                       │
│  │  └────────────┘  │                                                       │
│  │        │         │                                                       │
│  └────────┼─────────┘                                                       │
│           │                                                                 │
└───────────┼─────────────────────────────────────────────────────────────────┘
            │
            │ ③ POST /authenticate
            │    Authorization: Bearer {auth_jwt}
            │
            ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          SERVICE PROVIDER INFRASTRUCTURE                     │
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │                         Backend Server                               │  │
│  │                                                                      │  │
│  │  - Validates the authentication JWT                                 │  │
│  │  - Identifies or creates the user session                          │  │
│  │  - Returns a session token for subsequent requests                  │  │
│  │                                                                      │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│           │                                                                 │
│           │ ④ Response: {session_jwt, ...}                                 │
│           ▼                                                                 │
└─────────────────────────────────────────────────────────────────────────────┘
            │
            │
            ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Widget                                                                      │
│                                                                              │
│  ⑤ Stores session token for authenticated requests                         │
│                                                                              │
│  ⑥ All subsequent API calls use: Authorization: Bearer {session_jwt}       │
└─────────────────────────────────────────────────────────────────────────────┘

Detailed Sequence Diagram

User          Website       Customer        Widget          Service
Browser       Frontend      Backend         (iframe)        Provider (Alcmeon)
  │              │             │               │               │
  │──Login──────▶│             │               │               │
  │              │             │               │               │
  │              │──Request────▶               │               │
  │              │   JWT       │               │               │
  │              │             │               │               │
  │              │             │ Generate JWT  │               │
  │              │             │ ┌───────────┐ │               │
  │              │             │ │ Payload:  │ │               │
  │              │             │ │ - customer│ │               │
  │              │             │ │   _id     │ │               │
  │              │             │ │ - name    │ │               │
  │              │             │ │ - phone   │ │               │
  │              │             │ │ - attrs   │ │               │
  │              │             │ └───────────┘ │               │
  │              │             │ Sign with     │               │
  │              │             │ secret_key    │               │
  │              │◀────────────┤               │               │
  │              │ {jwt: "eyJ.."}              │               │
  │              │             │               │               │
  │              │             │               │               │
  │              │ ┌─────────────────────────────────────────┐ │
  │              │ │ IMPORTANT: Load Widget with the JWT    │ │
  │              │ │ The widget initialization MUST include │ │
  │              │ │ the JWT obtained from step ②           │ │
  │              │ └─────────────────────────────────────────┘ │
  │              │             │               │               │
  │              │─────────────┼──────────────▶│               │
  │              │             │               │               │
  │              │             │               │ Check for     │
  │              │             │               │ existing      │
  │              │             │               │ session       │
  │              │             │               │               │
  │              │             │               │ POST /authenticate
  │              │             │               │ Authorization: Bearer {auth_jwt}
  │              │             │               │──────────────▶│
  │              │             │               │               │
  │              │             │               │               │ Validate JWT
  │              │             │               │               │ and create
  │              │             │               │               │ user session
  │              │             │               │               │
  │              │             │               │               │ Generate
  │              │             │               │               │ session_jwt
  │              │             │               │               │
  │              │             │               │◀──────────────┤
  │              │             │               │ {session_jwt} │
  │              │             │               │               │
  │              │             │               │ Store session │
  │              │             │               │ token         │
  │              │             │               │               │
  │◀─────────────┼─────────────┼───────────────┤               │
  │ Widget Ready │             │               │               │
  │              │             │               │               │
  │──Send Message────────────────────────────▶│               │
  │              │             │               │               │
  │              │             │               │ POST /messages│
  │              │             │               │ Authorization:│
  │              │             │               │ Bearer {session_jwt}
  │              │             │               │──────────────▶│
  │              │             │               │               │
  │              │             │               │               │ Validate
  │              │             │               │               │ session and
  │              │             │               │               │ process
  │              │             │               │               │ request
  │              │             │               │               │
  │              │             │               │◀──────────────┤
  │              │             │               │ Response      │
  │              │             │               │               │

Summary

1. Customer Backend generates a signed JWT containing user identity
2. Widget is loaded with the JWT - The widget initialization MUST include the JWT from step 1
3. Widget sends this JWT to authenticate with the service provider
4. Service Provider (Alcmeon) validates the JWT and returns a session token
5. Widget uses the session token for all subsequent authenticated requests