3CX CRM XML TEMPLATE INTEGRATION SPECIFICATION #

• Document ID: KB-3CX-CRM-XML-01

• Target Version: 3CX v18 / v20 (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 <Crm> root tag with the following attribute declarations:

<Crm Name="Custom_CRM_REST" Version="1" Country="ID" SupportsEmojis="true">
    </Crm>

• 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 <Number> 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 <Connection> 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 <Parameters> Element #

Holds a collection of custom <Parameter> 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 <Authentication> 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 <base64> HTTP header on every request, based on the value from the child node <Value>.

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 <Scenario> 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 <Rules>, <Variables>, or <Outputs>. Simply declare the main interaction elements such as <Request>, <Query>, or <Command>.

5. Response Data Processing Pipeline (REST) #

The API response processing cycle in a REST scenario follows 4 sequential stages (sequential pipeline):

1. <Request>: Constructs the HTTP Request (URL, Method GET/POST/PUT, Headers, and Request Body).

2. <Rules>: Maps the base of the external response’s object array (the Type="json" attribute uses JSONPath syntax, while Type="xml" uses XPath syntax). A <Filter> element can be nested inside it to filter by a specific property condition.

3. <Variables>: Extracts specific property values from the filtered array results and maps them into local runtime variables.

   XML

   <Variables>
       <Variable Name="ContactID" Path="id" />
       <Variable Name="Company" Path="company.name" />
   </Variables>
   

4. <Outputs>: 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: <Outputs Next="GetContactDetailsByID"/>. 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 (Indonesian)