What does it do? 

Universal Messenger lets editors compose a newsletter as a normal TYPO3 page, using the site's usual content elements, and send it through the Universal Messenger webservice.

• A dedicated Newsletter page type carries the newsletter content and a selectable Universal Messenger channel.
• A backend module renders a per-language preview of the newsletter and triggers a TEST or LIVE dispatch to Universal Messenger.
• A console command imports the newsletter channels that are configured in Universal Messenger, so editors always see the current channel list in the page properties.
• Fluid ViewHelpers and dedicated content elements (for example a personalization control structure) integrate with Universal Messenger's placeholder and templating conventions.
• Shipped TypoScript renders the newsletter content with the Foundation for Emails 2 framework and inlines the resulting CSS, so the newsletter HTML matches what most email clients render correctly.

Requirements 

Version matrix 

The 2.x line also carries the umopen/cmsbs.open authentication token required by Universal Messenger servers older than 7.56.0. See the SDK compatibility notes for details.

Composer 

Install the extension via Composer:

composer require netresearch/universal-messenger

Activate the extension in the Admin Tools > Extensions backend module if your installation does not activate required extensions automatically.

Update the database structure 

The extension adds the newsletter page type and its channel-selection field to the pages table. Open Admin Tools > Maintenance and run Analyze Database Structure to add the missing fields.

Site configuration 

The extension ships its default TypoScript two ways, so no manual "include static template" step is required for either kind of site:

• Classic sites (sys_template based) receive the default TypoScript automatically through a global TypoScript registration.
• Site Set based sites load the same TypoScript by adding netresearch/universal-messenger to the site's Set dependencies.

dependencies:
  - netresearch/universal-messenger

Two additional static templates provide the Fluid rendering of the newsletter content and an example newsletter page template. Include them as described in TypoScript.

After installation, continue with Configuration to set up the Universal Messenger webservice credentials.

API endpoint 

To access the Universal Messenger API, store the connection configuration in additional.php, under TYPO3_CONF_VARS > EXTENSIONS > universal_messenger (note the spelling, it uses the extension key, not the Composer package name).

// The Universal Messenger API endpoint
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['universal_messenger'] = array_merge(
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['universal_messenger'] ?? [],
    [
        'apiUrl'    => 'YOUR-API-URL',
        'apiKey'    => 'YOUR-API-KEY',
        'apiSecret' => 'YOUR-API-SECRET',
    ]
);

Create the API key in the Universal Messenger backend, under the API key management for your account.

API logging 

To log Universal Messenger API requests and responses, enable enableLogging (see Extension configuration) and add a log writer configuration to ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['LOG']['Netresearch']['UniversalMessenger']['writerConfiguration'] = [
    \Psr\Log\LogLevel::DEBUG => [
        \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
            'logFileInfix' => 'universal_messenger',
        ],
    ],
];

General 

Webservice 

Expert 

Fluid content elements 

Provides the Fluid rendering used for the newsletter view and the newsletter container template. Without it, the backend preview and the dispatch to Universal Messenger have no template to render.

On classic (sys_template based) sites, go to the Web > Template module, select Edit TypoScript Record, then Edit the whole TypoScript record. On the Advanced Options tab, add Universal Messenger: Fluid Content Elements to the list of included static templates.

On Site Set based sites, the same TypoScript is already imported by the netresearch/universal-messenger Set, no extra step is needed.

Example newsletter template 

Provides an example newsletter backend layout and page template as a starting point for a project-specific newsletter design.

On classic sites, include the static template `Universal Messenger: Example Newsletter Template` the same way as above. On Site Set based sites it is imported together with the Fluid content elements template.

Open the page where the layout should apply, switch to the page properties Resources tab, and add `Universal Messenger: Backend Layout to the :guilabel:Page TSconfig selection. The layout is then selectable on the page's :guilabel:Layout` tab.

Basic concepts 

Universal Messenger newsletter channels are imported into TYPO3 as generic channels, the configured test or live suffix (see Test and live channels) is cut off during import, regardless of upper or lower case.

A newsletter page is therefore always assigned to a single generic channel name. The split between a TEST and a LIVE dispatch happens only when the newsletter is actually sent, in the backend module described in Backend module.

Each imported newsletter channel can carry additional, per-channel settings. A re-import does not overwrite them:

These settings are sent to the Universal Messenger API together with the newsletter content.

Importing newsletter channels 

The console command universal-messenger:newsletter-channels:import imports the newsletter channels currently configured in Universal Messenger.

vendor/bin/typo3 universal-messenger:newsletter-channels:import

Configure it as a Scheduler task (Execute console commands) to keep the channel list in TYPO3 in sync with Universal Messenger automatically, for example once a day.

Control structure 

In the content element's settings, enter the corresponding control structure (for example a personalized salutation) that Universal Messenger substitutes when the newsletter is sent. Also specify the alternative text shown when the newsletter is opened in a web view, where personalization is not available.

Both the control structure and the alternative text can be formatted using the RTE editor and adapted to the newsletter's layout.

tt_content.control_structure.stdWrap.wrap = <div class="component"><div class="component__content">|</div></div>
tt_content.control_structure.stdWrap.wrap.if.value.data = GP:type
tt_content.control_structure.stdWrap.wrap.if.equals = 1715682913
tt_content.control_structure.stdWrap.wrap.if.negate = 1

Initialization 

To use the extension's ViewHelpers in a Fluid template, declare their namespace:

xmlns:um="http://typo3.org/ns/Netresearch/UniversalMessenger/ViewHelpers"

um:format.placeholder 

Marks a value as a Universal Messenger placeholder using curly brackets, so it can be passed as a literal placeholder inside a URL, for example the unsubscribe link of a newsletter.

<f:link.external uri="https://newsletter.example.org/unsubscribe?identifier={um:format.placeholder(value: 'identifier')}">
    Unsubscribe
</f:link.external>

This renders a URL of the form:

https://newsletter.example.org/unsubscribe?identifier={identifier}

Universal Messenger replaces {identifier} with the actual value when the newsletter is sent.