wuapi 0.13.0

Rust SDK for wuapi, a WhatsApp API for developers. Link numbers by QR or pairing code, send and receive messages, manage chats, contacts, groups and channels, split them into projects and verify webhooks.
Documentation
// Generated by wuapi-codegen from the OpenAPI spec. Do not edit: run `bun run codegen`.

use crate::http::{HttpClient, Method, Request, RequestParts, encode_path};
use crate::pagination::Paginator;
use crate::types;

/// The account's favorite stickers: the star tab of WhatsApp's sticker picker, which WhatsApp keeps in sync between the phone and its linked devices.
///
/// **Reading.** `GET .../stickers/favorites` answers what wuapi stored, without asking WhatsApp, so it works while the account is not `ready`. wuapi reads the list from WhatsApp once after a number is linked (a minute or two after it is `ready`) and then follows every change the phone or another device makes; until that first read the list is empty. `sticker.favorites_updated` tells you when it changes.
///
/// **Files.** A favorite is a reference to a file on WhatsApp. `media.url` fetches it on first use, through the number's proxy, and wuapi keeps it: `downloaded` turns `true` and `url` becomes the file itself. The account must be `ready` for that first fetch. Fetch the files a picker shows, not the whole list at once: first downloads are limited to 60 per minute per account, shared with message media.
///
/// **Changing.** `POST` favorites a sticker from a message or from an uploaded WebP file, and `DELETE` removes one. Both write to WhatsApp, so the phone and every other linked device show the change; the account must be `ready`. At most 30 changes per minute per account.
///
/// **Availability.** Favorite stickers are being turned on account by account. For an account that does not have them yet, the list is empty, no `sticker.favorites_updated` fires, and `POST` and `DELETE` answer `400 not_supported`.
#[derive(Clone, Debug)]
pub struct FavoriteStickersResource {
    http: HttpClient,
}

impl FavoriteStickersResource {
    pub(crate) fn new(http: HttpClient) -> Self {
        Self { http }
    }

    /// List favorite stickers
    ///
    /// The account's favorite stickers, the last one favorited first, as WhatsApp's sticker picker shows them. Read from what wuapi stored, without asking WhatsApp, so it works while the account is not `ready`.
    ///
    /// What is in it: wuapi reads the list from WhatsApp once after the number is linked, a minute or two after the account is `ready`, and then applies every change the phone or another linked device makes, as it happens. So the list is empty until that first read, and `sticker.favorites_updated` (`reason: synced`) says when it arrived. At most 2,000 favorites are kept, the newest.
    ///
    /// Each sticker's file stays on WhatsApp until someone asks for it: `media.downloaded` is `false` and `media.url` is the endpoint that fetches it. `animated` and `emojis` are `null` until then, because only the file says them.
    ///
    /// Favorite stickers are being turned on account by account: an account that does not have them yet answers an empty list, and adding or removing answers `400 not_supported`.
    ///
    /// `GET /v1/accounts/{accountId}/stickers/favorites`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn list(
        &self,
        account_id: &str,
        params: types::FavoriteStickersListParams,
    ) -> Paginator<types::FavoriteStickerList> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/stickers/favorites", encode_path(account_id)))
            .query_opt("limit", params.limit.as_ref())
            .retryable();
        Paginator::new(self.http.clone(), parts, "cursor", params.cursor)
    }

    /// Add a favorite sticker
    ///
    /// Favorite a sticker, so it appears in the star tab of the sticker picker on the phone and on every linked device. The change is written to WhatsApp; the account must be `ready`.
    ///
    /// Name the sticker one of two ways. `messageId`: a sticker message the account sent or received; wuapi reuses the file WhatsApp already has when it can, and uploads the stored file to WhatsApp otherwise. `uploadId`: a WebP file of your own, uploaded with `POST /v1/uploads` (`mimeType: image/webp`, at most 2 MB); wuapi uploads it to WhatsApp from the number, which is proxy traffic like sending it.
    ///
    /// Safe to repeat: a sticker that is a favorite already answers the same favorite and sends nothing to WhatsApp, and `Idempotency-Key` replays the first answer. `sticker.favorites_updated` (`reason: added`) follows.
    ///
    /// `POST /v1/accounts/{accountId}/stickers/favorites`
    ///
    /// Sends `Idempotency-Key` (a random key, or your own with `.idempotency_key(..)`), so it is retried on timeouts, network errors, `429` and `5xx` without repeating its effect.
    pub fn add(
        &self,
        account_id: &str,
        params: impl Into<types::FavoriteStickersAddParams>,
    ) -> Request<types::FavoriteSticker> {
        let params = params.into();
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/stickers/favorites", encode_path(account_id)))
            .body(&params)
            .keyed();
        self.http.request(parts)
    }

    /// Remove a favorite sticker
    ///
    /// Take a sticker out of the account's favorites, on the phone and on every linked device. The change is written to WhatsApp; the account must be `ready`.
    ///
    /// Safe to repeat: removing a favorite that was removed already answers `204` and sends nothing. `sticker.favorites_updated` (`reason: removed`) follows. The sticker's stored file is deleted, so its `media.url` stops working.
    ///
    /// `DELETE /v1/accounts/{accountId}/stickers/favorites/{stickerId}`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn remove(&self, account_id: &str, sticker_id: &str) -> Request<()> {
        let parts = RequestParts::new(Method::Delete, format!("/v1/accounts/{}/stickers/favorites/{}", encode_path(account_id), encode_path(sticker_id)))
            .retryable()
            .no_content();
        self.http.request(parts)
    }

    /// Get a favorite sticker's file
    ///
    /// The sticker's file. By default the answer is `302 Found` to the file (no API key needed there), so `curl -L`, browsers and HTTP clients download it directly. With `redirect=false`, or an `Accept` header that names only `application/json` (the SDKs), the answer is this JSON with the file's URL instead.
    ///
    /// A file still on WhatsApp (`media.downloaded: false`) is fetched first, once, through the number's proxy, and kept: later requests are served from storage, and the favorite then says `animated`, `emojis` and its real size. Concurrent requests for the same file wait for that one download. The account must be `ready` for a first download.
    ///
    /// WhatsApp does not keep files forever. A favorite whose file is gone answers `410 media_expired` and its `media.url` becomes `null`; favoriting the sticker again from a message or a file gives it a new one.
    ///
    /// `GET /v1/accounts/{accountId}/stickers/favorites/{stickerId}/media`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn get_media(
        &self,
        account_id: &str,
        sticker_id: &str,
        params: types::FavoriteStickersGetMediaParams,
    ) -> Request<types::FavoriteStickerMediaFile> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/stickers/favorites/{}/media", encode_path(account_id), encode_path(sticker_id)))
            .query_opt("redirect", params.redirect.as_ref())
            .retryable();
        self.http.request(parts)
    }
}