wuapi 0.15.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;

/// WhatsApp Status posts.
///
/// **Stories the account posts.** `POST .../stories` queues one like any send. It is stored as a message whose `chatId` is `stories` (`message.sent`, `message.failed` and `GET /v1/messages?chatId=stories` work as for any message), and that message's id is also its story id: `GET .../stories/own` lists the ones of the last 24 hours with their view count, `GET .../stories/{storyId}/viewers` says who saw one, `DELETE .../stories/{storyId}` deletes it for everyone.
///
/// **Stories contacts post.** Stored apart from messages, for 24 hours from the time they were posted, then deleted with any file wuapi stored for them. `GET .../stories` lists them grouped by author; `story.received` and `story.deleted` say when one arrives or its author deletes it. They are never counted as received messages (usage, the Free plan's limit) and never appear in `GET /v1/messages` or in the chats. An account receives them only once stories are turned on for it; until then the list is empty.
///
/// **Media is on demand.** A contact's story arrives without its file: `media.downloaded` is `false` and `media.url` is `GET .../stories/{storyId}/media`, which downloads it through the number's proxy the first time it is asked for.
///
/// **Viewing is explicit.** Listing stories, reading one or downloading its file tells WhatsApp nothing. Only `POST .../stories/{storyId}/view` sends the receipt that puts the account on the author's viewer list, once, when you call it. WhatsApp ties story views to the read receipts privacy setting: with `readReceipts` set to `none`, the author is not told (`authorNotified: false`), and the account does not learn who views its own stories either.
///
/// **Limits.** At most 5,000 contacts' stories per account and 100 per author at a time; past them new ones are not stored. Viewers of a posted story are kept for 7 days after it expires.
#[derive(Clone, Debug)]
pub struct StoriesResource {
    http: HttpClient,
}

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

    /// Post a story
    ///
    /// Queued like any send and stored as an outbound message with `chatId: stories`; that message's id is also the story's id (`GET .../stories/own`, `GET .../stories/{storyId}/viewers`, `DELETE .../stories/{storyId}`). The outcome arrives as `message.sent` or `message.failed`. It goes to the audience of the account's story privacy (`GET .../privacy/stories`).
    ///
    /// An image or video story takes `media.url` or `media.uploadId` (a file uploaded with `POST /v1/uploads`).
    ///
    /// `POST /v1/accounts/{accountId}/stories`
    ///
    /// 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 create(
        &self,
        account_id: &str,
        params: impl Into<types::StoriesCreateParams>,
    ) -> Request<types::Message> {
        let params = params.into();
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/stories", encode_path(account_id)))
            .body(&params)
            .keyed();
        self.http.request(parts)
    }

    /// List contacts' stories
    ///
    /// The stories the account's contacts posted in the last 24 hours, grouped by author: one `story_group` per contact, the contact with the newest story first, each with its stories oldest first. `limit` counts groups. Stored stories only, so the account does not need to be `ready`.
    ///
    /// Nothing here tells a contact the account saw their story: that is `POST .../stories/{storyId}/view`. An account receives contacts' stories only once stories are turned on for it; until then the list is empty.
    ///
    /// `GET /v1/accounts/{accountId}/stories`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn list(
        &self,
        account_id: &str,
        params: types::StoriesListParams,
    ) -> Paginator<types::StoryGroupList> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/stories", encode_path(account_id)))
            .query_opt("contactId", params.contact_id.as_ref())
            .query_opt("unviewed", params.unviewed.as_ref())
            .query_opt("limit", params.limit.as_ref())
            .retryable();
        Paginator::new(self.http.clone(), parts, "cursor", params.cursor)
    }

    /// List the account's stories
    ///
    /// The stories the account posted in the last 24 hours, newest first, each with `viewCount`: posted through the API, and, once stories are on for the account, from its phone too. Deleted stories are left out; one still `queued` or `failed` is listed with `postedAt: null`. Older ones stay readable as messages (`GET /v1/messages?chatId=stories`). A page may hold fewer stories than `limit` while `nextCursor` is set.
    ///
    /// `GET /v1/accounts/{accountId}/stories/own`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn list_own(
        &self,
        account_id: &str,
        params: types::StoriesListOwnParams,
    ) -> Paginator<types::StoryList> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/stories/own", encode_path(account_id)))
            .query_opt("limit", params.limit.as_ref())
            .retryable();
        Paginator::new(self.http.clone(), parts, "cursor", params.cursor)
    }

    /// Get a story
    ///
    /// One story: a contact's (while it has not expired; afterwards `404`) or one the account posted. Reading it does not mark it as viewed.
    ///
    /// `GET /v1/accounts/{accountId}/stories/{storyId}`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn get(&self, account_id: &str, story_id: &str) -> Request<types::Story> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/stories/{}", encode_path(account_id), encode_path(story_id)))
            .retryable();
        self.http.request(parts)
    }

    /// Get a story's media
    ///
    /// The story's file. By default the answer is `302 Found` to the file (no API key needed there). 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 contact's story is still on WhatsApp when it arrives (`media.downloaded: false`): the first request downloads it through the number's proxy and keeps it until the story expires; concurrent requests wait for that one download, and the account must be `ready` for it. Downloads count toward the account's 60 first media downloads per minute, shared with its messages' files.
    ///
    /// Downloading a story's file does not mark it as viewed and tells its author nothing.
    ///
    /// `GET /v1/accounts/{accountId}/stories/{storyId}/media`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn get_media(
        &self,
        account_id: &str,
        story_id: &str,
        params: types::StoriesGetMediaParams,
    ) -> Request<types::StoryMediaFile> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/stories/{}/media", encode_path(account_id), encode_path(story_id)))
            .query_opt("redirect", params.redirect.as_ref())
            .retryable();
        self.http.request(parts)
    }

    /// List a story's viewers
    ///
    /// Who saw a story the account posted, the latest viewer first, each with their reaction when they sent one. It is what WhatsApp reports through read receipts: contacts with read receipts off are not listed, and with the account's own `readReceipts` privacy set to `none` WhatsApp reports no viewer at all. Viewers are kept for 7 days after the story expires. A contact's story answers `400`.
    ///
    /// `GET /v1/accounts/{accountId}/stories/{storyId}/viewers`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn list_viewers(
        &self,
        account_id: &str,
        story_id: &str,
        params: types::StoriesListViewersParams,
    ) -> Paginator<types::StoryViewerList> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/stories/{}/viewers", encode_path(account_id), encode_path(story_id)))
            .query_opt("limit", params.limit.as_ref())
            .retryable();
        Paginator::new(self.http.clone(), parts, "cursor", params.cursor)
    }

    /// Mark a story as viewed
    ///
    /// Tell the author of a contact's story that the account saw it: wuapi sends WhatsApp one read receipt for that story, which puts the account on the story's viewer list, and sets `viewedAt`. This is the only call that does it: listing stories, reading one or downloading its file never sends a receipt, and wuapi never views a story on its own. Call it when a person actually opens the story.
    ///
    /// WhatsApp ties story views to the read receipts privacy setting. With the account's `readReceipts` set to `none` (`GET .../privacy`), WhatsApp records the view for the account's own devices only and the author is not told: the answer has `authorNotified: false`.
    ///
    /// A story already seen (through this call, or on the account's phone) is answered as it is and nothing is sent. The account's own stories answer `400`.
    ///
    /// `POST /v1/accounts/{accountId}/stories/{storyId}/view`
    ///
    /// 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 view(&self, account_id: &str, story_id: &str) -> Request<types::Story> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/stories/{}/view", encode_path(account_id), encode_path(story_id)))
            .keyed();
        self.http.request(parts)
    }

    /// React to a story
    ///
    /// React to a contact's story with an emoji (the heart the WhatsApp apps send is `💚`); an empty string removes the reaction. Only the story's author receives it, and sees it next to the account in the story's viewers. The story's `reaction` keeps it.
    ///
    /// A reaction is sent to the author alone, never to the account's other contacts. That is only possible while the account's own story privacy is "My contacts" or "My contacts except" and does not exclude the author; otherwise the answer is `400 not_supported` and nothing is sent. Reacting does not mark the story as viewed. The account's own stories answer `400`.
    ///
    /// `POST /v1/accounts/{accountId}/stories/{storyId}/react`
    ///
    /// 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 react(
        &self,
        account_id: &str,
        story_id: &str,
        params: types::StoriesReactParams,
    ) -> Request<()> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/stories/{}/react", encode_path(account_id), encode_path(story_id)))
            .body(&params)
            .keyed()
            .no_content();
        self.http.request(parts)
    }

    /// Delete a story
    ///
    /// Delete a story the account posted, for everyone: WhatsApp removes it from the phones of every contact, `deletedAt` is set on it and `message.deleted` fires. A story still `queued` is cancelled instead (`message.failed`, `error.code: cancelled`). Deleting an already deleted story answers `204` again. A contact's story cannot be deleted: `400`.
    ///
    /// `DELETE /v1/accounts/{accountId}/stories/{storyId}`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn delete(&self, account_id: &str, story_id: &str) -> Request<()> {
        let parts = RequestParts::new(Method::Delete, format!("/v1/accounts/{}/stories/{}", encode_path(account_id), encode_path(story_id)))
            .retryable()
            .no_content();
        self.http.request(parts)
    }
}