Architecture¶

This page describes the components involved in the integration, how traffic flows between them, what kind of connection is used between Lime Connect and Lime CRM, and how the communication is secured. It is intended for IT architects and security reviewers. For the step-by-step setup, see Installation.

Components¶

Component	Where it runs	Role in the integration
Lime Connect	Cloud service operated by Lime Connect (`app.lime-connect.com`)	Handles the conversations with the contact (website chat, WhatsApp, etc.). Sends conversations to Lime CRM and hosts the operator's Message Center, including the Portal panel.
Lime CRM web server	Customer's on-premise server or Lime Cloud	Exposes the integration's HTTPS endpoints (the `limepkg-userlike` package), creates the objects in Lime CRM and serves the Portal.
Lime CRM task handler	Same environment as the Lime CRM web server	Runs the optional asynchronous import of media files (images, attachments) from Lime Connect.
Lime CRM database	Same environment as the Lime CRM web server	Stores the created objects, history notes, conversation references and documents.
Operator's browser	Operator's workstation	Runs the Lime Connect Message Center. The Portal is loaded here as an iframe served by the Lime CRM web server. Links to Lime CRM open the Lime CRM web client.

flowchart LR
    Contact["Contact<br/>(website chat, WhatsApp, ...)"]

    subgraph OP["Operator's browser"]
        direction TB
        MC["Lime Connect Message Center<br/>(operator sends the conversation from here)"]
        Portal["Lime CRM Portal (iframe)"]
        MC -. "embeds" .-> Portal
    end

    subgraph LC["Lime Connect (cloud)"]
        direction TB
        LCB["Lime Connect backend"]
        LCAPI["Lime Connect API &amp; file storage"]
    end

    subgraph CRM["Lime CRM (on-premise or Lime Cloud)"]
        direction TB
        WS["Lime CRM web server<br/>limepkg-userlike endpoints"]
        TH["Lime CRM task handler"]
        DB[("Lime CRM database")]
        WS --> DB
        TH --> DB
    end

    Contact -- "chat" --> LCB
    LCB -- "1. POST conversation (HTTPS + API key)<br/>2. link to created object (response)" --> WS
    LCAPI <-- "3. task handler fetches media files<br/>(HTTPS + Lime Connect API token)" --> TH
    Portal -- "4. GET portal page and contact data<br/>(HTTPS + JWT)" --> WS
    MC -- "5. open object in Lime CRM web client<br/>(HTTPS + user login)" --> WS

Traffic Flows¶

All traffic is plain HTTPS request/response. There are no persistent connections, no polling and no software installed on the customer's network by Lime Connect. Each flow below is initiated by a specific event.

#	Flow	Initiated by	Direction	Endpoint	Authentication	When
1	Send conversation	Lime Connect backend	Lime Connect → Lime CRM web server (inbound)	`POST <SERVER_URL>/<APP_NAME>/limepkg-userlike/userlike/`	Lime CRM API key for the `userlike@lime` API user (`x-api-key` header)	When an operator sends a conversation to Lime CRM, or when Lime Connect verifies the add-on settings
2	Link back to Lime CRM	Lime CRM web server (response to flow 1)	Lime CRM → Lime Connect (response)	–	–	Immediately after flow 1. The response contains a URL to the created object
3	Import media files	Lime CRM task handler	Lime CRM → Lime Connect API (outbound)	`GET https://api.userlike.com/api/um/media/download/<file>` (URL given in the payload), then `GET` on the download URL that response returns	Lime Connect API token (`Authorization` header)	Only if `importMediaFiles` is enabled, after each sent conversation
4	Portal	Operator's browser (iframe in the Message Center)	Operator's browser → Lime CRM web server (inbound)	`GET .../limepkg-userlike/portal/client/`, `.../portal/client/data/`, `.../portal/client/translations/`, plus scripts and styles from `<SERVER_URL>/static/...`	JWT issued by Lime Connect and validated by Lime CRM (`Authorization: Bearer`)	Only if the Portal is configured. When an operator opens a conversation
5	Open object in Lime CRM	Operator's browser	Operator's browser → Lime CRM web server (inbound)	`<SERVER_URL>/client/login/?next=<SERVER_URL>/<APP_NAME>/limepkg-userlike/redirect/<client>/<limetype>/<id>/`, which redirects to `<SERVER_URL>/client/object/<limetype>/<id>/`	The operator's own Lime CRM login	When an operator clicks a link to Lime CRM in Lime Connect

Sending a Conversation¶

sequenceDiagram
    participant O as Operator (browser)
    participant LC as Lime Connect (cloud)
    participant WS as Lime CRM web server
    participant DB as Lime CRM database
    participant TH as Lime CRM task handler

    O->>LC: Send conversation to Lime CRM (topic is set)
    LC->>WS: POST /limepkg-userlike/userlike/<br/>HTTPS, x-api-key, JSON payload
    WS->>WS: Match topic to configured instance, verify ACL and object access
    WS->>DB: Create or update conversation, object and history note
    WS-->>LC: 200 { "url": "<link to object>" }
    LC-->>O: Link shown in the conversation timeline
    opt Media file import enabled
        WS->>TH: Queue import task
        TH->>LC: GET media file<br/>HTTPS, Lime Connect API token
        LC-->>TH: File content
        TH->>DB: Create document, update history note
    end

The payload sent in flow 1 is a JSON document with the conversation ID, the topics, the contact details submitted in the chat (typically name and email address) and the transcript. See Technical for an example and GDPR for which personal data is transferred. Lime CRM responds with a URL only; no CRM data is sent back to Lime Connect in this flow.

When the add-on settings are saved in Lime Connect, Lime Connect sends a small verification request to the same endpoint to confirm that the URL and API key are correct. Nothing is created in Lime CRM by the verification request.

Portal¶

sequenceDiagram
    participant MC as Lime Connect Message Center (browser)
    participant P as Lime CRM Portal (iframe, browser)
    participant WS as Lime CRM web server

    MC->>P: Load iframe from <SERVER_URL>/<APP_NAME>/limepkg-userlike/portal/client/
    P->>WS: GET portal page (HTTPS)
    WS-->>P: HTML with Content-Security-Policy frame-ancestors app.lime-connect.com
    P->>WS: GET /static/... (portal bundle, Lime Elements, icons)
    WS-->>P: JavaScript, CSS and icons
    P->>MC: postMessage: ready, generate_jwt_token
    MC-->>P: postMessage: jwt_token, contact_information, operator_information
    P->>WS: GET portal/client/data/<br/>HTTPS, Authorization: Bearer <JWT>
    WS->>WS: Validate JWT signature and expiry (HS256, shared secret)<br/>Run as the portal API user, apply policies and object access
    WS-->>P: Read-only contact data (JSON), or null if no match

The Portal never writes to Lime CRM and the contact details received from Lime Connect are only used for the lookup. The browser-side exchange between the Message Center and the iframe uses postMessage, and the Portal only accepts messages from the configured frame ancestor (https://app.lime-connect.com by default). See Technical for the endpoint details.

Connection Between Lime Connect and Lime CRM¶

Protocol: HTTPS over the public internet. No VPN, site-to-site tunnel, agent or reverse proxy from Lime Connect is involved.
Lime CRM must be reachable from Lime Connect. The Lime CRM web server URL (<SERVER_URL>) needs to accept inbound HTTPS from Lime Connect's cloud for flow 1, and from the operators' browsers for flows 4 and 5. For Lime Cloud installations this is already the case. For on-premise installations the Lime CRM web server must be published on the internet, for example through the customer's existing reverse proxy or firewall rule for the Lime CRM web client.
Outbound traffic from Lime CRM to Lime Connect only occurs in flow 3 (media file import) and only if that feature is enabled. The task handler then needs outbound HTTPS access to api.userlike.com and to the file download URL that this API returns for each file. Lime Connect does not document the host of that download URL; ask Lime Connect if the firewall needs it.
No static IP addresses are required on the Lime CRM side. Lime Connect does not publish a fixed list of source IP addresses for its callbacks, so restricting flow 1 by source IP is not supported. Access is controlled by the API key instead. Contact Lime Connect if an IP allow-list is a hard requirement.
Paths that need to be exposed: /<APP_NAME>/limepkg-userlike/userlike/ (flow 1); /<APP_NAME>/limepkg-userlike/portal/client/ and everything below it, together with /static/ (flow 4); /<APP_NAME>/limepkg-userlike/redirect/ and the Lime CRM web client itself (flow 5). The portal page is served from the portal client path, but its JavaScript, CSS and icons are loaded from Lime CRM's static route at /static/, the same route the Lime CRM web client uses, so an installation where the web client already works needs no extra rule for it. Everything else in Lime CRM can stay restricted as before.

Direction	Source	Destination	Port	Purpose	Required
Inbound to Lime CRM	Lime Connect cloud	Lime CRM web server, `.../limepkg-userlike/userlike/`	443 (TCP)	Send conversation	Yes
Inbound to Lime CRM	Operators' browsers	Lime CRM web server, `.../limepkg-userlike/portal/client/` and `/static/`	443 (TCP)	Portal	Only if the Portal is used
Inbound to Lime CRM	Operators' browsers	Lime CRM web server, `.../limepkg-userlike/redirect/` and the Lime CRM web client	443 (TCP)	Open object from Lime Connect	Yes (normal Lime CRM access)
Outbound from Lime CRM	Lime CRM task handler	`api.userlike.com` and the file download host it refers to	443 (TCP)	Media file import	Only if `importMediaFiles` is enabled

Security¶

Transport encryption. All flows use HTTPS/TLS. Configure <SERVER_URL> with https:// in Lime Connect; the Lime CRM web server must have a valid certificate.
API key (flow 1). Lime Connect authenticates with a Lime CRM API key that is generated during installation for a dedicated API user, userlike@lime. The key is stored in Lime Connect's add-on settings and in Lime CRM only. The API user cannot log in interactively, and its permissions are limited through Lime CRM policies to the tables the integration needs (see Installation). The key can be revoked or regenerated in Lime CRM at any time; update the add-on settings in Lime Connect afterwards.
Least privilege. Every object the integration creates or links is checked against Lime CRM's policies and object access for the API user. If the API user lacks access to, for example, a person or company, that relation is simply not set. See Object Access.
JWT (flow 4). The Portal's data endpoint requires a JSON Web Token issued by Lime Connect for the current operator session. The token is signed with HMAC SHA-256 using a shared secret that is generated in Lime Admin and configured in both Lime Connect and Lime CRM's application config. Lime CRM rejects tokens with an invalid signature or an expired timestamp. The token contains no personal data.
Clickjacking protection (flow 4). The portal page is served with a Content-Security-Policy: frame-ancestors header, so it can only be embedded by https://app.lime-connect.com (configurable). The iframe also ignores browser messages from any other origin.
Read-only portal. The Portal runs as the configured portal API user (userlike@lime by default) and only reads data that this user has access to. Nothing is created or updated.
Lime Connect API token (flow 3). Stored as a secret in Lime CRM's application config (on-premise: application_config.yaml, Lime Cloud: Cloud Admin). It is only used by the task handler for outbound requests and is never exposed to browsers.
Operator access to Lime CRM (flow 5). Links from Lime Connect to Lime CRM go through the normal Lime CRM login. Operators only see what their own Lime CRM user is allowed to see.
Data at rest. Conversation transcripts, contact details and imported media files are stored in the Lime CRM database and file storage, in the customer's environment. No CRM data is stored by Lime Connect as part of this integration.
Logging. No personal data is logged by the integration. See GDPR.