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

wuapi Rust SDK

crates.io docs.rs license

Rust SDK for wuapi, a WhatsApp API for developers. Link your own WhatsApp numbers by QR code or pairing code, send and receive messages, manage chats, contacts, groups, communities and channels, split them into projects, and receive events over Webhooks or Streams.

  • Async, on reqwest and tokio. TLS is rustls: there is no OpenSSL to install.
  • Types for every schema of the OpenAPI spec, with serde.
  • A timeout on every attempt, retries that never repeat a send, and idempotency keys built in.
  • Streams: your events over one connection, with reconnect and resume built in.

Docs: wuapi.dev/docs. API reference for this crate: docs.rs/wuapi.

How it works. wuapi does not use the WhatsApp Business Platform (Cloud API). Numbers are linked as devices, the same way WhatsApp Web works. WhatsApp can restrict or ban numbers that behave like spam. You are responsible for your recipients' consent and for following WhatsApp's terms.

Install

cargo add wuapi
cargo add tokio --features macros,rt-multi-thread

The crate needs Rust 1.85 or later and a tokio runtime.

Authentication

Create an API key in the dashboard at wuapi.dev/app/api-keys. Keys look like wu_live_... and are sent as Authorization: Bearer <key>. Keep them on your server.

use wuapi::Wuapi;

fn clients() -> Result<(Wuapi, Wuapi), wuapi::Error> {
    let from_env = Wuapi::from_env()?; // reads WUAPI_API_KEY
    let explicit = Wuapi::new("wu_live_...")?;
    Ok((from_env, explicit))
}

A missing key is an Error::Config when the client is built. The client is cheap to clone: clones share one connection pool.

An organization key reaches every project. A project key, created with projects().api_keys().create(..), reaches only its project: see Projects.

Quickstart: link a number and send a message

use std::time::Duration;

use wuapi::types::{AccountCreateRequest, AccountStatus, ProxyLocationInput, SendTextMessageRequest};
use wuapi::Wuapi;

#[tokio::main]
async fn main() -> Result<(), wuapi::Error> {
    let client = Wuapi::from_env()?;

    // 1. Create an account. Its traffic exits through a residential proxy in
    //    the country and city you name: use the phone number's country.
    //    `proxy_locations().list(..)` returns every supported pair.
    let mut request = AccountCreateRequest::new(ProxyLocationInput::new("VE", "caracas"));
    request.name = Some("Support line".to_owned());
    let account = client.accounts().create(request).await?;

    // 2. Poll the account: show the QR code to the phone owner (WhatsApp >
    //    Linked devices > Link a device) and wait until the phone has linked.
    //    The QR code rotates while you wait.
    let ready = loop {
        let account = client.accounts().get(&account.id).await?;
        match account.status {
            AccountStatus::Ready => break account,
            AccountStatus::QrReady => println!("Scan this QR code: {:?}", account.qr_code_url),
            AccountStatus::Failed => panic!("linking failed: {:?}", account.last_error),
            _ => {}
        }
        tokio::time::sleep(Duration::from_secs(2)).await;
    };

    // 3. Send a message.
    let text = SendTextMessageRequest::new(&ready.id, "+584241112233", "Your order has shipped.");
    let message = client.messages().send(text).await?;
    println!("{} {}", message.id, message.status); // "queued"
    Ok(())
}

A send returns the message with status queued. The outcome arrives as the message.sent or message.failed webhook, or by calling client.messages().get(id).

To link by phone number instead of a QR code, set pairing_phone on the create request, or call accounts().create_pairing_code(..), and show account.pairing_code to the phone owner.

Contacts are E.164 (+584241112233), or lid:<digits> when WhatsApp hides the number; groups are ...@g.us, channels ...@newsletter.

Sending other types

messages().send(..) takes any of the Send...MessageRequest types. Each has a new with its required fields; the optional ones are public fields that start as None.

use wuapi::types::{SendDocumentMessageRequest, SendMediaUrl, SendTextMessageRequest};
use wuapi::Wuapi;

async fn examples(client: &Wuapi, account_id: &str) -> Result<(), wuapi::Error> {
    let mut media = SendMediaUrl::new("https://example.com/invoice.pdf");
    media.filename = Some("invoice.pdf".to_owned());
    let mut document = SendDocumentMessageRequest::new(account_id, "+584241112233", media.into());
    document.text = Some("Your invoice".to_owned());
    client.messages().send(document).await?;

    // Reply to (quote) a message in the same chat.
    let mut reply = SendTextMessageRequest::new(account_id, "+584241112233", "Tomorrow.");
    reply.reply_to_message_id = Some("msg_...".to_owned());
    let sent = client.messages().send(reply).await?;

    // Star what you sent, then delete it.
    client.messages().star(&sent.id).await?;
    client.messages().delete(&sent.id, Default::default()).await?;
    Ok(())
}

Everything else works on the account: chats, contacts, the profile, privacy, stories, groups and communities, channels, labels and calls. Those methods take the account id first, and the account must be ready. The methods are grouped and named like the TypeScript SDK's, in snake case: client.chats().archive(account_id, chat_id), client.groups().add_participants(account_id, group_id, params).

Sending a local file

A file you have (a local file, a pasted image, a recorded voice note) is uploaded first and sent by its upload id. Create the upload with its type and size, post the bytes to the upload_url of the answer with your own HTTP client, complete it with the storageId that post answers, and send it:

use wuapi::types::{FileUploadCreateRequest, SendImageMediaUpload, SendImageMessageRequest, UploadCompleteRequest};
use wuapi::Wuapi;

async fn send_photo(client: &Wuapi, account_id: &str, bytes: Vec<u8>) -> Result<(), Box<dyn std::error::Error>> {
    // 1. Declare the file. The answer carries `upload_url`, valid for one hour.
    let size = i64::try_from(bytes.len())?;
    let upload = client.uploads().create(FileUploadCreateRequest::new("image/jpeg", size)).await?;
    let upload_url = upload.upload_url.ok_or("the upload has no upload URL")?;

    // 2. Post the bytes straight to storage: no API key, the URL is the credential.
    let stored = reqwest::Client::new()
        .post(upload_url)
        .header("Content-Type", "image/jpeg")
        .body(bytes)
        .send()
        .await?
        .error_for_status()?
        .text()
        .await?;
    let stored: serde_json::Value = serde_json::from_str(&stored)?;
    let storage_id = stored["storageId"].as_str().ok_or("the upload URL answered no storageId")?;

    // 3. Complete it, then send it. A ready upload can be sent again for 24 hours.
    let upload = client.uploads().complete(&upload.id, UploadCompleteRequest::new(storage_id)).await?;
    let media = SendImageMediaUpload::new(upload.id);
    let image = SendImageMessageRequest::new(account_id, "+584241112233", media.into());
    client.messages().send(image).await?;
    Ok(())
}

Files up to 100 MB work this way, because the bytes never pass through the API. A file up to 5 MB can skip steps 2 and 3: uploads().create(InlineUploadCreateRequest::new("image/jpeg", base64)) takes the bytes as base64 and answers an upload that is already ready. A voice note is an Ogg/Opus file sent with SendVoiceMessageRequest.

Every step is safe to repeat: create and complete carry an idempotency key, completing a ready upload with the same storageId answers it again, and a send that is retried with the same key is replayed, never sent twice.

Drops, timeouts and retries

Every number connects through a residential proxy, so a request can be slow or lose its connection halfway. The client is built for that:

  • Every attempt has a timeout: 30 seconds by default, per attempt, from connecting until the body has been read. Change it for the client with builder().timeout(..) or for one call with .timeout(..).
  • A send carries an idempotency key. Every method whose endpoint accepts Idempotency-Key (sends, reactions, group changes, creates) sends a random key, and every retry of that call sends the same one, so the API replays the first answer instead of sending twice.
  • Retries only where they cannot repeat work. GET, PUT and DELETE requests and requests with an idempotency key are retried on timeouts, network errors, 429 and 5xx, with exponential backoff and jitter (2 retries by default). A request that is not idempotent (the PATCH updates) is retried only when it never reached the API (the connection could not be opened) or was refused with 429. A Retry-After header is honored; one longer than 60 seconds fails at once with the wait in Error::retry_after().

The random key covers the retries the client makes on its own. To make a request you send again later the same request (after your process restarted, or from a job queue), give it your own key:

use std::time::Duration;

use wuapi::types::SendTextMessageRequest;
use wuapi::Wuapi;

async fn notify(client: &Wuapi, order_id: u64, text: SendTextMessageRequest) -> Result<(), wuapi::Error> {
    client
        .messages()
        .send(text)
        .idempotency_key(format!("order-{order_id}-shipped"))
        .timeout(Duration::from_secs(10))
        .await?;
    Ok(())
}

The same key with the same request answers with the first response for 24 hours. A key reused with a different body answers 409 idempotency_conflict.

A request does nothing until it is awaited. Dropping its future cancels it.

Lists and pagination

List methods return a Paginator. Stream it to walk every item across pages, or ask for one page:

use wuapi::pagination::TryStreamExt;
use wuapi::types::{MessageDirection, MessagesListParams};
use wuapi::Wuapi;

async fn inbound(client: &Wuapi, account_id: &str) -> Result<(), wuapi::Error> {
    let params = MessagesListParams {
        account_id: Some(account_id.to_owned()),
        direction: Some(MessageDirection::Inbound),
        ..Default::default()
    };

    let mut messages = client.messages().list(params.clone()).stream();
    while let Some(message) = messages.try_next().await? {
        println!("{:?} {:?}", message.from, message.text);
    }

    let page = client.messages().list(params.clone()).page().await?;
    if let Some(cursor) = &page.next_cursor {
        let next = client.messages().list(params).page_at(cursor).await?;
        println!("{} more", next.items.len());
    }
    Ok(())
}

pages() streams whole pages, to_vec() collects everything and to_vec_max(n) stops after n items. Every list has the same shape, object, items and next_cursor, including lists read live from WhatsApp.

Webhooks

Create an endpoint once and store the secret; it is returned only on creation.

use wuapi::types::{WebhookEndpointCreateRequest, WebhookEventType};
use wuapi::Wuapi;

async fn subscribe(client: &Wuapi) -> Result<(), wuapi::Error> {
    let events = vec![WebhookEventType::MessageReceived, WebhookEventType::AccountDisconnected];
    let request = WebhookEndpointCreateRequest::new("https://example.com/webhooks/wuapi", events);
    let endpoint = client.webhook_endpoints().create(request).await?;
    println!("{:?}", endpoint.secret); // whsec_...
    Ok(())
}

Verify each request with the raw body, before parsing it as JSON:

use wuapi::types::Event;
use wuapi::{WebhookVerificationError, verify_webhook};

/// `signature` is the `Wuapi-Signature` header.
fn handle(raw_body: &[u8], signature: &str, secret: &str) -> Result<(), WebhookVerificationError> {
    match verify_webhook(raw_body, signature, secret)? {
        Event::Message(event) => println!("{:?} {:?}", event.r#type, event.data.object.text),
        Event::Account(event) => println!("{} is {}", event.data.object.id, event.data.object.status),
        Event::Unknown(raw) => println!("an event newer than this SDK: {raw}"),
        _ => {}
    }
    Ok(())
}

verify_webhook checks the Wuapi-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<rawBody>">) in constant time and rejects timestamps more than 300 seconds away; verify_webhook_with_tolerance takes another tolerance, and verify_signature checks without parsing. Answer anything but 2xx when it fails. Deliveries can repeat: deduplicate on the event's id.

An event type added after this version of the SDK parses as Event::Unknown with its raw JSON, instead of failing.

Streams

Streams deliver the same events as Webhooks over one connection your code opens: no public endpoint, no signature to verify. Use Streams from a script, a worker behind a firewall, a desktop app, or while you build.

use wuapi::resources::events::EventsStreamParams;
use wuapi::types::{Event, WebhookEventType};
use wuapi::Wuapi;

async fn listen(client: &Wuapi) -> Result<(), Box<dyn std::error::Error>> {
    let params = EventsStreamParams::new().types([WebhookEventType::MessageReceived]);
    let mut stream = client.events().stream(params)?;
    while let Some(event) = stream.next_event().await {
        let event = event?; // a StreamError: the stream has stopped for good
        match event.parse()? {
            Event::Message(message) => println!("{:?}", message.data.object.text),
            other => println!("{} {other:?}", event.event),
        }
        // Save `event.cursor` to resume from here after a restart.
    }
    Ok(())
}

The stream connects, and when the connection ends (a deploy, a network drop, an hour of age) it waits and connects again with its cursor, so nothing in between is missed; an event a replay repeats is delivered once. It never gives up by itself: only what waiting cannot fix ends it, as a StreamError whose kind is Unauthorized, Forbidden, InvalidRequest, NotFound, Refused or UnexpectedResponse. A 429 (the Free plan allows 3 open stream connections per organization), a 5xx and a network error are waited out, honoring Retry-After, with jitter and at most 6 connects a minute for the whole client.

next_item() reports everything in order, not only events: Open, Reset (the cursor was too old and events may have been missed: resync over REST, the stream goes on live), Skipped and Reconnecting with its reason and delay.

use std::time::Duration;

use wuapi::resources::events::EventsStreamParams;
use wuapi::{StreamItem, StreamOptions, Wuapi};

async fn watch(client: &Wuapi, saved: Option<String>) -> Result<(), Box<dyn std::error::Error>> {
    let mut params = EventsStreamParams::new().accounts(["k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr"]);
    params.last_event_id = saved;
    let options = StreamOptions::new().give_up_after(Duration::from_secs(30 * 60));
    let mut stream = client.events().stream_with(params, options)?;
    while let Some(item) = stream.next_item().await {
        match item? {
            StreamItem::Event(event) => println!("{} {}", event.event, event.data),
            StreamItem::Reset { reason } => println!("missed events ({reason}): resync over REST"),
            StreamItem::Reconnecting(waiting) => println!("{:?}, back in {:?}", waiting.reason, waiting.delay),
            _ => {}
        }
    }
    Ok(())
}
  • next_event() and next_item() lose nothing when their future is dropped, so they can be raced in a select!. into_stream() and into_items() turn the stream into a futures Stream.
  • event.data is the envelope exactly as received, and event.parse() types it; a type newer than this version parses as Event::Unknown.
  • A stream without a cursor starts now. Within 28 minutes of a cursor, wuapi replays what happened since (events are kept 30 minutes, but only 28 are guaranteed).
  • close() ends a stream; dropping it does too. restart_after(wait, keep_cursor) starts a stopped stream again.
  • The key is sent in the Authorization header only, and only to https (or to http on this machine). Wuapi::builder().stream_base_url(..) points at another stream host.
  • wuapi::stream has the parts for a caller that drives the connection itself: HttpStreamTransport, SseParser, StreamBudget, and EventStream::with_transport with a description of your own.

Projects

Three levels: your organization pays; a project is one of your customers, or an environment, with its own accounts, API keys, webhooks, limits and usage; an account is a linked WhatsApp number.

use wuapi::types::{AccountsListParams, ProjectCreateRequest};
use wuapi::Wuapi;

async fn projects(client: &Wuapi) -> Result<(), wuapi::Error> {
    // Organization key: create the project with your own id for the customer.
    let mut request = ProjectCreateRequest::new("Northwind Dental");
    request.external_id = Some("customer_8812".to_owned());
    let project = client.projects().create(request).await?;

    // Act inside it: every request carries the Wuapi-Project header.
    let northwind = client.with_project("ext:customer_8812")?; // or &project.id
    let accounts = northwind.accounts().list(AccountsListParams::default()).to_vec().await?;
    println!("{} has {} accounts", project.id, accounts.len());
    Ok(())
}

Wuapi::builder().project(..) does the same from the start. A resource outside the scope answers 404 not_found; a project key naming another project answers 403 forbidden.

Errors

Every failure is a wuapi::Error:

Variant When code()
Error::Api The API answered with a non-2xx status. Carries status, code, message, details, request_id and retry_after. the API's code, such as account_not_ready
Error::Timeout An attempt ran out of time and no retry was left or allowed. timeout
Error::Network The request could not be sent or the response could not be read. network_error
Error::Decode A 2xx response did not match the expected type. invalid_response
Error::Encode The request body could not be serialized. Nothing was sent. invalid_request
Error::Config No API key, or a bad project. Nothing was sent. configuration
use wuapi::types::SendTextMessageRequest;
use wuapi::{Error, Wuapi};

async fn send(client: &Wuapi, text: SendTextMessageRequest) {
    match client.messages().send(text).await {
        Ok(message) => println!("queued {}", message.id),
        Err(Error::Api { code, retry_after, .. }) if code == "account_not_ready" => {
            println!("the number is offline; retry after {retry_after:?}");
        }
        Err(error) => eprintln!(
            "{error} (status {:?}, request {:?})",
            error.status(),
            error.request_id()
        ),
    }
}

request_id is the x-request-id response header. Quote it when you contact support.

Configuration

use std::time::Duration;

use wuapi::{RetryPolicy, Wuapi};

fn client() -> Result<Wuapi, wuapi::Error> {
    Wuapi::builder()
        .api_key("wu_live_...")
        .base_url("https://api.wuapi.dev")
        .timeout(Duration::from_secs(20))
        .retry(RetryPolicy {
            max_retries: 4,
            ..RetryPolicy::default()
        })
        .project("ext:customer_8812")
        .build()
}

http_client(..) takes your own reqwest::Client, for a proxy or a shared connection pool. RetryPolicy::none() turns retries off.

An endpoint this version does not cover yet can be called through the same client, with the same auth, timeout and retry rules:

use wuapi::{Method, RequestParts, Wuapi};

async fn raw(client: &Wuapi) -> Result<serde_json::Value, wuapi::Error> {
    let parts = RequestParts::new(Method::Get, "/v1/me").retryable();
    client.http().request(parts).await
}

Types

wuapi::types holds one type per schema of the spec, and the params of every method.

  • Optional fields are Options and are left out of the request when None. A field that may be absent or null is an Option<Option<T>>: None leaves it out, Some(None) sends null (as in pacing: null, which resets an account's pacing).
  • Enums keep a value this version does not know in Unknown(String), and unions keep an unknown shape in Unknown(serde_json::Value), so a value the API adds later still parses.
  • Timestamps are ISO 8601 strings, as the API sends them.

Generated code

This crate, version 0.15.0, is generated from the wuapi OpenAPI spec: its types, methods, tests and this README. Do not edit it by hand. Report problems at wuapi.dev/support.

License

MIT