Extract common fields from Whapi API responses

Helper function to standardize parsing of Whapi message responses. Whapi responses typically return a JSON object with a top-level element sent and a nested message object containing details such as id, status, timestamp, etc. This function consolidates those fields into a flat tibble, making it easier to work with message metadata in R.

Usage

whapi_extract_common_fields(out, fallback_to)

Arguments

out

A list (parsed JSON) as returned by httr2::resp_body_json() from a Whapi request.

fallback_to

Character(1). A fallback chat id (usually the to argument originally passed to the API) used when the response does not contain an explicit chat_id or to.

Value

A tibble with one row and the following columns:

• id: message id;

• to: recipient chat id (phone or group);

• status: sending status (e.g., "pending", "sent");

• timestamp: numeric epoch timestamp (seconds);

• timestamp_dt: POSIXct parsed timestamp in UTC;

• type: message type (e.g., "text", "image", "location");

• sent: logical/boolean (TRUE if sent flag present);

• resp: the full raw response list for inspection.

Details

The function safely looks up fields in multiple possible locations, since Whapi responses are not always consistent across endpoints:

• id: prefers out$message$id, then out$id, then out$message_id;

• status: out$message$status or out$status;

• timestamp: out$message$timestamp or out$timestamp;

• chat_id: from out$message$chat_id, out$message$to, or fallback_to;

• type: out$message$type or out$type;

• sent: top-level out$sent (boolean, TRUE if successfully sent).

The timestamp is returned both raw (numeric, seconds since epoch) and as a parsed POSIXct column (timestamp_dt, UTC).

See also

Used internally in wrappers like whapi_send_text(), whapi_send_image(), whapi_send_document(), whapi_send_location().

Examples

# Suppose `resp` is the parsed JSON returned from Whapi:
 out <- list(
   sent = TRUE,
   message = list(
     id = "abc123",
     chat_id = "558199999999@s.whatsapp.net",
     timestamp = 1756426418,
     type = "location",
     status = "pending"
   )
 )

 whapi_extract_common_fields(out, fallback_to = "558199999999")
#> # A tibble: 1 × 8
#>   id     to            status timestamp timestamp_dt        type  sent 
#>   <chr>  <chr>         <chr>      <dbl> <dttm>              <chr> <lgl>
#> 1 abc123 558199999999… pendi…    1.76e9 2025-08-29 00:13:38 loca… TRUE 
#> # ℹ 1 more variable: resp <list>