wuapi 0.17.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 `contacts` methods.
#[derive(Clone, Debug)]
pub struct ContactsResource {
    http: HttpClient,
}

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

    /// List contacts
    ///
    /// The account's contacts, ordered by saved name: its address book as the linked phone synced it to wuapi. Read from what wuapi stored, without asking WhatsApp, so it works while the account is not `ready`.
    ///
    /// What is in it: every contact the phone holds a saved name or a business name for. WhatsApp sends the address book to a linked device when the number is linked and again whenever it resyncs it, and wuapi stores it then, and after that every contact the phone adds, renames or deletes, as it happens. So the list is empty until the first sync after linking finishes (seconds to a few minutes), a contact deleted on the phone leaves the list, and people the account only chatted with, without saving them, are not in it: those are in `GET …/chats`.
    ///
    /// `about` and `deviceCount` are `null` here (ask `POST …/contacts/lookup`); `username` and `pictureId` are what wuapi has seen so far. With `q`, the contacts that match, best match first.
    ///
    /// `GET /v1/accounts/{accountId}/contacts`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn list(
        &self,
        account_id: &str,
        params: types::ContactsListParams,
    ) -> Paginator<types::ContactList> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/contacts", encode_path(account_id)))
            .query_opt("q", params.q.as_ref())
            .query_opt("limit", params.limit.as_ref())
            .retryable();
        Paginator::new(self.http.clone(), parts, "cursor", params.cursor)
    }

    /// Get a contact
    ///
    /// One contact of the account's address book, by its number or its `lid:<digits>` id, from what wuapi stored (see `GET …/contacts` for what that holds). A number or id the address book does not hold answers `404 not_found`, even when the account has a chat with it, unless a name was saved for it through wuapi (`PATCH …/contacts/{contactId}`, see `phoneSync`): `POST …/contacts/lookup` asks WhatsApp about any number.
    ///
    /// `GET /v1/accounts/{accountId}/contacts/{contactId}`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn get(&self, account_id: &str, contact_id: &str) -> Request<types::Contact> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/contacts/{}", encode_path(account_id), encode_path(contact_id)))
            .retryable();
        self.http.request(parts)
    }

    /// Save a contact on the phone
    ///
    /// Saves the contact under `savedName` on the account's phone: in WhatsApp and in the phone's own address book, as if it were saved on the phone. Any number can be saved, not only the ones the address book holds (a `lid:<digits>` contact needs its number known). The change is queued and answered `202` with the contact, its new `savedName` and `phoneSync.status: pending`: it is sent right away when the account is `ready`, and when it is back if it is reconnecting. `contact.updated` follows when WhatsApp took it (`synced`) or it failed (`not_on_whatsapp`, `account_offline`). The phone shows it about a minute later. Saving the same name again changes nothing. Removing a contact (`savedName: null`) is not supported.
    ///
    /// `PATCH /v1/accounts/{accountId}/contacts/{contactId}`
    ///
    /// 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 update(
        &self,
        account_id: &str,
        contact_id: &str,
        params: types::ContactsUpdateParams,
    ) -> Request<types::Contact> {
        let parts = RequestParts::new(Method::Patch, format!("/v1/accounts/{}/contacts/{}", encode_path(account_id), encode_path(contact_id)))
            .body(&params)
            .keyed();
        self.http.request(parts)
    }

    /// Save contacts on the phone in bulk
    ///
    /// Queues up to 500 contact saves at once, like `PATCH …/contacts/{contactId}` for each; they go to the phone in as few WhatsApp changes as possible. Each contact's `phoneSync` and `contact.updated` tell how it ended.
    ///
    /// `POST /v1/accounts/{accountId}/contacts/batch`
    ///
    /// 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 save_many(
        &self,
        account_id: &str,
        params: types::ContactsSaveManyParams,
    ) -> Request<types::ContactSaveBatch> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/contacts/batch", encode_path(account_id)))
            .body(&params)
            .keyed();
        self.http.request(parts)
    }

    /// Auto-save the contacts of existing chats
    ///
    /// Queues the auto-save of the contacts of the account's existing direct chats, named with its `contactAutoSave` templates (whether or not auto-save is enabled). The same rules apply: contacts the phone already holds a name for, and contacts written before, are left alone, and at most `dailyLimit` saves go out per UTC day. Calling it again queues only what is new.
    ///
    /// `POST /v1/accounts/{accountId}/contacts/auto-save/backfill`
    ///
    /// 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 backfill_auto_save(&self, account_id: &str) -> Request<types::ContactAutoSaveBackfill> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/contacts/auto-save/backfill", encode_path(account_id)))
            .keyed();
        self.http.request(parts)
    }

    /// Check numbers on WhatsApp
    ///
    /// Which numbers have WhatsApp. Read-only: works for a suspended project.
    ///
    /// `POST /v1/accounts/{accountId}/contacts/check`
    ///
    /// 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 check(
        &self,
        account_id: &str,
        params: types::ContactsCheckParams,
    ) -> Request<types::ContactCheckList> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/contacts/check", encode_path(account_id)))
            .body(&params)
            .keyed();
        self.http.request(parts)
    }

    /// Look up contacts
    ///
    /// About text, picture id, verified business name, username and device count, asked from WhatsApp for 1 to 50 contacts. Read-only. `savedName` and `profileName` are `null` here: the account's address book is `GET …/contacts`. The picture ids and usernames it returns are kept on the chats and contacts wuapi stores.
    ///
    /// `POST /v1/accounts/{accountId}/contacts/lookup`
    ///
    /// 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 lookup(
        &self,
        account_id: &str,
        params: types::ContactsLookupParams,
    ) -> Request<types::ContactList> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/contacts/lookup", encode_path(account_id)))
            .body(&params)
            .keyed();
        self.http.request(parts)
    }

    /// Get a profile picture
    ///
    /// The profile picture of a contact, or the picture of a group: `{contactId}` also takes a group id (`120363041234567890@g.us`), which is how a chat list shows group pictures. `id` is the picture's id and `url` a WhatsApp URL that expires, so download it and keep it by `id`. `404 picture_not_found` when it has no picture or this account may not see it (the contact's privacy settings); a community's own picture may answer that too. A channel id is passed to WhatsApp as it is, with no guarantee of an answer: a channel's picture is `pictureUrl` on the channel.
    ///
    /// What this call learns is kept: `pictureId` of the chat and of the contact follows it, so check that field before asking again.
    ///
    /// `GET /v1/accounts/{accountId}/contacts/{contactId}/picture`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn get_picture(
        &self,
        account_id: &str,
        contact_id: &str,
        params: types::ContactsGetPictureParams,
    ) -> Request<types::Picture> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/contacts/{}/picture", encode_path(account_id), encode_path(contact_id)))
            .query_opt("preview", params.preview.as_ref())
            .retryable();
        self.http.request(parts)
    }

    /// Get a business profile
    ///
    /// The WhatsApp Business profile of a contact.
    ///
    /// `GET /v1/accounts/{accountId}/contacts/{contactId}/business-profile`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn get_business_profile(
        &self,
        account_id: &str,
        contact_id: &str,
    ) -> Request<types::BusinessProfile> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/contacts/{}/business-profile", encode_path(account_id), encode_path(contact_id)))
            .retryable();
        self.http.request(parts)
    }

    /// Subscribe to a contact's presence
    ///
    /// Receive `contact.presence_updated` events for the contact. Needs the engine's extended events; otherwise `400 not_supported`.
    ///
    /// `POST /v1/accounts/{accountId}/contacts/{contactId}/subscribe-presence`
    ///
    /// 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 subscribe_presence(&self, account_id: &str, contact_id: &str) -> Request<()> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/contacts/{}/subscribe-presence", encode_path(account_id), encode_path(contact_id)))
            .keyed()
            .no_content();
        self.http.request(parts)
    }

    /// Block a contact
    ///
    /// The contact can no longer message or call the account.
    ///
    /// `POST /v1/accounts/{accountId}/contacts/{contactId}/block`
    ///
    /// 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 block(&self, account_id: &str, contact_id: &str) -> Request<()> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/contacts/{}/block", encode_path(account_id), encode_path(contact_id)))
            .keyed()
            .no_content();
        self.http.request(parts)
    }

    /// Unblock a contact
    ///
    /// Remove the contact from the blocklist.
    ///
    /// `POST /v1/accounts/{accountId}/contacts/{contactId}/unblock`
    ///
    /// 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 unblock(&self, account_id: &str, contact_id: &str) -> Request<()> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/contacts/{}/unblock", encode_path(account_id), encode_path(contact_id)))
            .keyed()
            .no_content();
        self.http.request(parts)
    }

    /// List blocked contacts
    ///
    /// The account's blocklist, read live from WhatsApp. `contactId` is the contact as WhatsApp lists it (often a LID); `phone` and `lid` add the number and the LID when the account knows them.
    ///
    /// `GET /v1/accounts/{accountId}/blocklist`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn list_blocked(
        &self,
        account_id: &str,
        params: types::ContactsListBlockedParams,
    ) -> Paginator<types::BlockedContactList> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/blocklist", encode_path(account_id)))
            .query_opt("limit", params.limit.as_ref())
            .retryable();
        Paginator::new(self.http.clone(), parts, "cursor", params.cursor)
    }

    /// Get the account's contact link
    ///
    /// The account's own contact QR link.
    ///
    /// `GET /v1/accounts/{accountId}/contact-link`
    ///
    /// Safe to repeat: retried on timeouts, network errors, `429` and `5xx`.
    pub fn get_link(&self, account_id: &str) -> Request<types::ContactLink> {
        let parts = RequestParts::new(Method::Get, format!("/v1/accounts/{}/contact-link", encode_path(account_id)))
            .retryable();
        self.http.request(parts)
    }

    /// Reset the account's contact link
    ///
    /// Revoke the current contact link and return a new one.
    ///
    /// `POST /v1/accounts/{accountId}/contact-link/reset`
    ///
    /// 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 reset_link(&self, account_id: &str) -> Request<types::ContactLink> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/contact-link/reset", encode_path(account_id)))
            .keyed();
        self.http.request(parts)
    }

    /// Resolve a contact or business link
    ///
    /// Who a contact QR link or a business message link points to. Read-only. `400 not_supported` when WhatsApp does not offer link resolution to this account.
    ///
    /// `POST /v1/accounts/{accountId}/links/resolve`
    ///
    /// 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 resolve_link(
        &self,
        account_id: &str,
        params: types::ContactsResolveLinkParams,
    ) -> Request<types::ResolvedLink> {
        let parts = RequestParts::new(Method::Post, format!("/v1/accounts/{}/links/resolve", encode_path(account_id)))
            .body(&params)
            .keyed();
        self.http.request(parts)
    }
}