snaplyagentDeveloper docsSDK 2.3.0

SDK reference — Snaply Agent developer docs

Install & initialize

One call at app start. The SDK registers the device, opens a lightweight socket, and waits. It never captures on its own.

// call once, at app launch Snaply.configure(key: "snap_live_9f2kA7qX") // optional: tell us who the user is Snaply.identify(id: "usr_20481", name: "Maya Kowalski")
keyProduct API key. Use snap_test_… while integrating — test captures are free and watermarked.userOptional at init. Whatever your app knows — an ID, a name, both. This is how agents find the caller.

Identify the user

Identity is optional. Call it after login — or never. We link whatever you pass to the device ID, so agents can search by name, your ID, or the device. Anonymous devices get a short pairing code instead.

Snaply.identify({ id: "usr_20481", name: "Maya Kowalski" })
// not signed in? surface the pairing code:
Snaply.showCode() // e.g. "74-315" — agents search it
// logout: Snaply.reset()

Request lifecycle

When an agent requests a capture, the SDK shows the consent popup and emits events you can hook:

onRequestShown()Popup is on screen. Pause video or hide sensitive views if you need to.
onAllowed(capture)User tapped Allow. capture.id matches the console and webhook record.
onDenied()User declined. Nothing left the device.
onExpired()No response within 60s — the popup dismissed itself.
onLiveEnded(session)Live view stopped — by the user, the agent, or call end.
Privacy contract: mark any view snaply-redact and it's blacked out in every capture — even live view. Card fields and passwords are redacted by default.

Webhook payload

POSTed to your product's webhook URL on every approved capture. Signed with X-Snaply-Signature (HMAC-SHA256). We retry on 5xx for 24h.

{ "event": "capture.created", "capture_id": "cap_9f31d8", "product": "prd_acme_ios", "user": { "id": "usr_20481", "name": "Maya Kowalski" }, "device": { "id": "dvc_8f3a91c2", "os": "iOS 18.4", "app": "4.2.1" }, "mode": "ask_every_time", "requested_by": "dana@acme.dev", "image_url": "https://cdn.snaply.io/cap_9f31d8.png", "expires_at": "2026-10-08T14:32:00Z" }

Errors

401invalid_keyKey revoked or rotated — check product settings.
403mode_not_allowedLive view / session approval not enabled on this product or plan.
403origin_mismatchThe key was used from an app or domain that isn't this product's verified identity.
403workspace_suspendedThe account was suspended by Snaply — capture requests are rejected until it's reactivated. No data is deleted.
409device_offlineQueued — delivered when the device reconnects.
410request_expiredThe 60-second consent window passed.
429quota_exceededMonthly screenshot quota reached — upgrade or wait for the cycle.