Order Messenger for WooCommerce

Documentation Développeurs

Cette référence s’adresse aux développeurs qui étendent Order Messenger : remplacement des modèles, styles, hooks, API REST et services PHP. Pour l’installation et l’utilisation au quotidien, consultez la documentation utilisateur. Tout ce qui suit s’applique à la version 4 du plugin ; les versions gratuite et premium partagent ce code.

L’architecture en bref

Le plugin se trouve dans l’espace de noms U2Code\OrderMessenger. Les services sont enregistrés dans un conteneur et accessibles via des getters typés :

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

Les messages sont des lignes de la table {prefix}wc_order_messages. Les dates sont stockées en UTC.

ColonneSignification
idID du message.
order_idLa commande à laquelle appartient la conversation.
user_idL’ID client de la commande (0 pour les invités).
sender_idL’utilisateur qui a écrit le message ; 0 pour les messages système.
attachment_idID de la pièce jointe dans la médiathèque, ou NULL.
messageTexte brut, jusqu’à 3000 caractères.
type0 équipe, 1 client, 2 note de commande, 3 changement d’état, 4 programmé (en attente), 5 programmé (envoyé).
date_sent / date_readHorodatages UTC ; date_read vaut NULL tant que le message n’est pas lu.
is_notified1 dès qu’un e-mail est parti (ou qu’aucun n’était nécessaire).
dataJSON : scheduled_date, notify, from/to pour les changements d’état, note_id, purchase_product_id.

Envoyer et lire des messages depuis le code

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 vaut admin pour la vue de l’équipe et customer pour celle du client ; il détermine quels types de messages sont inclus et de quel côté l’état non lu est pris en compte.

Remplacement des modèles

Les modèles front-end se trouvent dans le dossier views/frontend du plugin et peuvent être copiés dans votre thème sous order-messenger-for-woocommerce/, en conservant le chemin situé sous frontend/ :

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

Le modèle de conversation reçoit $order, $orderId, $orderKey, $messages (du plus ancien au plus récent), $totalMessages, $hasMore, $canSend, $filesEnabled, $config (les attributs data que lit le script) et $presenter. Les modèles de message reçoivent $message, $order et $orderKey. Conservez les attributs data-om-* et les classes om-* si vous voulez que le script continue de fonctionner : c’est par eux qu’il envoie les messages, interroge le serveur pour récupérer les nouveaux et ouvre la visionneuse.

Les e-mails de notification sont des modèles WooCommerce classiques. Copiez-les depuis le dossier views/emails du plugin vers your-theme/woocommerce/emails/ : admin-messenger-notification.php, customer-messenger-notification.php, partials/messages.php et les variantes plain/.

La recherche du modèle peut être redirigée avec le filtre order_messenger/template/location (arguments : fichier résolu, nom du modèle).

Styles

La conversation côté client est volontairement neutre vis-à-vis du thème : elle hérite de la police de la page, tire ses bordures et ses fonds de la couleur de texte courante et utilise les champs et les boutons du thème. Les palettes nommées définissent ces propriétés personnalisées sur .om-messenger et .om-conversations ; vous pouvez les définir vous-même pour une apparence sur mesure :

.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;
}

Classes utiles : .om-messenger (le widget entier), .om-message avec les modificateurs --customer, --admin, --system, --own, .om-message__bubble, .om-message__meta, .om-attachment, .om-messenger__composer, .om-badge et .om-nav-badge (compteurs de non-lus), .om-conversations (la liste de Mon compte). Des règles propres à un thème peuvent être ajoutées avec le filtre order_messenger/frontend/theme_integration_css ; c’est ainsi que le plugin donne à Storefront une icône de discussion dans le menu du compte.

Hooks

Tous les noms de hooks commencent par order_messenger/. Les plus utiles sont listés ici ; pour la liste complète, faites un grep dans le code du plugin.

Actions

ActionArgumentsQuand
messages/message_createdMessage $messageUn message a été enregistré (tout type).
messages/message_updatedMessage $messageUn message a changé (état de lecture, publication).
messages/message_deletedMessage $messageAprès la suppression d’un message ; messages/before_delete se déclenche avant.
messages/changed?Message $message, int $orderIdQuelque chose a changé dans la conversation d’une commande ; les compteurs de non-lus écoutent ce hook.
messages/scheduled_message_publishedMessage $published, Message $scheduledUn message programmé est parti.
notifications/sentint $orderId, Message[] $messages, string $side, bool $sentUn envoi d’e-mail de notification a été tenté ; $side vaut admin ou customer.
attachments/uploadedint $attachmentId, WC_Order $order, array $resultUn fichier envoyé par un client a été enregistré.
admin/product_page/messenger_tab_begin / _endint $productIdAjouter des champs à l’onglet Order Messenger du produit.
upgradedstring $from, string $toAprès une migration des données.
rest/register_routesstring $namespaceEnregistrer vos propres routes à côté de celles du plugin.

Permissions

FiltreArgumentsUtilité
permissions/capabilitystring $capabilityLa capacité qui identifie les membres de l’équipe (par défaut manage_order_messenger).
permissions/can_managebool $allowed, int $userIdSi un utilisateur fait partie de l’équipe.
permissions/userCanViewMessengerbool $allowed, WC_Order $order, int $userIdSi un client peut ouvrir une conversation.
permissions/userCanSendMessagebool $allowed, int $userId, WC_Order $order, string $textSi un client peut écrire.
permissions/userCanSendAdminMessagebool $allowed, int $userId, WC_Order $orderSi un membre de l’équipe peut écrire dans la conversation de cette commande.
permissions/userCanDeleteMessage / userCanUnreadMessagebool $allowed, Message $messageActions sur les messages.
settings/allowed_roles_to_manage_admin_messenger/defaultstring[] $rolesRôles d’équipe par défaut.

Messages et contenu

FiltreArgumentsUtilité
messages/before_saving_customer_messageMessage $message, WC_Order $order, ?array $fileModifier un message de client avant son enregistrement.
messages/before_saving_admin_messageMessage $message, $request, array $customData, WC_Order $order, int $attachmentIdModifier un message de l’équipe avant son enregistrement.
messages/before_saving_system_messageMessage $message, WC_Order $orderModifier une entrée automatique.
messages/before_publishing_scheduled_messageMessage $published, Message $scheduledModifier un message programmé au moment de son envoi.
message/sender_namestring $name, Message $messageLe nom affiché pour un message.
message/formatted_textstring $html, ?string $textLe texte rendu (liens, sauts de ligne).
message/message_template_pagestring $path, string $place, Message $messageLe modèle utilisé pour un message.
system_messages/post_order_notebool $post, $note, WC_Order $orderIgnorer certaines notes de commande.
config/rate_limitarray{limit:int, window:int}Messages de client par fenêtre de temps (30 par tranche de 10 minutes par défaut).
notification/email_delayint $minutesLe délai du récapitulatif.
config/message_types_customer_should_be_notified / _admin_int[] $typesLes types de messages qui déclenchent des e-mails, pour chaque côté.

Réglages, modèles et front-end

FiltreArgumentsUtilité
settings/sectionsSectionAbstract[] $sectionsAjouter une section de réglages.
settings/settingsarray $fields, SectionAbstract $sectionModifier les champs d’une section.
settings/available_themesarray $palettesAjouter une palette de couleurs (nom → propriétés personnalisées).
settings/available_file_typesarray $typesAjouter un type de pièce jointe (clé → titre, mime, ext).
config/get_{key}mixed $value, array $argsChaque réglage passe par un filtre qui porte son nom, par ex. config/get_polling_interval.
template/locationstring $file, string $templateL’emplacement depuis lequel un modèle est chargé.
frontend/conversation_configarray $config, WC_Order $orderLes attributs data que lit le script front-end.
frontend/show_on_order_receivedbool $show, WC_Order $orderAfficher la conversation sur la page de confirmation de commande.
frontend/theme_integration_cssstring $cssCSS supplémentaire inséré avec la feuille de style front-end.
order/customer_name, order/summarystring|array, WC_Order $orderLa façon dont une commande est décrite dans l’application d’administration et dans les e-mails.
attachments/sideloadbool $sideload, array $file, ?WC_Order $orderAccepter des fichiers qui ne sont pas des envois du navigateur (imports, tests).
rest/featuresarray $features, WC_Order $order, bool $isManagerCe que la zone de rédaction propose pour une commande et pour la personne qui la consulte.
rest/messagearray $data, Message $message, string $contextLa structure JSON d’un message.
license/can_use_premium_codebool $premiumActive ou désactive les fonctionnalités premium. Toujours vrai dans la version WooCommerce.com.

Exemples

// 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 );

API REST

Espace de noms order-messenger/v1. Les requêtes émises par le site lui-même s’authentifient avec le cookie WordPress et un en-tête X-WP-Nonce (nonce wp_rest) ; les applications externes utilisent des mots de passe d’application. Les clients de la boutique ne peuvent accéder qu’à leurs propres commandes ; les invités transmettent la clé de commande dans key. Les routes de l’équipe exigent la capacité manage_order_messenger.

RouteMéthodeParamètres
/orders/{id}GETkey (invités). Renvoie le résumé de la commande, les totaux, le nombre de messages non lus et les features que la zone de rédaction peut proposer.
/orders/{id}/messagesGETbefore_id, after_id, per_page (≤ 200), render = json ou html. Page la plus récente en premier ; les mises à jour en direct interrogent le serveur avec after_id.
/orders/{id}/messagesPOSTmessage, file (multipart, clients), attachment_id (équipe), notify, schedule_at (Y-m-d\TH:i:s, heure du site), custom_data, render. Répond 201 avec le message.
/orders/{id}/readPOSTMarque la conversation comme lue du côté de l’utilisateur courant.
/messages/{id}DELETEÉquipe uniquement.
/messages/{id}/unreadPOSTÉquipe uniquement.
/conversationsGETÉquipe uniquement. search, unread_only, page, per_page (≤ 100).
/unread-countGETÉquipe uniquement. Messages de clients non lus sur l’ensemble des commandes.
// 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();

Les routes de la version 3 (/get/{limit}/{offset}, /send, /sendAdmin, /delete/{id}, /unread/{id}) répondent toujours avec leurs anciens formats, pour les intégrations qui en dépendent.

Tâches en arrière-plan

Les messages programmés et les récapitulatifs par e-mail s’exécutent sur l’Action Scheduler de WooCommerce, dans le groupe order-messenger :

HookPlanification
order_messenger/publish_scheduled_messageUne action par message programmé, à l’heure prévue ; argument message_id.
order_messenger/publish_due_scheduled_messagesToutes les 10 minutes, publie tout ce qui a été manqué (filtre scheduler/catch_up_interval).
order_messenger/send_notification_digestsÀ quelques minutes d’intervalle, tant que les récapitulatifs sont activés (filtre notifications/digest_interval).

Pièces jointes

Les fichiers envoyés par les clients passent par wp_handle_upload() avec les types autorisés dans les réglages, sont renommés avec des noms aléatoires, stockés sous uploads/order-messenger/ derrière une règle de refus .htaccess, et enregistrés comme éléments privés de la médiathèque, liés à la commande. Les pièces jointes de l’équipe sont des fichiers ordinaires de la médiathèque. Chaque fichier est servi par admin-post.php?action=om_attachment, qui vérifie que la personne fait partie de la conversation (client, invité muni de la clé de commande, ou équipe) et transmet le fichier en flux avec un nonce lié à la pièce jointe. Utilisez AttachmentService::getDownloadUrl( $attachment, $size, $orderKey ) pour construire un tel lien, et le filtre attachments/sideload pour fournir des fichiers qui ne sont pas des envois du navigateur.

Shortcodes et points de terminaison

ÉlémentDétails
[order_chatroom order_id=""]Une conversation ; à défaut, utilise la variable de requête view-order ou messenger.
[order_chatrooms limit="10" current_page="1"]Les conversations du client connecté.
[order_chatroom_unread_messages_count order_id=""]Nombre de messages non lus pour une commande, ou pour le client si l’attribut est vide.
Points de terminaison de Mon comptemessages (la liste) et messenger/{order-id} (une conversation), enregistrés via woocommerce_get_query_vars.
Page d’administrationadmin.php?page=om-messenger&order={id} ouvre une conversation sur la page Messenger.

JavaScript

L’application d’administration est une application React basée sur @wordpress/components ; sa configuration se trouve dans window.omMessengerConfig (filtrable via admin/app_config). Le script front-end n’a aucune dépendance : chaque élément [data-om-messenger] reçoit une instance Conversation, accessible via element.omConversation, avec poll(), loadOlder() et send(). window.omFrontendConfig fournit l’intervalle d’interrogation et le nombre de messages non lus pour la pastille du menu du compte.

Versions gratuite et premium

La version WordPress.org embarque le SDK Freemius ; la version WooCommerce.com, non. LicenseManager::canUsePremiumCode() est le seul endroit qui interroge le SDK, et le filtre license/can_use_premium_code s’applique par-dessus. Les pièces jointes sont la fonctionnalité premium : avec la version gratuite, les envois des clients sont refusés avec une erreur 403 et la zone de rédaction de l’équipe affiche un bouton verrouillé ; tout le reste fonctionne de la même façon dans les deux versions.

Il manque quelque chose ?

Posez-nous la question : nous répondrons sous un jour ouvré, et nous en profiterons pour améliorer la documentation.