TC Token

​

Access

let tc_token = client.tc_token();

​

Methods

​

issue_tokens

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

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

• Vec<ReceivedTcToken> - List of received tokens

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);
}

​

prune_expired

pub async fn prune_expired(&self) -> Result<u32, TcTokenError>

• Number of tokens deleted

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

​

get

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

• jid - User portion of the JID (without domain)

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

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

pub async fn get_all_jids(&self) -> Result<Vec<String>, TcTokenError>

• List of JID user portions with stored tokens

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

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

​

Error handling

#[non_exhaustive]
pub enum TcTokenError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Store(#[from] StoreError),
}

• Iq — the server token request failed (timeout, server error, etc.)
• Store — token persistence failed

use whatsapp_rust::TcTokenError;

let jids = vec!["100000000000001@lid".parse()?];
match client.tc_token().issue_tokens(&jids).await {
    Ok(tokens) => println!("Got {} tokens", tokens.len()),
    Err(TcTokenError::Iq(e)) => eprintln!("Server request failed: {e}"),
    Err(TcTokenError::Store(e)) => eprintln!("Storage error: {e}"),
    Err(e) => eprintln!("Error: {e}"),
}

​

Types

​

ReceivedTcToken

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

​

TcTokenEntry

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

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,
}

​

Automatic usage

1. tctoken — used when PRIVACY_TOKEN_ON_ALL_1_ON_1_MESSAGES is on and a stored, unexpired token exists for the recipient
2. cstoken — an independent HMAC-SHA256 fallback using the NCT salt and recipient LID, used when NCT_TOKEN_SEND_ENABLED is on and the tctoken above didn’t win (its prop is off, or no valid token is stored) — see AB prop gating for the full priority logic
3. 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?;

• get_user_info — a per-recipient tctoken is attached to each queried <user> node in the usync IQ, so status/about for a privacy-restricted contact resolves instead of coming back hidden. Gated behind profile_scraping_privacy_token_in_about_usync.
• send_spam_report — when SpamReportRequest::from_jid is set, that contact’s tctoken is attached to the spam report IQ so the report is accepted for a privacy-restricted account. Gated behind enable_spam_report_iq_with_privacy_token. Group reports that only set group_jid/participant_jid (no from_jid) don’t get a token attached.
• Outgoing 1:1 call offers (voip feature) — placing a call attaches the callee’s stored, unexpired tctoken as the offer’s leading <privacy> node, and issues a fresh token to the callee in the background after the offer sends. This mirrors WA Web’s sendTcToken in StartCall.js and prevents 463 nacks on later offers to a privacy-restricted contact. Unlike the other paths, it isn’t gated by any AB prop — issuance is rate-limited only by the same sender bucket that governs message reissuance (see Post-send issuance). Group-call initiation isn’t implemented yet.

// Attaches the queried contact's tctoken automatically when the AB prop is on
let info = client.contacts().get_user_info(&[jid]).await?;

// Attaches the reported contact's tctoken automatically when the AB prop is on
let result = client.send_spam_report(request).await?;

// Attaches the callee's tctoken automatically, then issues a fresh one after the offer sends
let handle = client.voip().call(&peer).audio(mic_source, speaker_sink).start().await?;

​

AB prop gating

• PRIVACY_TOKEN_ON_ALL_1_ON_1_MESSAGES — gates the tctoken only (R). When off, a stored, valid tctoken is never attached.
• NCT_TOKEN_SEND_ENABLED — gates the cstoken fallback independently (D). The cstoken is attached whenever this flag is on and the NCT salt/recipient LID are available — even when the tctoken prop above is off, or a valid tctoken exists but its prop is disabled. The cstoken is not nested behind the tctoken prop.

​

Post-send issuance

​

Identity change reissuance

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

​

Incoming token notifications

1. Parses the <notification type="privacy_token"> stanza
2. Resolves the sender to a LID for storage (using sender_lid attribute or LID-PN cache)
3. Applies a timestamp monotonicity pre-filter — if the incoming token is older than a stored real token, storage and the presence re-subscribe are both skipped
4. Stores the token in the backend, preserving any sender_timestamp already recorded by the post-send issuance path
5. Re-subscribes presence for the sender to pick up the updated token

​

Startup pruning

​

Skipped recipients

• Your own JID
• Bot JIDs
• Status broadcast

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

​

cstoken (NCT fallback)

​

How it works

1. The server provides an NCT salt through the nct_salt_sync app state mutation (or via history sync during initial pairing)
2. The salt is stored in the Device struct as nct_salt
3. When sending a message where the tctoken doesn’t win — either PRIVACY_TOKEN_ON_ALL_1_ON_1_MESSAGES is off, or no valid TC token is stored — and NCT_TOKEN_SEND_ENABLED is on, the library computes HMAC-SHA256(nct_salt, recipient_lid) and includes it as a <cstoken> stanza child (see AB prop gating for the full priority logic)

​

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

• 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.

​

Token lifecycle

​

Expiration

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

// Get the cutoff timestamp for expired received 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 — checks both the received-token and sender-bucket
// cutoffs (AB-prop-aware config); a row survives if either is still live
let deleted = client.tc_token().prune_expired().await?;

​

Best practices

1. Pre-issue tokens for contacts you frequently interact with
2. Don’t over-issue — tokens are automatically issued after each message send when the bucket rolls over
3. Use LID JIDs when issuing tokens manually
4. 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(())
}