Order Messenger for WooCommerce

Documentación de Desarrolladores

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.

ColumnaSignificado
idID del mensaje.
order_idEl pedido al que pertenece la conversación.
user_idEl ID de cliente del pedido (0 para los invitados).
sender_idEl usuario que escribió el mensaje; 0 en los mensajes del sistema.
attachment_idID del archivo adjunto en la biblioteca de medios, o NULL.
messageTexto sin formato, hasta 3000 caracteres.
type0 equipo, 1 cliente, 2 nota del pedido, 3 cambio de estado, 4 programado (en espera), 5 programado (enviado).
date_sent / date_readMarcas de tiempo en UTC; date_read es NULL mientras el mensaje no se ha leído.
is_notified1 en cuanto se ha enviado un correo (o cuando no hacía falta ninguno).
dataJSON: 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ónArgumentosCuándo
messages/message_createdMessage $messageSe ha guardado un mensaje (de cualquier tipo).
messages/message_updatedMessage $messageHa cambiado un mensaje (estado de lectura, publicación).
messages/message_deletedMessage $messageDespués de eliminar un mensaje; messages/before_delete se dispara antes.
messages/changed?Message $message, int $orderIdHa cambiado algo en la conversación de un pedido; los contadores de no leídos escuchan aquí.
messages/scheduled_message_publishedMessage $published, Message $scheduledSe ha enviado un mensaje programado.
notifications/sentint $orderId, Message[] $messages, string $side, bool $sentSe ha intentado enviar un correo de notificación; $side es admin o customer.
attachments/uploadedint $attachmentId, WC_Order $order, array $resultSe ha guardado un archivo subido por un cliente.
admin/product_page/messenger_tab_begin / _endint $productIdAñadir campos a la pestaña Order Messenger del producto.
upgradedstring $from, string $toDespués de una migración de datos.
rest/register_routesstring $namespaceRegistrar sus propias rutas junto a las del plugin.

Permisos

FiltroArgumentosFinalidad
permissions/capabilitystring $capabilityLa capacidad que identifica a los miembros del equipo (manage_order_messenger de forma predeterminada).
permissions/can_managebool $allowed, int $userIdSi un usuario forma parte del equipo.
permissions/userCanViewMessengerbool $allowed, WC_Order $order, int $userIdSi un cliente puede abrir una conversación.
permissions/userCanSendMessagebool $allowed, int $userId, WC_Order $order, string $textSi un cliente puede escribir.
permissions/userCanSendAdminMessagebool $allowed, int $userId, WC_Order $orderSi un miembro del equipo puede escribir en este pedido.
permissions/userCanDeleteMessage / userCanUnreadMessagebool $allowed, Message $messageAcciones sobre los mensajes.
settings/allowed_roles_to_manage_admin_messenger/defaultstring[] $rolesRoles del equipo predeterminados.

Mensajes y contenido

FiltroArgumentosFinalidad
messages/before_saving_customer_messageMessage $message, WC_Order $order, ?array $fileModificar un mensaje del cliente antes de guardarlo.
messages/before_saving_admin_messageMessage $message, $request, array $customData, WC_Order $order, int $attachmentIdModificar un mensaje del equipo antes de guardarlo.
messages/before_saving_system_messageMessage $message, WC_Order $orderModificar una entrada automática.
messages/before_publishing_scheduled_messageMessage $published, Message $scheduledModificar un mensaje programado en el momento de enviarlo.
message/sender_namestring $name, Message $messageEl nombre que se muestra en un mensaje.
message/formatted_textstring $html, ?string $textEl texto renderizado (enlaces, saltos de línea).
message/message_template_pagestring $path, string $place, Message $messageLa plantilla que se usa para un mensaje.
system_messages/post_order_notebool $post, $note, WC_Order $orderOmitir determinadas notas del pedido.
config/rate_limitarray{limit:int, window:int}Mensajes de cliente por intervalo de tiempo (30 cada 10 minutos de forma predeterminada).
notification/email_delayint $minutesEl tiempo de espera del resumen.
config/message_types_customer_should_be_notified / _admin_int[] $typesQué tipos de mensaje generan correos para cada parte.

Ajustes, plantillas y frontend

FiltroArgumentosFinalidad
settings/sectionsSectionAbstract[] $sectionsAñadir una sección de ajustes.
settings/settingsarray $fields, SectionAbstract $sectionModificar los campos de una sección.
settings/available_themesarray $palettesAñadir una paleta de colores (nombre → propiedades personalizadas).
settings/available_file_typesarray $typesAñadir un tipo de archivo adjunto (clave → title, mime, ext).
config/get_{key}mixed $value, array $argsCada ajuste pasa por un filtro con su nombre, por ejemplo config/get_polling_interval.
template/locationstring $file, string $templateDesde dónde se carga una plantilla.
frontend/conversation_configarray $config, WC_Order $orderLos atributos de datos que lee el script del frontend.
frontend/show_on_order_receivedbool $show, WC_Order $orderMostrar la conversación en la página de confirmación del pedido.
frontend/theme_integration_cssstring $cssCSS adicional que se imprime junto con la hoja de estilos del frontend.
order/customer_name, order/summarystring|array, WC_Order $orderCómo se describe un pedido en la aplicación de administración y en los correos.
attachments/sideloadbool $sideload, array $file, ?WC_Order $orderAceptar archivos que no se han subido desde el navegador (importaciones, pruebas).
rest/featuresarray $features, WC_Order $order, bool $isManagerLo que ofrece el editor de mensajes según el pedido y quién lo consulta.
rest/messagearray $data, Message $message, string $contextLa estructura JSON de un mensaje.
license/can_use_premium_codebool $premiumActiva 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.

RutaMétodoParámetros
/orders/{id}GETkey (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}/messagesGETbefore_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}/messagesPOSTmessage, 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}/readPOSTMarca la conversación como leída para la parte que la consulta.
/messages/{id}DELETESolo para el equipo.
/messages/{id}/unreadPOSTSolo para el equipo.
/conversationsGETSolo para el equipo. search, unread_only, page, per_page (≤ 100).
/unread-countGETSolo 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:

HookProgramación
order_messenger/publish_scheduled_messageUna acción por cada mensaje programado, a su hora; argumento message_id.
order_messenger/publish_due_scheduled_messagesCada 10 minutos; publica los mensajes que no salieron a su hora (filtro scheduler/catch_up_interval).
order_messenger/send_notification_digestsCada 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

ElementoDetalles
[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 cuentamessages (la lista) y messenger/{order-id} (una conversación), registrados mediante woocommerce_get_query_vars.
Página de administraciónadmin.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.

¿Falta algo?

Pregúntenos y le responderemos en un día laborable; de paso, mejoraremos la documentación.