Expand description
§wuapi Rust SDK
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
reqwestandtokio. 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-threadThe 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,PUTandDELETErequests and requests with an idempotency key are retried on timeouts, network errors,429and5xx, with exponential backoff and jitter (2 retries by default). A request that is not idempotent (thePATCHupdates) is retried only when it never reached the API (the connection could not be opened) or was refused with429. ARetry-Afterheader is honored; one longer than 60 seconds fails at once with the wait inError::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()andnext_item()lose nothing when their future is dropped, so they can be raced in aselect!.into_stream()andinto_items()turn the stream into afuturesStream.event.datais the envelope exactly as received, andevent.parse()types it; a type newer than this version parses asEvent::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
Authorizationheader only, and only tohttps(or tohttpon this machine).Wuapi::builder().stream_base_url(..)points at another stream host. wuapi::streamhas the parts for a caller that drives the connection itself:HttpStreamTransport,SseParser,StreamBudget, andEventStream::with_transportwith 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 whenNone. A field that may be absent ornullis anOption<Option<T>>:Noneleaves it out,Some(None)sendsnull(as inpacing: 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 inUnknown(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.17.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
Re-exports§
pub use client::Wuapi;pub use error::Error;pub use error::WebhookVerificationError;pub use http::ClientBuilder;pub use http::HttpClient;pub use http::Method;pub use http::Request;pub use http::RequestParts;pub use http::RetryPolicy;pub use http::encode_path;pub use http::random_key;pub use meta::API_KEY_ENV;pub use meta::DEFAULT_BASE_URL;pub use meta::IDEMPOTENCY_HEADER;pub use meta::PROJECT_HEADER;pub use meta::PACKAGE_NAME;pub use meta::USER_AGENT;pub use meta::VERSION;pub use pagination::CursorPage;pub use pagination::Paginator;pub use stream::EventStream;pub use stream::StreamError;pub use stream::StreamErrorKind;pub use stream::StreamEvent;pub use stream::StreamItem;pub use stream::StreamOptions;pub use webhook::verify_webhook_with_tolerance;pub use webhook::compute_signature;pub use webhook::verify_signature;pub use webhook::verify_webhook;
Modules§
- client
- error
- Errors.
- http
- The HTTP runtime: client configuration, timeouts, retries and idempotency keys.
- meta
- Constants of this crate and of the API.
- pagination
- Cursor pagination.
- resources
- One module per resource of the API.
- stream
- The event stream runtime: one long-lived
GETanswered withtext/event-stream, reconnected and resumed by itself. - types
- The API’s types: every schema of the spec, and the params of every method.
- webhook
- Webhook signature verification.