Order meta _whatsapp_message_sent

O plugin grava o histórico de envios de cada pedido no meta _whatsapp_message_sent. Esse artigo cobre o formato, como ler, escrever e migrar do formato legado.

Formato

Array indexado por ID da mensagem (posição na aba Mensagens, começando em 0) com timestamp Unix do envio:

[
    0 => 1709568000,  // primeira mensagem ("Lembrete de pagamento") enviada em 04/03/2024 12:00 UTC
    1 => 1709827200,  // segunda mensagem enviada em 07/03/2024 12:00 UTC
    2 => null,        // terceira mensagem nunca foi enviada (chave nem existe)
]

Chaves não enviadas não existem no array (não são null). Para checar se uma mensagem foi enviada:

$sent = $order->get_meta( '_whatsapp_message_sent' );
$was_sent = isset( $sent[ $message_id ] );

Ler

$order = wc_get_order( 1234 );
$sent  = $order->get_meta( '_whatsapp_message_sent' );

if ( ! is_array( $sent ) ) {
    $sent = [];
}

foreach ( $sent as $message_id => $timestamp ) {
    printf(
        "Mensagem #%d enviada em %s\n",
        $message_id,
        date( 'd/m/Y H:i', $timestamp )
    );
}

Escrever

Para registrar manualmente um envio (por exemplo, em integração com outro sistema):

$order = wc_get_order( 1234 );

$sent = $order->get_meta( '_whatsapp_message_sent' );
$sent = is_array( $sent ) ? $sent : [];

$sent[0] = time();  // marca a primeira mensagem como enviada agora

$order->update_meta_data( '_whatsapp_message_sent', $sent );
$order->add_order_note( 'Enviado WhatsApp manualmente: Lembrete de pagamento' );
$order->save();

A nota no pedido é parte do contrato de UX — quando o usuário clica no botão na lista, o plugin adiciona uma nota com o título da mensagem. Replicar essa nota mantém consistência.

Resetar

Para apagar o histórico de envios de um pedido (botões voltam pra cinza):

$order = wc_get_order( 1234 );
$order->delete_meta_data( '_whatsapp_message_sent' );
$order->save();

Para apagar só uma mensagem específica:

$order = wc_get_order( 1234 );
$sent  = $order->get_meta( '_whatsapp_message_sent' );

if ( is_array( $sent ) ) {
    unset( $sent[ $message_id ] );
    $order->update_meta_data( '_whatsapp_message_sent', $sent );
    $order->save();
}

Migração do formato legado

Em versões 1.1.x do plugin, o meta era _whatsapp_message_sent_1 — string única (timestamp do único envio). A partir da v1.2.0, virou array em _whatsapp_message_sent.

A migração é lazy: acontece na primeira vez que o pedido é tocado pelo plugin (clique num botão da lista, abertura do meta box, ou chamada direta ao código). O plugin lê o legado e copia pro novo formato sob a chave 0.

Você não precisa rodar migração manual. Pedidos antigos continuam funcionando.

$wpdb->query(
    "DELETE FROM {$wpdb->postmeta} WHERE meta_key = '_whatsapp_message_sent_1'"
);

AJAX endpoint

Para entender como o plugin escreve no meta a partir do clique no botão, o handler AJAX é wp_ajax_wc_whatsapp_pending_orders:

• Action: wc_whatsapp_pending_orders
• POST data:
  • order_id — ID do pedido
  • message_id — índice da mensagem (0, 1, 2...)
• Response: { success: true }

Se você quer disparar a marcação de envio do JS sem clicar no botão visualmente:

jQuery.post( ajaxurl, {
    action     : 'wc_whatsapp_pending_orders',
    order_id   : 1234,
    message_id : 0
} );

Requer permissão manage_woocommerce (mesma da aba Pedidos).

Por que indexar por posição e não por hash

A escolha de indexar por posição da mensagem na aba (0, 1, 2) tem um trade-off conhecido:

• ✅ Simples de ler/escrever.
• ❌ Se você reordenar mensagens na aba Mensagens, o histórico fica "deslocado" — o que era a mensagem 0 (Lembrete) agora é 1, e o registro antigo passa a apontar pra outra mensagem.

Recomendação: não reordene mensagens depois que estiver em produção. Adicione novas no final ou substitua o texto da existente.