--- title: "3CX CRM XML Template Structure & Specification Guide" description: "# 3CX CRM XML TEMPLATE INTEGRATION SPECIFICATION - **Document ID:** `KB-3CX-CRM-XML-01` - **Target Version:** [3CX v18 / v20](https://www.3cx.com/blog/releases/u9-web-client-smarter-ai/) (Server-Side Integration) - **Category:** Middleware & API Development ### 1. Introduction & Core Architecture 3CX uses a *server-side* integration engine that executes…" url: "https://solusipbx.id/en/pusat-bantuan/3cx-crm-xml-template-integration-spec/" updated: "2026-10-02" category: Developer --- # 3CX CRM XML Template Structure & Specification Guide # 3CX CRM XML TEMPLATE INTEGRATION SPECIFICATION - **Document ID:** `KB-3CX-CRM-XML-01` - **Target Version:** [3CX v18 / v20](https://www.3cx.com/blog/releases/u9-web-client-smarter-ai/) (Server-Side Integration) - **Category:** Middleware & API Development ### 1. Introduction & Core Architecture 3CX uses a *server-side* integration engine that executes instructions from a custom XML configuration file. This engine handles phone number lookups (*contact lookup*), call history logging (*call journaling*), message interaction reporting (*chat journaling*), and even complex token authorization flows (OAuth2). The engine supports three scenario types (`Type`): 1. **REST**: Interaction via HTTP REST API (returns JSON- or XML-formatted data). 2. **SQLDatabase**: Direct relational database queries (supports MySQL, PostgreSQL, and Microsoft SQL Server). 3. **NoSQLDatabase**: Non-relational database command execution (supports MongoDB). ### 2. Root Element Structure & Base Attributes Every template must be wrapped inside a `` root tag with the following attribute declarations: XML ``` ``` - **`Name`**: A unique identifier string for the template, shown in the 3CX Admin Console UI. - **`Version`**: An integer marking the integration schema version (used by the system for update management). - **`Country`**: The app's target country code (required, though it isn't currently evaluated by the core functionality). - **`SupportsEmojis`**: A boolean value (`true`/`false`). If set to `false`, emoji characters in chat messages will be automatically filtered out before being sent to your CRM system. ### 3. Core Component Configuration Elements #### 3.1 The `` Element Used to normalize the format of the incoming phone number string (*caller ID*) so it matches the lookup index format in your CRM database. - **`Prefix`** *(Enum)*: Determines how the number's leading characters are manipulated: - `AsIs`: Keeps the original string unmodified (example: `+62` or `00` stays as is). - `Off`: Strips out all leading marker characters (such as the `+` symbol or the digits `00`). - `Plus`: Forces the leading character to be a plus sign (`+`). - `Zeros`: Forces the leading characters to be double zero (`00`). - **`MaxLength`** *(Expression)*: Trims the string from the right, keeping only the last $N$ digits. This value can be set dynamically using the `[MaxLength]` variable expression to pull the global parameter from *3CX Console > Contacts > Options*. #### 3.2 The `` Element Configures the engine's concurrency limits for requests to the external server. - **`MaxConcurrentRequests`**: Limits the maximum number of parallel simultaneous queries allowed to be sent to the CRM API (prevents *rate limiting*). A single phone call lookup session — even one that runs several parallel lookup scenarios for *Lead*, *Contact*, or *Account* — is counted as a single request unit. #### 3.3 The `` Element Holds a collection of custom `` elements whose values are entered dynamically by the administrator through the 3CX Web Console UI. These parameter values can be referenced anywhere in the template using square-bracket notation: `[ParameterName]`. - **Parameter Data Type (`Type`)**: Supports `String`, `Password` (hidden text input), `Boolean` (checkbox), `Integer`, `Double`, `DateTime`, and `OAuth` (triggers an interactive OAuth2 authorization flow button). - **Editor Control Attribute**: The `Editor` attribute is either `String` (max 100 characters) or `Sql` (max 1000 characters). For `OAuth`-type parameters, you must also include the `RequestUrl`, `RequestUrlParameters`, and `ResponseScenario` attributes. #### 3.4 The `` Element Configures how security tokens are injected into the HTTP header. Supports three configurations: 1. `Type="No"`: No built-in authentication — used when the CRM handles the token manually inside the URL's query string. 2. `Type="Basic"`: Automatically injects the `Authorization: Basic ` HTTP header on every request, based on the value from the child node ``. 3. `Type="Scenario"`: Used for dynamic token schemes (such as an OAuth2 Access Token). This option triggers a dedicated scenario to fetch a fresh token, detect its *expiry time*, and store it in runtime memory state. ### 4. Scenario Handling Based on Reserved System IDs The `Id` attribute on the `` tag controls when and how a block of instructions is executed by the 3CX telephony core engine: - **`Id=""` (Empty String)**: The primary default scenario for matching a contact based on the incoming phone number (*Inbound Call Contact Lookup*). - **`Id="LookupByEmail"`**: Automatically triggered when the system requests an entity lookup using an email address. - **`Id="SearchContacts"`**: Used for free-text search functionality across data columns (Name, Company, Email, etc.) from the 3CX client application. - **`Id="ReportCall"`**: Executed automatically the instant a phone call session ends, to log the call history (*Call Journaling*). - **`Id="ReportChat"`**: Executed automatically once a custom message interaction session finishes (*Chat Journaling*). - **`Id="CreateContactRecordFromClient"`**: Triggers the creation of a new contact record in the CRM directly from an action button in the 3CX client application. - **`Id="LookupFromCFD_[Entity]_[Type]"`**: Used specifically to pass back a *raw data payload* (JSON/XML) directly to the Call Flow Designer (CFD) application. > ⚠️ **IMPORTANT FOR DEVELOPERS (JOURNALING RULES):** > > > > Specifically for the `ReportCall` and `ReportChat` scenarios, the 3CX engine does not expect any data to be returned (*output data return*). Because of this, the XML structure for these scenarios **must not** include closing nodes such as ``, ``, or ``. Simply declare the main interaction elements such as ``, ``, or ``. ### 5. Response Data Processing Pipeline (REST) The API response processing cycle in a REST scenario follows 4 sequential stages (*sequential pipeline*): 1. **``**: Constructs the HTTP Request (URL, Method `GET`/`POST`/`PUT`, Headers, and Request Body). 2. **``**: Maps the base of the external response's object array (the `Type="json"` attribute uses JSONPath syntax, while `Type="xml"` uses XPath syntax). A `` element can be nested inside it to filter by a specific property condition. 3. **``**: Extracts specific property values from the filtered array results and maps them into local runtime variables. XML ``` ``` 4. **``**: Passes the local runtime variable values back to the 3CX PBX core. For a contact lookup scenario, the required properties that must be mapped include: `ContactUrl`, `FirstName`, `LastName`, `CompanyName`, `Email`, and `PhoneBusiness`. - **Chained Scenarios**: Developers can recursively trigger a follow-up scenario per data row by adding a `Next` attribute to the output tag, for example: ``. The child scenario automatically inherits all the variable state captured in its parent scenario. ### 6. Expression Syntax Rules & Special Character Escaping 3CX's XML expression parsing engine enforces strict rules around reserved system characters. If a literal string inside an expression attribute contains special characters, you must escape them as follows: - The opening square bracket `[` **must be changed to**: `{{` - The closing square bracket `]` **must be changed to**: `}}` - The double-quote character `"` **must be changed to**: `^^` *Note for SQL Developers:* Specifically when writing variable bindings inside a `SQLDatabase` scenario, you must not reference variable values using square-bracket notation `[Variable]` — instead, use SQL's native bound-parameter prefix, the `@` symbol (Example: `WHERE phone = @NumberToLookup`). ### 7. Testing & Debugging Workflow The main **3CX System Service** is responsible for loading all XML schema files into RAM when the PBX first boots up. As a result, every time a developer changes a line of code in the XML template file, the **3CX System Service must be fully restarted** for the updated schema to be picked up. To test the integration's functionality without placing an actual call (*dummy testing execution*), use the interactive **"Test"** button located on the admin web management page: `3CX Admin Console > Settings > CRM Integration`. Also read: [Call Center Hospitality for Multi-Country Guest Service with 3CX, CRM & AI Agent](https://solusipbx.com/call-center-hospitality/) (Indonesian)