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.
| Colonne | Signification |
|---|---|
id | ID du message. |
order_id | La commande à laquelle appartient la conversation. |
user_id | L’ID client de la commande (0 pour les invités). |
sender_id | L’utilisateur qui a écrit le message ; 0 pour les messages système. |
attachment_id | ID de la pièce jointe dans la médiathèque, ou NULL. |
message | Texte brut, jusqu’à 3000 caractères. |
type | 0 équipe, 1 client, 2 note de commande, 3 changement d’état, 4 programmé (en attente), 5 programmé (envoyé). |
date_sent / date_read | Horodatages UTC ; date_read vaut NULL tant que le message n’est pas lu. |
is_notified | 1 dès qu’un e-mail est parti (ou qu’aucun n’était nécessaire). |
data | JSON : 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
| Action | Arguments | Quand |
|---|---|---|
messages/message_created | Message $message | Un message a été enregistré (tout type). |
messages/message_updated | Message $message | Un message a changé (état de lecture, publication). |
messages/message_deleted | Message $message | Après la suppression d’un message ; messages/before_delete se déclenche avant. |
messages/changed | ?Message $message, int $orderId | Quelque chose a changé dans la conversation d’une commande ; les compteurs de non-lus écoutent ce hook. |
messages/scheduled_message_published | Message $published, Message $scheduled | Un message programmé est parti. |
notifications/sent | int $orderId, Message[] $messages, string $side, bool $sent | Un envoi d’e-mail de notification a été tenté ; $side vaut admin ou customer. |
attachments/uploaded | int $attachmentId, WC_Order $order, array $result | Un fichier envoyé par un client a été enregistré. |
admin/product_page/messenger_tab_begin / _end | int $productId | Ajouter des champs à l’onglet Order Messenger du produit. |
upgraded | string $from, string $to | Après une migration des données. |
rest/register_routes | string $namespace | Enregistrer vos propres routes à côté de celles du plugin. |
Permissions
| Filtre | Arguments | Utilité |
|---|---|---|
permissions/capability | string $capability | La capacité qui identifie les membres de l’équipe (par défaut manage_order_messenger). |
permissions/can_manage | bool $allowed, int $userId | Si un utilisateur fait partie de l’équipe. |
permissions/userCanViewMessenger | bool $allowed, WC_Order $order, int $userId | Si un client peut ouvrir une conversation. |
permissions/userCanSendMessage | bool $allowed, int $userId, WC_Order $order, string $text | Si un client peut écrire. |
permissions/userCanSendAdminMessage | bool $allowed, int $userId, WC_Order $order | Si un membre de l’équipe peut écrire dans la conversation de cette commande. |
permissions/userCanDeleteMessage / userCanUnreadMessage | bool $allowed, Message $message | Actions sur les messages. |
settings/allowed_roles_to_manage_admin_messenger/default | string[] $roles | Rôles d’équipe par défaut. |
Messages et contenu
| Filtre | Arguments | Utilité |
|---|---|---|
messages/before_saving_customer_message | Message $message, WC_Order $order, ?array $file | Modifier un message de client avant son enregistrement. |
messages/before_saving_admin_message | Message $message, $request, array $customData, WC_Order $order, int $attachmentId | Modifier un message de l’équipe avant son enregistrement. |
messages/before_saving_system_message | Message $message, WC_Order $order | Modifier une entrée automatique. |
messages/before_publishing_scheduled_message | Message $published, Message $scheduled | Modifier un message programmé au moment de son envoi. |
message/sender_name | string $name, Message $message | Le nom affiché pour un message. |
message/formatted_text | string $html, ?string $text | Le texte rendu (liens, sauts de ligne). |
message/message_template_page | string $path, string $place, Message $message | Le modèle utilisé pour un message. |
system_messages/post_order_note | bool $post, $note, WC_Order $order | Ignorer certaines notes de commande. |
config/rate_limit | array{limit:int, window:int} | Messages de client par fenêtre de temps (30 par tranche de 10 minutes par défaut). |
notification/email_delay | int $minutes | Le délai du récapitulatif. |
config/message_types_customer_should_be_notified / _admin_ | int[] $types | Les types de messages qui déclenchent des e-mails, pour chaque côté. |
Réglages, modèles et front-end
| Filtre | Arguments | Utilité |
|---|---|---|
settings/sections | SectionAbstract[] $sections | Ajouter une section de réglages. |
settings/settings | array $fields, SectionAbstract $section | Modifier les champs d’une section. |
settings/available_themes | array $palettes | Ajouter une palette de couleurs (nom → propriétés personnalisées). |
settings/available_file_types | array $types | Ajouter un type de pièce jointe (clé → titre, mime, ext). |
config/get_{key} | mixed $value, array $args | Chaque réglage passe par un filtre qui porte son nom, par ex. config/get_polling_interval. |
template/location | string $file, string $template | L’emplacement depuis lequel un modèle est chargé. |
frontend/conversation_config | array $config, WC_Order $order | Les attributs data que lit le script front-end. |
frontend/show_on_order_received | bool $show, WC_Order $order | Afficher la conversation sur la page de confirmation de commande. |
frontend/theme_integration_css | string $css | CSS supplémentaire inséré avec la feuille de style front-end. |
order/customer_name, order/summary | string|array, WC_Order $order | La façon dont une commande est décrite dans l’application d’administration et dans les e-mails. |
attachments/sideload | bool $sideload, array $file, ?WC_Order $order | Accepter des fichiers qui ne sont pas des envois du navigateur (imports, tests). |
rest/features | array $features, WC_Order $order, bool $isManager | Ce que la zone de rédaction propose pour une commande et pour la personne qui la consulte. |
rest/message | array $data, Message $message, string $context | La structure JSON d’un message. |
license/can_use_premium_code | bool $premium | Active 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.
| Route | Méthode | Paramètres |
|---|---|---|
/orders/{id} | GET | key (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}/messages | GET | before_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}/messages | POST | message, 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}/read | POST | Marque la conversation comme lue du côté de l’utilisateur courant. |
/messages/{id} | DELETE | Équipe uniquement. |
/messages/{id}/unread | POST | Équipe uniquement. |
/conversations | GET | Équipe uniquement. search, unread_only, page, per_page (≤ 100). |
/unread-count | GET | É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 :
| Hook | Planification |
|---|---|
order_messenger/publish_scheduled_message | Une action par message programmé, à l’heure prévue ; argument message_id. |
order_messenger/publish_due_scheduled_messages | Toutes 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ément | Dé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 compte | messages (la liste) et messenger/{order-id} (une conversation), enregistrés via woocommerce_get_query_vars. |
| Page d’administration | admin.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.