Switch the WhatsApp AI auto-reply on or off
- Credentials
- OAuth access token
- Scopes
settings:write- Role
- Owners and admins only. Staff get
403 forbidden. - Subscription
- Needs an active plan. Otherwise
403 subscription_locked. - Idempotency
- Send an
Idempotency-Keyheader. A retry with the same key does the work once.
It answers customers in the merchant's name, so it is off until the owner or an admin turns it on, and a connected AI app can only do so with settings:write. Setting the value it already has changes nothing. enabled must be true or false, else 400 bad_request. getWhatsAppChannel reports it as aiEnabled.
Access: OAuth scope settings:write; owner/admin only; write-gated by the subscription.
merchantOAuth settings:writeAuthorizationBearer <token>OAuth 2.1 (authorization code + PKCE S256, public clients, dynamic registration) for connected AI apps. Effective power is scopes granted AND the person's role today AND the plan. orders:refund, billing:write and team:write are opt-in on the consent screen. Write implies read for marketing:read and messages:read, so a grant holding marketing:write passes a marketing:read check, and messages:send passes messages:read.
Scope: settings:write
storeId*stringA store the person can reach. Any other id answers 404, never 403.
Idempotency-Key*stringRequired on every write. Minted on the device when the person taps, reused on every retry. A write without one, or with one that does not match the pattern, is refused with 422 validation_error. Scoped to the token's subject, remembered 24 hours. A replay returns the first 2xx response with Idempotent-Replay: true; a request still running answers 409 in_flight; the same key with a different method, path or body answers 409 idempotency_key_reused; non-2xx results are not remembered. If the key store cannot be read nothing is processed and the answer is 503 idempotency_unavailable: retry with the same key.
^[A-Za-z0-9_-]{8,128}$application/json- body
enabled*booleantrue: the assistant answers customers in the shop's name. Off by default, and deliberately the merchant's own decision.
OK
application/json- response
data*curl -X PUT 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/whatsapp/ai' \ -H 'Authorization: Bearer <access_token>' \ -H 'Idempotency-Key: <unique_key>' \ -H 'Content-Type: application/json' \ -d '{ "enabled": false}'{ "data": { "enabled": true }}Look again for a catalogue on the WhatsApp account POST
Attaching a catalogue to a number is the one step Meta will not let ShopEazy do for a merchant (it needs an admin of their business), so they do it once in WhatsApp Manager and this tells us it is done. It looks for the catalogue again and, when found, syncs the listings to it in the background. `found: false` means there is still none to attach. WhatsApp refusing, in Meta's own words, or no longer accepting the connection (the number has to be connected again), is 422 `provider_error`. WhatsApp down, busy or not answering is 503 `provider_unavailable` with `Retry-After`: nothing was changed, and it is never answered as `found: false`, which only ever means WhatsApp answered and there is still no catalogue. Safe to repeat: it only looks and syncs, and the same `Idempotency-Key` replays the first answer. Access: OAuth scope `settings:write`; owner/admin only; write-gated by the subscription.
Recent conversations GET
Needs `messages:read`. Access: OAuth scope `messages:read` (a grant with `messages:send` passes too); not write-gated. Paged: `{ items, nextCursor }`, `limit` (default 50, at most 100) and an opaque `cursor`. It pages through the newest 100.