Esta referencia está dirigida a los desarrolladores que amplían Order Messenger: sobrescritura de plantillas, estilos, hooks, la API REST y los servicios PHP. Para la configuración y el uso diario, consulte la documentación para usuarios. Todo lo que sigue se aplica a la versión 4 del plugin; la versión gratuita y la premium comparten este código.
La arquitectura de un vistazo
El plugin vive en el espacio de nombres U2Code\OrderMessenger. Los servicios se registran en un contenedor y se obtienen mediante getters tipados:
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
Los mensajes son filas de la tabla {prefix}wc_order_messages. Las fechas se guardan en UTC.
| Columna | Significado |
|---|---|
id | ID del mensaje. |
order_id | El pedido al que pertenece la conversación. |
user_id | El ID de cliente del pedido (0 para los invitados). |
sender_id | El usuario que escribió el mensaje; 0 en los mensajes del sistema. |
attachment_id | ID del archivo adjunto en la biblioteca de medios, o NULL. |
message | Texto sin formato, hasta 3000 caracteres. |
type | 0 equipo, 1 cliente, 2 nota del pedido, 3 cambio de estado, 4 programado (en espera), 5 programado (enviado). |
date_sent / date_read | Marcas de tiempo en UTC; date_read es NULL mientras el mensaje no se ha leído. |
is_notified | 1 en cuanto se ha enviado un correo (o cuando no hacía falta ninguno). |
data | JSON: scheduled_date, notify, from/to en los cambios de estado, note_id, purchase_product_id. |
Enviar y leer mensajes desde código
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 es admin para la vista del equipo y customer para la del cliente; determina qué tipos de mensaje se incluyen y a qué parte corresponde el estado de no leído.
Sobrescribir plantillas
Las plantillas del frontend están en la carpeta views/frontend del plugin y se pueden copiar en su tema dentro de order-messenger-for-woocommerce/, manteniendo la ruta que hay por debajo de 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
La plantilla de la conversación recibe $order, $orderId, $orderKey, $messages (del más antiguo al más reciente), $totalMessages, $hasMore, $canSend, $filesEnabled, $config (los atributos de datos que lee el script) y $presenter. Las plantillas de mensaje reciben $message, $order y $orderKey. Conserve los atributos data-om-* y las clases om-* si quiere que el script siga funcionando: a través de ellos envía los mensajes, consulta periódicamente si hay mensajes nuevos y abre el lightbox.
Los correos de notificación son plantillas normales de WooCommerce. Cópielas de la carpeta views/emails del plugin a your-theme/woocommerce/emails/: admin-messenger-notification.php, customer-messenger-notification.php, partials/messages.php y las variantes de plain/.
La búsqueda de plantillas se puede redirigir con el filtro order_messenger/template/location (argumentos: archivo resuelto, nombre de la plantilla).
Estilos
La conversación que ve el cliente se adapta a propósito al tema: hereda la fuente de la página, calcula el color de sus líneas y rellenos a partir del color de texto actual y usa los campos y botones del propio tema. Las paletas con nombre definen estas propiedades personalizadas en .om-messenger y .om-conversations; puede definirlas usted mismo para darle un aspecto propio:
.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;
}
Clases útiles: .om-messenger (todo el widget), .om-message con los modificadores --customer, --admin, --system y --own, .om-message__bubble, .om-message__meta, .om-attachment, .om-messenger__composer, .om-badge y .om-nav-badge (contadores de no leídos), .om-conversations (la lista de Mi cuenta). Puede añadir reglas para un tema concreto con el filtro order_messenger/frontend/theme_integration_css; así es como el plugin añade a Storefront un icono de chat en el menú de la cuenta.
Hooks
Todos los nombres de hook empiezan por order_messenger/. Aquí se enumeran los más útiles; busque con grep en el código del plugin para ver la lista completa.
Acciones
| Acción | Argumentos | Cuándo |
|---|---|---|
messages/message_created | Message $message | Se ha guardado un mensaje (de cualquier tipo). |
messages/message_updated | Message $message | Ha cambiado un mensaje (estado de lectura, publicación). |
messages/message_deleted | Message $message | Después de eliminar un mensaje; messages/before_delete se dispara antes. |
messages/changed | ?Message $message, int $orderId | Ha cambiado algo en la conversación de un pedido; los contadores de no leídos escuchan aquí. |
messages/scheduled_message_published | Message $published, Message $scheduled | Se ha enviado un mensaje programado. |
notifications/sent | int $orderId, Message[] $messages, string $side, bool $sent | Se ha intentado enviar un correo de notificación; $side es admin o customer. |
attachments/uploaded | int $attachmentId, WC_Order $order, array $result | Se ha guardado un archivo subido por un cliente. |
admin/product_page/messenger_tab_begin / _end | int $productId | Añadir campos a la pestaña Order Messenger del producto. |
upgraded | string $from, string $to | Después de una migración de datos. |
rest/register_routes | string $namespace | Registrar sus propias rutas junto a las del plugin. |
Permisos
| Filtro | Argumentos | Finalidad |
|---|---|---|
permissions/capability | string $capability | La capacidad que identifica a los miembros del equipo (manage_order_messenger de forma predeterminada). |
permissions/can_manage | bool $allowed, int $userId | Si un usuario forma parte del equipo. |
permissions/userCanViewMessenger | bool $allowed, WC_Order $order, int $userId | Si un cliente puede abrir una conversación. |
permissions/userCanSendMessage | bool $allowed, int $userId, WC_Order $order, string $text | Si un cliente puede escribir. |
permissions/userCanSendAdminMessage | bool $allowed, int $userId, WC_Order $order | Si un miembro del equipo puede escribir en este pedido. |
permissions/userCanDeleteMessage / userCanUnreadMessage | bool $allowed, Message $message | Acciones sobre los mensajes. |
settings/allowed_roles_to_manage_admin_messenger/default | string[] $roles | Roles del equipo predeterminados. |
Mensajes y contenido
| Filtro | Argumentos | Finalidad |
|---|---|---|
messages/before_saving_customer_message | Message $message, WC_Order $order, ?array $file | Modificar un mensaje del cliente antes de guardarlo. |
messages/before_saving_admin_message | Message $message, $request, array $customData, WC_Order $order, int $attachmentId | Modificar un mensaje del equipo antes de guardarlo. |
messages/before_saving_system_message | Message $message, WC_Order $order | Modificar una entrada automática. |
messages/before_publishing_scheduled_message | Message $published, Message $scheduled | Modificar un mensaje programado en el momento de enviarlo. |
message/sender_name | string $name, Message $message | El nombre que se muestra en un mensaje. |
message/formatted_text | string $html, ?string $text | El texto renderizado (enlaces, saltos de línea). |
message/message_template_page | string $path, string $place, Message $message | La plantilla que se usa para un mensaje. |
system_messages/post_order_note | bool $post, $note, WC_Order $order | Omitir determinadas notas del pedido. |
config/rate_limit | array{limit:int, window:int} | Mensajes de cliente por intervalo de tiempo (30 cada 10 minutos de forma predeterminada). |
notification/email_delay | int $minutes | El tiempo de espera del resumen. |
config/message_types_customer_should_be_notified / _admin_ | int[] $types | Qué tipos de mensaje generan correos para cada parte. |
Ajustes, plantillas y frontend
| Filtro | Argumentos | Finalidad |
|---|---|---|
settings/sections | SectionAbstract[] $sections | Añadir una sección de ajustes. |
settings/settings | array $fields, SectionAbstract $section | Modificar los campos de una sección. |
settings/available_themes | array $palettes | Añadir una paleta de colores (nombre → propiedades personalizadas). |
settings/available_file_types | array $types | Añadir un tipo de archivo adjunto (clave → title, mime, ext). |
config/get_{key} | mixed $value, array $args | Cada ajuste pasa por un filtro con su nombre, por ejemplo config/get_polling_interval. |
template/location | string $file, string $template | Desde dónde se carga una plantilla. |
frontend/conversation_config | array $config, WC_Order $order | Los atributos de datos que lee el script del frontend. |
frontend/show_on_order_received | bool $show, WC_Order $order | Mostrar la conversación en la página de confirmación del pedido. |
frontend/theme_integration_css | string $css | CSS adicional que se imprime junto con la hoja de estilos del frontend. |
order/customer_name, order/summary | string|array, WC_Order $order | Cómo se describe un pedido en la aplicación de administración y en los correos. |
attachments/sideload | bool $sideload, array $file, ?WC_Order $order | Aceptar archivos que no se han subido desde el navegador (importaciones, pruebas). |
rest/features | array $features, WC_Order $order, bool $isManager | Lo que ofrece el editor de mensajes según el pedido y quién lo consulta. |
rest/message | array $data, Message $message, string $context | La estructura JSON de un mensaje. |
license/can_use_premium_code | bool $premium | Activa o desactiva las funciones premium. Siempre true en la versión de WooCommerce.com. |
Ejemplos
// 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
Espacio de nombres order-messenger/v1. Las peticiones del propio sitio se autentican con la cookie de WordPress y una cabecera X-WP-Nonce (nonce wp_rest); las aplicaciones externas usan contraseñas de aplicación. Los clientes de la tienda solo pueden acceder a sus propios pedidos; los invitados envían la clave del pedido como key. Las rutas del equipo requieren la capacidad manage_order_messenger.
| Ruta | Método | Parámetros |
|---|---|---|
/orders/{id} | GET | key (invitados). Devuelve el resumen del pedido, los totales, el número de no leídos y las features que puede ofrecer el editor de mensajes. |
/orders/{id}/messages | GET | before_id, after_id, per_page (≤ 200), render = json o html. Primero la página más reciente; las actualizaciones en directo consultan con after_id. |
/orders/{id}/messages | POST | message, file (multipart, clientes), attachment_id (equipo), notify, schedule_at (Y-m-d\TH:i:s, hora del sitio), custom_data, render. Responde 201 con el mensaje. |
/orders/{id}/read | POST | Marca la conversación como leída para la parte que la consulta. |
/messages/{id} | DELETE | Solo para el equipo. |
/messages/{id}/unread | POST | Solo para el equipo. |
/conversations | GET | Solo para el equipo. search, unread_only, page, per_page (≤ 100). |
/unread-count | GET | Solo para el equipo. Mensajes de clientes no leídos de todos los pedidos. |
// 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();
Las rutas de la versión 3 (/get/{limit}/{offset}, /send, /sendAdmin, /delete/{id}, /unread/{id}) siguen respondiendo con su formato antiguo para las integraciones que dependen de ellas.
Tareas en segundo plano
Los mensajes programados y los resúmenes por correo se ejecutan con el Action Scheduler de WooCommerce en el grupo order-messenger:
| Hook | Programación |
|---|---|
order_messenger/publish_scheduled_message | Una acción por cada mensaje programado, a su hora; argumento message_id. |
order_messenger/publish_due_scheduled_messages | Cada 10 minutos; publica los mensajes que no salieron a su hora (filtro scheduler/catch_up_interval). |
order_messenger/send_notification_digests | Cada pocos minutos mientras los resúmenes están activados (filtro notifications/digest_interval). |
Archivos adjuntos
Los archivos que suben los clientes pasan por wp_handle_upload() con los tipos permitidos en los ajustes, se renombran con nombres aleatorios, se guardan en uploads/order-messenger/ protegidos por una regla de denegación en .htaccess y se registran como elementos privados de la biblioteca de medios vinculados al pedido. Los adjuntos del equipo son archivos normales de la biblioteca de medios. Todos los archivos se sirven a través de admin-post.php?action=om_attachment, que comprueba que quien los solicita pertenece a la conversación (cliente, invitado con la clave del pedido o equipo) y transmite el archivo con un nonce vinculado al adjunto. Use AttachmentService::getDownloadUrl( $attachment, $size, $orderKey ) para generar un enlace de este tipo, y el filtro attachments/sideload para aportar archivos que no se han subido desde el navegador.
Shortcodes y endpoints
| Elemento | Detalles |
|---|---|
[order_chatroom order_id=""] | Una conversación; si no se indica el pedido, usa la variable de consulta view-order o messenger. |
[order_chatrooms limit="10" current_page="1"] | Las conversaciones del cliente actual. |
[order_chatroom_unread_messages_count order_id=""] | Número de no leídos de un pedido o, si se deja vacío, del cliente. |
| Endpoints de Mi cuenta | messages (la lista) y messenger/{order-id} (una conversación), registrados mediante woocommerce_get_query_vars. |
| Página de administración | admin.php?page=om-messenger&order={id} abre una conversación en la página Messenger. |
JavaScript
La aplicación de administración es una aplicación React basada en @wordpress/components; su configuración es window.omMessengerConfig (filtrable mediante admin/app_config). El script del frontend no tiene dependencias: cada elemento [data-om-messenger] recibe una instancia de Conversation, disponible como element.omConversation, con poll(), loadOlder() y send(). window.omFrontendConfig contiene el intervalo de sondeo y el número de no leídos para el indicador del menú de la cuenta.
Versión gratuita y premium
La versión de WordPress.org incluye el SDK de Freemius; la de WooCommerce.com, no. LicenseManager::canUsePremiumCode() es el único punto que consulta al SDK, y el filtro license/can_use_premium_code actúa por encima de él. Los archivos adjuntos son la función premium: en el plan gratuito, las subidas de los clientes se rechazan con un 403 y el editor de mensajes del equipo muestra un control bloqueado; todo lo demás funciona igual en ambas versiones.