The Flume iframe is a page Flume hosts and you frame. It runs the whole flow: verify the user, search by photo, get an instant quote, save. Your backend starts it. Your page listens to it.
Who does what?
Section titled “Who does what?”| Actor | Responsibility |
|---|---|
| Your backend | Starts a session. Exchanges the connect code. Stores the user access token. Holds the partner key |
| Your page | Frames the iframe. Checks and handles its messages. Writes the saved item |
| Flume iframe | Draws every screen. Calls the Flume API with its own short-lived credential |
| Flume API | Verifies users, searches, prices, builds the save payload |
Your partner key and the user access token never reach the browser.
What is the lifecycle?
Section titled “What is the lifecycle?”The whole flow, from a click to a saved item. One open of the iframe, end to end. Lighter steps happen only the first time a user opens it.
Read this diagram as text
- The user clicks your button. Your page asks your backend to start a session.
- Your backend calls POST /start-iframe-session with the user, project and item.
- Flume returns iframe_url and session_uuid.
- Your backend passes both to your page.
- Your page starts the ready timer, adds the message listener, then sets the iframe src.
- The iframe posts flume:iframe_ready. Your page clears the timer.
- First time only: the user verifies their email, and the iframe posts flume:user_connected with a connect code.
- First time only: your page sends the connect code to your backend.
- First time only: your backend exchanges the code for the user access token and stores it.
- The user saves a product. The iframe posts flume:save_item with the save payload.
- Your page writes its record and replies flume:item_saved, or flume:item_save_failed.
- The iframe posts flume:close_iframe. Your page removes the iframe.
What is a session?
Section titled “What is a session?”An iframe session is one user working on one item of one project. Your backend starts it with POST /start-iframe-session. Flume keeps its state on the server.
| You send | Required fields | Purpose |
|---|---|---|
user | external_ref, email | Who is working |
project | external_ref | Where the result is filed in the user's Flume account |
item | external_id | What the user wants a product for |
host_origin | Yes | The exact origin of the page that frames the iframe |
| You get back | Use |
|---|---|
session_uuid | The session's id. Filter messages by it. Log it |
iframe_url | Set it as the iframe src at once. It holds the launch code |
The launch code works once, for 120 seconds. Never store, rebuild or reuse iframe_url.
When is a session reused?
Section titled “When is a session reused?”Flume reuses a session when the user, the project and the item are the same.
- The item is the same when its
external_id,name,item_type,labels, photo links and room names are unchanged. - A change to one of those starts a new session.
- Quantity, unit, ZIP code and unit price are not compared.
A reopened session restores the first of these that exists:
- A save that is still waiting for your page's reply.
- The instant quote.
- The search, at its last step.
- The category detection.
When does a session end?
Section titled “When does a session end?”| Event | What happens |
|---|---|
| The user closes the iframe | The session stays. A reopen resumes it |
| 12 hours pass since the session's first open | The iframe posts flume:close_iframe with reason expired. Start a session again |
| You revoke the user's access token | The session ends at its next call |
| The user's access token is replaced | The session ends at its next call |
| 30 days pass with no use | The session is dropped. The next open starts fresh |
- Reopening the same item does not restart the 12 hours.
- Inside those hours the iframe renews its own credential. You do nothing.
What must you build?
Section titled “What must you build?”| Piece | Where |
|---|---|
| A call to start a session | Backend |
| A call to exchange a connect code | Backend |
| A handler that writes a saved item | Backend or page |
| The iframe tag and the host snippet | Page |
The full example has all four in three small files.
What must you store?
Section titled “What must you store?”What you store, and what you never store. Two things are worth keeping. Everything else is used once and dropped.
Read this diagram as text
- From the exchange response, store the user access token, per external_ref, encrypted, on your server.
- From flume:save_item, store your own record keyed by save_uuid: the fields you map, the photo bytes, product_url, and the two ids an Open in Flume link needs (match.search_session_uuid and product.sku_uuid).
- Never store iframe_url or its launch code. Set it as the iframe src at once.
- Never store a connect code. Exchange it at once.
- Also never store image links or an Open in Flume link: both expire. Log session_uuid with your item id and user id.
| What | Why |
|---|---|
| The user access token, per user, on your server | Send it on the next open so the user skips the email step |
A stable external_ref per user | Flume finds the user's earlier work by it |
A stable project.external_ref and item.external_id | A reopen of the same item resumes where the user was |
session_uuid, with your item id and user id | Flume support asks for it |
save_uuid with your own record | So a retried save writes nothing twice |
| The mapped payload and copies of the image bytes | Image links expire |
product_url | The durable link back to the product in Flume |
What does the iframe not do?
Section titled “What does the iframe not do?”- It does not resize itself. You size the element. See Set up your page.
- It does not send an error message. See Timeouts and expiry for how failures show.
- It does not navigate your page. The iframe tag grants no top navigation.
- It does not call your backend. All it sends you are the messages.
- It has no theming options you can set from your page.
- There is no npm package for the host snippet. Copy the file from Set up your page.