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 verify webhooks.
- 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.
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
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;
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 Duration;
use ;
use Wuapi;
async
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 ;
use Wuapi;
async
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 ;
use Wuapi;
async
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 Duration;
use SendTextMessageRequest;
use Wuapi;
async
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 TryStreamExt;
use ;
use Wuapi;
async
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 ;
use Wuapi;
async
Verify each request with the raw body, before parsing it as JSON:
use Event;
use ;
/// `signature` is the `Wuapi-Signature` header.
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.
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 ;
use Wuapi;
async
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 SendTextMessageRequest;
use ;
async
request_id is the x-request-id response header. Quote it when you contact support.
Configuration
use Duration;
use ;
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 ;
async
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.10.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