TC Token

The TcToken feature provides APIs for issuing and managing trusted contact privacy tokens (TC tokens). These tokens are used for privacy-gated operations like sending messages and fetching profile pictures. The library also supports cstoken (client-side token / NCT) as a fallback when no TC token exists for a recipient. This matches WhatsApp Web’s MsgCreateFanoutStanza.js behavior. Token timing (bucket duration and count) is configurable via server-side AB props, with sensible defaults matching WhatsApp Web.

Access

Access TC token operations through the client:

let tc_token = client.tc_token();

Methods

issue_tokens

Issue privacy tokens for specified contacts.

pub async fn issue_tokens(&self, jids: &[Jid]) -> Result<Vec<ReceivedTcToken>, IqError>

Parameters:

jids - Array of JIDs (should be LID JIDs) to issue tokens for

Returns:

Vec<ReceivedTcToken> - List of received tokens

Example:

let jids = vec![
    "100000000000001@lid".parse()?,
    "100000000000002@lid".parse()?,
];

let tokens = client.tc_token().issue_tokens(&jids).await?;

for token in &tokens {
    println!("Token for {}: {} bytes", token.jid, token.token.len());
    println!("Timestamp: {}", token.timestamp);
}

Issued tokens are automatically stored in the backend and used for subsequent operations like message sending and profile picture fetching. Tokens are also automatically issued after sending a message when the current bucket has expired (see automatic usage).

prune_expired

Remove expired tokens from storage.

pub async fn prune_expired(&self) -> Result<u32, anyhow::Error>

Returns:

Number of tokens deleted

Example:

let deleted = client.tc_token().prune_expired().await?;
println!("Pruned {} expired tokens", deleted);

By default, tokens expire after 28 days (4 buckets × 7 days). The server may override this via AB props. Expired tokens are also automatically pruned on connect. Call this method if you need to trigger pruning manually.

get

Get a stored token for a specific JID.

pub async fn get(&self, jid: &str) -> Result<Option<TcTokenEntry>, anyhow::Error>

Parameters:

jid - User portion of the JID (without domain)

Returns:

Option<TcTokenEntry> - The stored token entry, if found

Example:

if let Some(entry) = client.tc_token().get("100000000000001").await? {
    println!("Token timestamp: {}", entry.token_timestamp);
    println!("Token size: {} bytes", entry.token.len());
    
    if let Some(sender_ts) = entry.sender_timestamp {
        println!("Issued at: {}", sender_ts);
    }
}

get_all_jids

Get all JIDs that have stored tokens.

pub async fn get_all_jids(&self) -> Result<Vec<String>, anyhow::Error>

Returns:

List of JID user portions with stored tokens

Example:

let jids = client.tc_token().get_all_jids().await?;
println!("Tokens stored for {} contacts", jids.len());

for jid in jids {
    println!("  - {}", jid);
}

Types

ReceivedTcToken

Token received from the server.

pub struct ReceivedTcToken {
    /// JID the token is for
    pub jid: Jid,
    /// Binary token data
    pub token: Vec<u8>,
    /// Server timestamp
    pub timestamp: i64,
}

TcTokenEntry

Stored token entry.

pub struct TcTokenEntry {
    /// Binary token data
    pub token: Vec<u8>,
    /// Token timestamp from server
    pub token_timestamp: i64,
    /// Timestamp when we issued/received this token
    pub sender_timestamp: Option<i64>,
}

TcTokenConfig

Runtime-configurable timing for token expiration, sourced from server AB props.

pub struct TcTokenConfig {
    /// Receiver-side bucket duration in seconds (default: 604800 = 7 days)
    pub bucket_duration: i64,
    /// Number of receiver-side buckets (default: 4)
    pub num_buckets: i64,
    /// Sender-side bucket duration in seconds (default: 604800 = 7 days)
    pub sender_bucket_duration: i64,
    /// Number of sender-side buckets (default: 4)
    pub sender_num_buckets: i64,
}

The client builds this config from AB props at runtime, falling back to defaults. All values are clamped to safe ranges (durations between 1 and 180 days, counts ≥ 1).

Automatic usage

The library automatically includes privacy tokens in outgoing 1:1 message stanzas using a fallback chain that matches WhatsApp Web:

tctoken — use the stored trusted contact token if it exists and hasn’t expired
cstoken — compute an HMAC-SHA256 fallback using the NCT salt and recipient LID (for first-contact scenarios)
No token — send without a token if neither is available (the server may return a 463 error)

// TC tokens are automatically included when sending messages
client.send_message(jid, message).await?;

// And when fetching profile pictures
let picture = client.contacts().get_profile_picture(&jid, true).await?;

AB prop gating

Token inclusion on message stanzas is gated by server-side AB props:

PRIVACY_TOKEN_ON_ALL_1_ON_1_MESSAGES — controls whether tctoken/cstoken stanza children are attached to outgoing messages
NCT_TOKEN_SEND_ENABLED — controls whether the cstoken fallback is used when no tctoken is available

Token issuance scheduling (requesting new tokens from the server after sending) runs regardless of these flags.

Post-send issuance

After sending a 1:1 message, the library checks whether a new token should be issued for the recipient. If the sender-side bucket has rolled over since the last issuance, a background IQ request issues a fresh token and stores the response. This matches WhatsApp Web’s sendTcToken behavior in MsgJob.js.

Identity change reissuance

When a contact reinstalls WhatsApp and their identity key changes, the library automatically re-issues TC tokens so the contact retains a valid privacy token. This matches WhatsApp Web’s sendTcTokenWhenDeviceIdentityChange behavior. The reissuance is triggered when an UntrustedIdentity error is encountered during message decryption. After handling the identity change (clearing the old identity and retrying decryption), the client spawns a background task that:

Checks if a token was previously issued to the sender (via sender_timestamp)
Verifies the token hasn’t expired on the sender side
Re-issues the token using the original issuance timestamp to preserve the bucket window

This ensures that privacy-gated operations (like profile picture fetching) continue to work after a contact reinstalls, without requiring manual token management.

Token reissuance is skipped for bot JIDs and status broadcast senders. The operation is deduplicated via session locks to prevent concurrent reissuance for the same sender.

Incoming token notifications

When a contact sends you a privacy token, the library handles it automatically:

Parses the <notification type="privacy_token"> stanza
Resolves the sender to a LID for storage (using sender_lid attribute or LID-PN cache)
Applies a timestamp monotonicity guard — older tokens don’t overwrite newer ones
Stores the token in the backend
Re-subscribes presence for the sender to pick up the updated token

Startup pruning

Expired tokens are automatically pruned when the client connects, matching WhatsApp Web’s PrivacyTokenJob.

Skipped recipients

Tokens are not sent to:

Your own JID
Bot JIDs
Status broadcast

You typically don’t need to manage tokens manually unless you are:

Pre-issuing tokens for a batch of contacts
Debugging token-related issues

cstoken (NCT fallback)

When no valid TC token exists for a recipient, the library falls back to a cstoken (client-side token). This is computed using an NCT salt that is provisioned by the server via app state sync.

How it works

The server provides an NCT salt through the nct_salt_sync app state mutation (or via history sync during initial pairing)
The salt is stored in the Device struct as nct_salt
When sending a message to a recipient with no stored TC token, the library computes HMAC-SHA256(nct_salt, recipient_lid) and includes it as a <cstoken> stanza child

Wire format

<!-- TC token (preferred) -->
<tctoken><!-- raw token bytes --></tctoken>

<!-- CS token (NCT fallback) -->
<cstoken><!-- HMAC-SHA256(nct_salt, recipient_lid) --></cstoken>

NCT salt provisioning

The NCT salt is delivered through two channels:

App state sync — The nct_salt_sync mutation in the RegularHigh syncd collection sets or removes the salt. This is the authoritative source.
History sync — During initial pairing, the salt may be included in the history sync payload. This is a backfill-only source and won’t overwrite a salt already set via app state sync.

The cstoken fallback is fully automatic. You don’t need to manage the NCT salt or compute tokens manually. The library handles salt storage, LID resolution, and token computation transparently during message sending.

Token lifecycle

Expiration

TC token expiration uses a bucket-aligned system. By default, tokens expire after 28 days (4 buckets × 7-day duration). The server can override these defaults via AB props:

AB prop	Default	Description
`tctoken_duration`	604800 (7 days)	Receiver-side bucket duration in seconds
`tctoken_num_buckets`	4	Number of receiver-side buckets
`tctoken_duration_sender`	604800 (7 days)	Sender-side bucket duration in seconds
`tctoken_num_buckets_sender`	4	Number of sender-side buckets

Bucket durations are capped at 180 days. The expiration cutoff is bucket-aligned — it always falls on a bucket boundary, matching WhatsApp Web’s tokenExpirationCutoff logic.

use wacore::iq::tctoken::{tc_token_expiration_cutoff, is_tc_token_expired};

// Get the cutoff timestamp for expired tokens (using defaults)
let cutoff = tc_token_expiration_cutoff();
println!("Tokens before {} are expired", cutoff);

// Check a specific token
let expired = is_tc_token_expired(some_timestamp);

// Prune expired tokens (uses AB-prop-aware config)
let deleted = client.tc_token().prune_expired().await?;

Best practices

Pre-issue tokens for contacts you frequently interact with
Don’t over-issue — tokens are automatically issued after each message send when the bucket rolls over
Use LID JIDs when issuing tokens manually
Let startup pruning handle cleanup — expired tokens are pruned automatically on connect

// Pre-issue tokens for frequent contacts
async fn initialize_tokens(client: &Client, contacts: &[Jid]) -> anyhow::Result<()> {
    // Filter to LID JIDs only
    let lid_jids: Vec<_> = contacts.iter()
        .filter(|j| j.is_lid())
        .cloned()
        .collect();
    
    if !lid_jids.is_empty() {
        client.tc_token().issue_tokens(&lid_jids).await?;
    }
    
    Ok(())
}

Core

Messaging

Features

Storage & Backends

Core Modules

Access

Methods

issue_tokens

prune_expired

get

get_all_jids

Types

ReceivedTcToken

TcTokenEntry

TcTokenConfig

Automatic usage

AB prop gating

Post-send issuance

Identity change reissuance

Incoming token notifications

Startup pruning

Skipped recipients

cstoken (NCT fallback)

How it works

Wire format

NCT salt provisioning

Token lifecycle

Expiration

Best practices

​Access

​Methods

​issue_tokens

​prune_expired

​get

​get_all_jids

​Types

​ReceivedTcToken

​TcTokenEntry

​TcTokenConfig

​Automatic usage

​AB prop gating

​Post-send issuance

​Identity change reissuance

​Incoming token notifications

​Startup pruning

​Skipped recipients

​cstoken (NCT fallback)

​How it works

​Wire format

​NCT salt provisioning

​Token lifecycle

​Expiration

​Best practices

Access

Methods

issue_tokens

prune_expired

get

get_all_jids

Types

ReceivedTcToken

TcTokenEntry

TcTokenConfig

Automatic usage

AB prop gating

Post-send issuance

Identity change reissuance

Incoming token notifications

Startup pruning

Skipped recipients

cstoken (NCT fallback)

How it works

Wire format

NCT salt provisioning

Token lifecycle

Expiration

Best practices