Diese Referenz richtet sich an Entwickler, die Order Messenger erweitern: Template-Überschreibungen, Styling, Hooks, die REST-API und die PHP-Services. Einrichtung und tägliche Nutzung beschreibt die Benutzerdokumentation. Alles Folgende gilt für Version 4 des Plugins; die kostenlose und die Premium-Version teilen sich diesen Code.
Architektur im Überblick
Das Plugin liegt im Namespace U2Code\OrderMessenger. Services werden in einem Container registriert und über typisierte Getter abgerufen:
use U2Code\OrderMessenger\Core\ServiceContainer;
$container = ServiceContainer::getInstance();
$container->getMessageService(); // write messages
$container->getMessageRepository(); // read and query messages
$container->getAttachments(); // uploads and the download endpoint
$container->getNotifications(); // email notifications
$container->getScheduler(); // Action Scheduler jobs
$container->getPermissions(); // who may do what
$container->getLicense(); // free / premium
$container->getSettings(); // the WooCommerce settings tab
Nachrichten sind Zeilen der Tabelle {prefix}wc_order_messages. Datumsangaben werden in UTC gespeichert.
| Spalte | Bedeutung |
|---|---|
id | ID der Nachricht. |
order_id | Die Bestellung, zu der die Unterhaltung gehört. |
user_id | Die Kunden-ID der Bestellung (0 bei Gästen). |
sender_id | Der Benutzer, der die Nachricht geschrieben hat; 0 bei Systemnachrichten. |
attachment_id | Mediathek-ID des Anhangs oder NULL. |
message | Reiner Text, bis zu 3000 Zeichen. |
type | 0 Team, 1 Kunde, 2 Bestellhinweis, 3 Statusänderung, 4 geplant (wartend), 5 geplant (gesendet). |
date_sent / date_read | UTC-Zeitstempel; date_read ist NULL, solange die Nachricht ungelesen ist. |
is_notified | 1, sobald eine E-Mail versendet wurde (oder keine nötig war). |
data | JSON: scheduled_date, notify, from/to bei Statusänderungen, note_id, purchase_product_id. |
Nachrichten per Code senden und lesen
use U2Code\OrderMessenger\Core\ServiceContainer;
use U2Code\OrderMessenger\Entity\MessageType;
use U2Code\OrderMessenger\Services\MessageException;
$container = ServiceContainer::getInstance();
$order = wc_get_order( 123 );
try {
// From the store to the customer. Sender 0 shows the store signature.
$container->getMessageService()->sendAdminMessage( $order, get_current_user_id(), 'Your parcel ships tomorrow.', array(
'notify' => true, // email the customer
'attachment_id' => 0, // a media library id
'schedule_at' => new DateTimeImmutable( '+2 days 10:00', wp_timezone() ), // omit to send now
) );
// From the customer (permissions are checked: the customer, or a guest with the order key).
$container->getMessageService()->sendCustomerMessage( $order, $order->get_customer_id(), 'Thanks!' );
// A system entry, for example from a shipping plugin.
$container->getMessageService()->createSystemMessage( $order, MessageType::service(), 'Shipped with DHL, tracking 123456.', array( 'tracking' => '123456' ) );
} catch ( MessageException $e ) {
// $e->getCode() is the HTTP status the REST API would answer with (400, 403, 429).
error_log( $e->getMessage() );
}
// Reading.
$repository = $container->getMessageRepository();
$messages = $repository->getForOrder( $order->get_id(), array( 'context' => 'admin', 'limit' => 50 ) );
$unread = $repository->countUnreadForOrder( $order->get_id(), 'admin' ); // waiting for the team
$repository->markReadForOrder( $order->get_id(), 'admin' );
foreach ( $messages as $message ) {
$message->getMessage(); // text
$message->getMessageType()->isCustomer(); // who wrote it
$message->getDateSent(); // DateTimeImmutable in the site timezone
$message->getAttachment(); // MessageAttachment or null
}
context ist admin für die Ansicht des Teams und customer für die des Kunden; der Kontext bestimmt, welche Nachrichtentypen enthalten sind und wessen Lesestatus gemeint ist.
Templates überschreiben
Die Frontend-Templates liegen im Ordner views/frontend des Plugins und lassen sich in Ihr Theme unter order-messenger-for-woocommerce/ kopieren, wobei der Pfad unterhalb von frontend/ erhalten bleibt:
your-theme/order-messenger-for-woocommerce/my-account/messenger.php
your-theme/order-messenger-for-woocommerce/my-account/dialogs.php
your-theme/order-messenger-for-woocommerce/my-account/no-access.php
your-theme/order-messenger-for-woocommerce/my-account/no-conversations.php
your-theme/order-messenger-for-woocommerce/message/message-attachment.php
your-theme/order-messenger-for-woocommerce/message/message-types/admin-message.php
your-theme/order-messenger-for-woocommerce/message/message-types/customer-message.php
your-theme/order-messenger-for-woocommerce/message/message-types/service-message.php
your-theme/order-messenger-for-woocommerce/message/message-types/order-status-message.php
your-theme/order-messenger-for-woocommerce/message/message-types/scheduled-message.php
Das Template der Unterhaltung erhält $order, $orderId, $orderKey, $messages (älteste zuerst), $totalMessages, $hasMore, $canSend, $filesEnabled, $config (die Data-Attribute, die das Skript liest) und $presenter. Nachrichten-Templates erhalten $message, $order und $orderKey. Behalten Sie die Attribute data-om-* und die Klassen om-* bei, wenn das Skript weiter funktionieren soll: Über sie sendet es Nachrichten, fragt neue ab und öffnet die Lightbox.
Die Benachrichtigungs-E-Mails sind reguläre WooCommerce-Templates. Kopieren Sie sie aus dem Ordner views/emails des Plugins nach your-theme/woocommerce/emails/: admin-messenger-notification.php, customer-messenger-notification.php, partials/messages.php und die Varianten in plain/.
Die Template-Suche lässt sich mit dem Filter order_messenger/template/location umleiten (Argumente: aufgelöste Datei, Template-Name).
Styling
Die Unterhaltung auf der Kundenseite ist bewusst Theme-neutral: Sie übernimmt die Schrift der Seite, leitet ihre Linien und Flächen aus der aktuellen Textfarbe ab und verwendet die Eingabefelder und Buttons des Themes. Die benannten Paletten setzen diese Custom Properties auf .om-messenger und .om-conversations; für ein eigenes Aussehen können Sie sie selbst setzen:
.om-messenger {
--om-primary-color: #2b6cb0; /* store bubbles */
--om-primary-color-darker: #245a93;
--om-primary-text-color: #ffffff;
--om-secondary-color: #f1f5f9; /* customer bubbles */
--om-secondary-color-darker: #e2e8f0;
--om-secondary-text-color: #0f172a;
}
Nützliche Klassen: .om-messenger (das gesamte Widget), .om-message mit den Modifiern --customer, --admin, --system, --own, .om-message__bubble, .om-message__meta, .om-attachment, .om-messenger__composer, .om-badge und .om-nav-badge (Zähler für ungelesene Nachrichten), .om-conversations (die Liste in Mein Konto). Theme-spezifische Regeln lassen sich mit dem Filter order_messenger/frontend/theme_integration_css hinzufügen; auf diesem Weg gibt das Plugin Storefront ein Chat-Symbol im Kontomenü.
Hooks
Alle Hook-Namen beginnen mit order_messenger/. Hier sind die nützlichsten aufgeführt; die vollständige Liste finden Sie per grep im Plugin-Code.
Actions
| Action | Argumente | Wann |
|---|---|---|
messages/message_created | Message $message | Eine Nachricht wurde gespeichert (beliebiger Typ). |
messages/message_updated | Message $message | Eine Nachricht wurde geändert (Lesestatus, Veröffentlichung). |
messages/message_deleted | Message $message | Nachdem eine Nachricht gelöscht wurde; messages/before_delete wird davor ausgelöst. |
messages/changed | ?Message $message, int $orderId | In der Unterhaltung einer Bestellung hat sich etwas geändert; die Zähler für ungelesene Nachrichten hängen sich hier ein. |
messages/scheduled_message_published | Message $published, Message $scheduled | Eine geplante Nachricht wurde versendet. |
notifications/sent | int $orderId, Message[] $messages, string $side, bool $sent | Es wurde versucht, eine Benachrichtigungs-E-Mail zu senden; $side ist admin oder customer. |
attachments/uploaded | int $attachmentId, WC_Order $order, array $result | Ein Kunden-Upload wurde gespeichert. |
admin/product_page/messenger_tab_begin / _end | int $productId | Felder zum Tab „Order Messenger“ des Produkts hinzufügen. |
upgraded | string $from, string $to | Nach einer Datenmigration. |
rest/register_routes | string $namespace | Eigene Routen neben denen des Plugins registrieren. |
Berechtigungen
| Filter | Argumente | Zweck |
|---|---|---|
permissions/capability | string $capability | Die Berechtigung, die Teammitglieder kennzeichnet (Standard: manage_order_messenger). |
permissions/can_manage | bool $allowed, int $userId | Ob ein Benutzer zum Team gehört. |
permissions/userCanViewMessenger | bool $allowed, WC_Order $order, int $userId | Ob ein Kunde eine Unterhaltung öffnen darf. |
permissions/userCanSendMessage | bool $allowed, int $userId, WC_Order $order, string $text | Ob ein Kunde schreiben darf. |
permissions/userCanSendAdminMessage | bool $allowed, int $userId, WC_Order $order | Ob ein Teammitglied zu dieser Bestellung schreiben darf. |
permissions/userCanDeleteMessage / userCanUnreadMessage | bool $allowed, Message $message | Aktionen für Nachrichten. |
settings/allowed_roles_to_manage_admin_messenger/default | string[] $roles | Standard-Teamrollen. |
Nachrichten und Inhalte
| Filter | Argumente | Zweck |
|---|---|---|
messages/before_saving_customer_message | Message $message, WC_Order $order, ?array $file | Eine Kundennachricht ändern, bevor sie gespeichert wird. |
messages/before_saving_admin_message | Message $message, $request, array $customData, WC_Order $order, int $attachmentId | Eine Teamnachricht ändern, bevor sie gespeichert wird. |
messages/before_saving_system_message | Message $message, WC_Order $order | Einen automatischen Eintrag ändern. |
messages/before_publishing_scheduled_message | Message $published, Message $scheduled | Eine geplante Nachricht beim Versand ändern. |
message/sender_name | string $name, Message $message | Der Name, der bei einer Nachricht angezeigt wird. |
message/formatted_text | string $html, ?string $text | Der gerenderte Text (Links, Zeilenumbrüche). |
message/message_template_page | string $path, string $place, Message $message | Das Template, das für eine Nachricht verwendet wird. |
system_messages/post_order_note | bool $post, $note, WC_Order $order | Bestimmte Bestellhinweise überspringen. |
config/rate_limit | array{limit:int, window:int} | Kundennachrichten pro Zeitfenster (standardmäßig 30 pro 10 Minuten). |
notification/email_delay | int $minutes | Die Verzögerung der Sammel-E-Mail. |
config/message_types_customer_should_be_notified / _admin_ | int[] $types | Welche Nachrichtentypen bei Team und Kunde jeweils E-Mails auslösen. |
Einstellungen, Templates und Frontend
| Filter | Argumente | Zweck |
|---|---|---|
settings/sections | SectionAbstract[] $sections | Einen Einstellungsbereich hinzufügen. |
settings/settings | array $fields, SectionAbstract $section | Die Felder eines Bereichs ändern. |
settings/available_themes | array $palettes | Eine Farbpalette hinzufügen (Name → Custom Properties). |
settings/available_file_types | array $types | Einen Anhangstyp hinzufügen (Schlüssel → title, mime, ext). |
config/get_{key} | mixed $value, array $args | Jede Einstellung durchläuft einen nach ihr benannten Filter, z. B. config/get_polling_interval. |
template/location | string $file, string $template | Von wo ein Template geladen wird. |
frontend/conversation_config | array $config, WC_Order $order | Die Data-Attribute, die das Frontend-Skript liest. |
frontend/show_on_order_received | bool $show, WC_Order $order | Die Unterhaltung auf der Bestellbestätigungsseite anzeigen. |
frontend/theme_integration_css | string $css | Zusätzliches CSS, das mit dem Frontend-Stylesheet ausgegeben wird. |
order/customer_name, order/summary | string|array, WC_Order $order | Wie eine Bestellung in der Admin-App und in E-Mails beschrieben wird. |
attachments/sideload | bool $sideload, array $file, ?WC_Order $order | Dateien akzeptieren, die keine Browser-Uploads sind (Importe, Tests). |
rest/features | array $features, WC_Order $order, bool $isManager | Was der Eingabebereich für eine Bestellung und einen Betrachter anbietet. |
rest/message | array $data, Message $message, string $context | Die JSON-Struktur einer Nachricht. |
license/can_use_premium_code | bool $premium | Premium-Funktionen an oder aus. In der Version von WooCommerce.com immer true. |
Beispiele
// Post a message when an order is completed.
add_action( 'woocommerce_order_status_completed', function ( $order_id ) {
$order = wc_get_order( $order_id );
\U2Code\OrderMessenger\Core\ServiceContainer::getInstance()->getMessageService()
->sendAdminMessage( $order, 0, 'Your order is complete. Thank you for shopping with us!', array( 'notify' => true ) );
} );
// Show a role name instead of the team member's name.
add_filter( 'order_messenger/message/sender_name', function ( $name, $message ) {
return $message->getMessageType()->isFromStore() ? 'Support team' : $name;
}, 10, 2 );
// Allow SVG attachments.
add_filter( 'order_messenger/settings/available_file_types', function ( $types ) {
$types['svg'] = array( 'title' => 'SVG', 'mime' => 'image/svg+xml', 'ext' => 'svg' );
return $types;
} );
// Keep the conversation off the order confirmation page.
add_filter( 'order_messenger/frontend/show_on_order_received', '__return_false' );
// Let customers write only while the order is not completed.
add_filter( 'order_messenger/permissions/userCanSendMessage', function ( $allowed, $user_id, $order ) {
return $allowed && ! $order->has_status( 'completed' );
}, 10, 3 );
REST-API
Namespace order-messenger/v1. Anfragen von der Website selbst authentifizieren sich mit dem WordPress-Cookie und einem Header X-WP-Nonce (Nonce wp_rest); externe Clients verwenden Anwendungspasswörter. Kunden erreichen nur ihre eigenen Bestellungen; Gäste übergeben den Bestellschlüssel als key. Team-Routen erfordern die Berechtigung manage_order_messenger.
| Route | Methode | Parameter |
|---|---|---|
/orders/{id} | GET | key (Gäste). Liefert die Bestellübersicht, die Summen, die Zahl ungelesener Nachrichten und die features, die der Eingabebereich anbieten darf. |
/orders/{id}/messages | GET | before_id, after_id, per_page (≤ 200), render = json oder html. Neueste Seite zuerst; mit after_id fragen die Live-Aktualisierungen ab. |
/orders/{id}/messages | POST | message, file (multipart, Kunden), attachment_id (Team), notify, schedule_at (Y-m-d\TH:i:s, Zeit der Website), custom_data, render. Antwortet mit 201 und der Nachricht. |
/orders/{id}/read | POST | Markiert die Unterhaltung für die Seite des Betrachters als gelesen. |
/messages/{id} | DELETE | Nur für das Team. |
/messages/{id}/unread | POST | Nur für das Team. |
/conversations | GET | Nur für das Team. search, unread_only, page, per_page (≤ 100). |
/unread-count | GET | Nur für das Team. Ungelesene Kundennachrichten aus allen Bestellungen. |
// From a page on the same site.
const response = await fetch( wpApiSettings.root + 'order-messenger/v1/orders/123/messages', {
method: 'POST',
credentials: 'same-origin',
headers: { 'Content-Type': 'application/json', 'X-WP-Nonce': wpApiSettings.nonce },
body: JSON.stringify( { message: 'Hello from the storefront' } ),
} );
const { message } = await response.json();
Die Routen von Version 3 (/get/{limit}/{offset}, /send, /sendAdmin, /delete/{id}, /unread/{id}) antworten weiterhin im alten Format, für Integrationen, die darauf angewiesen sind.
Hintergrundaufgaben
Geplante Nachrichten und Sammel-E-Mails laufen über den Action Scheduler von WooCommerce in der Gruppe order-messenger:
| Hook | Zeitplan |
|---|---|
order_messenger/publish_scheduled_message | Eine Action pro geplanter Nachricht, zum jeweiligen Zeitpunkt; Argument message_id. |
order_messenger/publish_due_scheduled_messages | Alle 10 Minuten; veröffentlicht alles, was verpasst wurde (Filter scheduler/catch_up_interval). |
order_messenger/send_notification_digests | Alle paar Minuten, solange Sammel-E-Mails aktiviert sind (Filter notifications/digest_interval). |
Dateianhänge
Kunden-Uploads laufen durch wp_handle_upload() mit den in den Einstellungen erlaubten Typen, erhalten zufällige Namen, werden unter uploads/order-messenger/ hinter einer Deny-Regel in .htaccess gespeichert und als private, mit der Bestellung verknüpfte Elemente der Mediathek registriert. Anhänge des Teams sind normale Dateien der Mediathek. Jede Datei wird über admin-post.php?action=om_attachment ausgeliefert: Dort wird geprüft, ob der Betrachter zur Unterhaltung gehört (Kunde, Gast mit Bestellschlüssel oder Team), und die Datei wird mit einer an den Anhang gebundenen Nonce gestreamt. Verwenden Sie AttachmentService::getDownloadUrl( $attachment, $size, $orderKey ), um einen solchen Link zu erzeugen, und den Filter attachments/sideload, um Dateien einzuspeisen, die keine Browser-Uploads sind.
Shortcodes und Endpunkte
| Element | Details |
|---|---|
[order_chatroom order_id=""] | Eine Unterhaltung; greift ersatzweise auf die Query-Variable view-order oder messenger zurück. |
[order_chatrooms limit="10" current_page="1"] | Die Unterhaltungen des aktuellen Kunden. |
[order_chatroom_unread_messages_count order_id=""] | Zahl ungelesener Nachrichten einer Bestellung oder, wenn leer, des Kunden. |
| Endpunkte in Mein Konto | messages (die Liste) und messenger/{order-id} (eine Unterhaltung), registriert über woocommerce_get_query_vars. |
| Admin-Seite | admin.php?page=om-messenger&order={id} öffnet eine Unterhaltung auf der Messenger-Seite. |
JavaScript
Die Admin-App ist eine React-Anwendung auf Basis von @wordpress/components; ihre Konfiguration steht in window.omMessengerConfig (filterbar über admin/app_config). Das Frontend-Skript kommt ohne Abhängigkeiten aus: Jedes Element [data-om-messenger] erhält eine Conversation-Instanz, verfügbar als element.omConversation, mit poll(), loadOlder() und send(). window.omFrontendConfig enthält das Abfrageintervall und die Zahl ungelesener Nachrichten für das Badge im Kontomenü.
Kostenlose und Premium-Version
Die Version von WordPress.org enthält das Freemius SDK, die Version von WooCommerce.com nicht. LicenseManager::canUsePremiumCode() ist die einzige Stelle, die das SDK abfragt, und der Filter license/can_use_premium_code setzt darauf auf. Dateianhänge sind die Premium-Funktion: Im kostenlosen Plan werden Kunden-Uploads mit 403 abgelehnt, und im Eingabebereich des Teams erscheint ein gesperrtes Bedienelement; alles andere funktioniert in beiden Versionen gleich.