Order Messenger for WooCommerce

Dokumentation für Entwickler

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.

SpalteBedeutung
idID der Nachricht.
order_idDie Bestellung, zu der die Unterhaltung gehört.
user_idDie Kunden-ID der Bestellung (0 bei Gästen).
sender_idDer Benutzer, der die Nachricht geschrieben hat; 0 bei Systemnachrichten.
attachment_idMediathek-ID des Anhangs oder NULL.
messageReiner Text, bis zu 3000 Zeichen.
type0 Team, 1 Kunde, 2 Bestellhinweis, 3 Statusänderung, 4 geplant (wartend), 5 geplant (gesendet).
date_sent / date_readUTC-Zeitstempel; date_read ist NULL, solange die Nachricht ungelesen ist.
is_notified1, sobald eine E-Mail versendet wurde (oder keine nötig war).
dataJSON: 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

ActionArgumenteWann
messages/message_createdMessage $messageEine Nachricht wurde gespeichert (beliebiger Typ).
messages/message_updatedMessage $messageEine Nachricht wurde geändert (Lesestatus, Veröffentlichung).
messages/message_deletedMessage $messageNachdem eine Nachricht gelöscht wurde; messages/before_delete wird davor ausgelöst.
messages/changed?Message $message, int $orderIdIn der Unterhaltung einer Bestellung hat sich etwas geändert; die Zähler für ungelesene Nachrichten hängen sich hier ein.
messages/scheduled_message_publishedMessage $published, Message $scheduledEine geplante Nachricht wurde versendet.
notifications/sentint $orderId, Message[] $messages, string $side, bool $sentEs wurde versucht, eine Benachrichtigungs-E-Mail zu senden; $side ist admin oder customer.
attachments/uploadedint $attachmentId, WC_Order $order, array $resultEin Kunden-Upload wurde gespeichert.
admin/product_page/messenger_tab_begin / _endint $productIdFelder zum Tab „Order Messenger“ des Produkts hinzufügen.
upgradedstring $from, string $toNach einer Datenmigration.
rest/register_routesstring $namespaceEigene Routen neben denen des Plugins registrieren.

Berechtigungen

FilterArgumenteZweck
permissions/capabilitystring $capabilityDie Berechtigung, die Teammitglieder kennzeichnet (Standard: manage_order_messenger).
permissions/can_managebool $allowed, int $userIdOb ein Benutzer zum Team gehört.
permissions/userCanViewMessengerbool $allowed, WC_Order $order, int $userIdOb ein Kunde eine Unterhaltung öffnen darf.
permissions/userCanSendMessagebool $allowed, int $userId, WC_Order $order, string $textOb ein Kunde schreiben darf.
permissions/userCanSendAdminMessagebool $allowed, int $userId, WC_Order $orderOb ein Teammitglied zu dieser Bestellung schreiben darf.
permissions/userCanDeleteMessage / userCanUnreadMessagebool $allowed, Message $messageAktionen für Nachrichten.
settings/allowed_roles_to_manage_admin_messenger/defaultstring[] $rolesStandard-Teamrollen.

Nachrichten und Inhalte

FilterArgumenteZweck
messages/before_saving_customer_messageMessage $message, WC_Order $order, ?array $fileEine Kundennachricht ändern, bevor sie gespeichert wird.
messages/before_saving_admin_messageMessage $message, $request, array $customData, WC_Order $order, int $attachmentIdEine Teamnachricht ändern, bevor sie gespeichert wird.
messages/before_saving_system_messageMessage $message, WC_Order $orderEinen automatischen Eintrag ändern.
messages/before_publishing_scheduled_messageMessage $published, Message $scheduledEine geplante Nachricht beim Versand ändern.
message/sender_namestring $name, Message $messageDer Name, der bei einer Nachricht angezeigt wird.
message/formatted_textstring $html, ?string $textDer gerenderte Text (Links, Zeilenumbrüche).
message/message_template_pagestring $path, string $place, Message $messageDas Template, das für eine Nachricht verwendet wird.
system_messages/post_order_notebool $post, $note, WC_Order $orderBestimmte Bestellhinweise überspringen.
config/rate_limitarray{limit:int, window:int}Kundennachrichten pro Zeitfenster (standardmäßig 30 pro 10 Minuten).
notification/email_delayint $minutesDie Verzögerung der Sammel-E-Mail.
config/message_types_customer_should_be_notified / _admin_int[] $typesWelche Nachrichtentypen bei Team und Kunde jeweils E-Mails auslösen.

Einstellungen, Templates und Frontend

FilterArgumenteZweck
settings/sectionsSectionAbstract[] $sectionsEinen Einstellungsbereich hinzufügen.
settings/settingsarray $fields, SectionAbstract $sectionDie Felder eines Bereichs ändern.
settings/available_themesarray $palettesEine Farbpalette hinzufügen (Name → Custom Properties).
settings/available_file_typesarray $typesEinen Anhangstyp hinzufügen (Schlüssel → title, mime, ext).
config/get_{key}mixed $value, array $argsJede Einstellung durchläuft einen nach ihr benannten Filter, z. B. config/get_polling_interval.
template/locationstring $file, string $templateVon wo ein Template geladen wird.
frontend/conversation_configarray $config, WC_Order $orderDie Data-Attribute, die das Frontend-Skript liest.
frontend/show_on_order_receivedbool $show, WC_Order $orderDie Unterhaltung auf der Bestellbestätigungsseite anzeigen.
frontend/theme_integration_cssstring $cssZusätzliches CSS, das mit dem Frontend-Stylesheet ausgegeben wird.
order/customer_name, order/summarystring|array, WC_Order $orderWie eine Bestellung in der Admin-App und in E-Mails beschrieben wird.
attachments/sideloadbool $sideload, array $file, ?WC_Order $orderDateien akzeptieren, die keine Browser-Uploads sind (Importe, Tests).
rest/featuresarray $features, WC_Order $order, bool $isManagerWas der Eingabebereich für eine Bestellung und einen Betrachter anbietet.
rest/messagearray $data, Message $message, string $contextDie JSON-Struktur einer Nachricht.
license/can_use_premium_codebool $premiumPremium-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.

RouteMethodeParameter
/orders/{id}GETkey (Gäste). Liefert die Bestellübersicht, die Summen, die Zahl ungelesener Nachrichten und die features, die der Eingabebereich anbieten darf.
/orders/{id}/messagesGETbefore_id, after_id, per_page (≤ 200), render = json oder html. Neueste Seite zuerst; mit after_id fragen die Live-Aktualisierungen ab.
/orders/{id}/messagesPOSTmessage, 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}/readPOSTMarkiert die Unterhaltung für die Seite des Betrachters als gelesen.
/messages/{id}DELETENur für das Team.
/messages/{id}/unreadPOSTNur für das Team.
/conversationsGETNur für das Team. search, unread_only, page, per_page (≤ 100).
/unread-countGETNur 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:

HookZeitplan
order_messenger/publish_scheduled_messageEine Action pro geplanter Nachricht, zum jeweiligen Zeitpunkt; Argument message_id.
order_messenger/publish_due_scheduled_messagesAlle 10 Minuten; veröffentlicht alles, was verpasst wurde (Filter scheduler/catch_up_interval).
order_messenger/send_notification_digestsAlle 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

ElementDetails
[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 Kontomessages (die Liste) und messenger/{order-id} (eine Unterhaltung), registriert über woocommerce_get_query_vars.
Admin-Seiteadmin.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.

Fehlt etwas?

Fragen Sie uns: Wir antworten innerhalb eines Werktags und verbessern dabei gleich die Dokumentation.