[FEATURE] A way to know if an embedded typeform is over quota and "closed"

[patcon]

Hi there! Thanks for much for all the maintenance work on this library 🙌

I've been using the iframe embed SDK. We're now putting the app into sleeper mode after running it actively with a plan. Was hoping to opportunististically show the free plan;s typeform when the monthly quota is still there, and otherwise, skip the intake survey. This doesn't seem to be possible from the app that's embedding the typeform.

Things I've checked:

1. whether retrieve form endpoint of the Create API changes at all once the quota is hit. It doesn't seem to, neither in settings.is_public or otherwise. E.g., https://api.typeform.com/forms/aYU17R3F
2. whether any error or extra payload is delivered from a "closed" (overquota) typeform to let the app know that something is up.

Neither of these work. But I think this would support users.

Potential solutions are:

1. return an error from onStarted or onReady when the form can't be loaded, or
2. show some indication of over-quota status in the public API for forms.

I know that I'm now wondering whether other form tools are better for the long-tail after our consultation, to keep collecting slow feedback after our main event. I'll be idly looking to other tools in the future if Typeform can't support this.

Thanks for considering this feature request!

[mathio]

Hello @patcon

thank you for the suggestion. I dont know how many customers would be interested in such feature, but I do agree it would be nice to have. Unfortunately I can not promise any timeline, but we will look into it.

---

I like your suggestion to indicate if the form is open in one of the callbacks. This will mitigate any need for server-side implementation on your side, as API endpoints are not available to be called from browser.

I think the onStarted is not executed for closed forms because, well, they can not be started (I need to double check this). However the onReady payload might be the correct place to put this information.

[patcon]

Thanks for thinking on it! I understand the constraint on commiting :)

I'll keep tabs on this issue for our next consultation. For now, we'll just close typeform after the gig, and disable it from our app.

---

API endpoints are not available to be called from browser

Small point of clarification: can't we already use the read endpoint of the Create API without auth from the browser? Like I seem to be able to curl this, so I presume my app could use fetch() on it and get a status there, yeah? Would just be a little off-road, and not actually supported by the Embed SDK in an official way

https://api.typeform.com/forms/aYU17R3F

---

I think the onStarted is not executed for closed forms because, well, they can not be started (I need to double check this). However the onReady payload might be the correct place to put this information.

And just to make sure I understand, the possible states seem to be like so:

1. unpublished (aka not public)
   • ❓ all forms start this way, but can't re-enter this state via UI. can re-enter this state only via PATCH request to settings.is_public: false with API personal access token.
   • iframe: HTML says "Sorry, you can't access this typeform until its creator says so."
   • ❌ onReady doesn't execute (screenshot of error in console)
   • ❌ onStarted never gets chance to execute thru any interaction
   • GET https://api.typeform.com/forms/:formId returns error object

     {"code":"INVALID_AUTHORIZATION","description":"This form is not public."}

2. published (aka public)
   • ❓ state after clicking the "publish" button in UI, or PATCH to settings.is_public: true with API personal access token
   • iframe: HTML renders form
   • ✅ onReady executes
   • ✅ onStarted executes
   • GET https://api.typeform.com/forms/:formId returns response object
3. closed
   • ❓ done through UI, via "access & scheduling" menu, and settings.is_public: true
   • iframe: HTML says "Hey :) This typeform is now closed"
   • ✅ onReady executes
   • ❌ onStarted never gets chance to execute thru any interaction
   • GET https://api.typeform.com/forms/:formId returns response object
4. over-quota (aka "private" in docs), and settings.is_public: true
   • ❓ different than "closed" state?
   • iframe: HTML says "Hey :) This typeform is now closed"
   • ✅ onReady executes
   • ❌ onStarted never gets chance to execute thru any interaction
   • GET https://api.typeform.com/forms/:formId returns response object (same as when published)

Does all of the above look right? This was what I was seeing in my testing, but maybe I'll confirm [EDIT: updated]

EDIT2: Seems that 1 & 2 are mutually exclusive states, but 3+4 are the same (this wasn't clear to me at first, sorry)

[mathio]

It looks like you might know more about this aspect of typeforms than I do @patcon . Good job writing this down. Maybe we could use one of the callbacks (onReady seems like a good candidate) and indicate all of the states in the payload. Or should be introduce new callbacks for those state? I will discuss with the team.

[patcon]

heh thanks :) Just wanted to thoroughly explore for my own understanding, and glad if it helps y'all choose more thoughtfully.

All said and done, and additional onReady payload feels like it would accomodate anything I can think of! A status with a value like "open" or "closed" would be a minimum that would seem to align with existing documentation. Another state for "closed (overquota)" might be nice, but wouldn't add anything for my use-case, as I'm happy for the app to treat both as equivalent :)

Thanks you again for thinking on this!

[donovantc]

We'd also see a lot of value in having this. Currently, if there is any error creating the widget (e.g. incorrect form ID), then https://www.typeform.com/explore/ would display within our website. Ideally, we'd want to navigate the user somewhere else on error. Although, it's an unlikely scenario it could occur if we are dynamically injecting the formId, when a/b testing for example.

[mathio]

@donovantc I think this is different use case, since there is a difference if the form is closed or there is a 404 error 🤔

[donovantc]

@mathio I guess the issue is that none of the existing callbacks fire if the form cannot be found due to incorrect form Id, unless I'm missing something?

Having an onError callback would be ideal in my opinion.

This may be different to the case mentioned above. Happy to file a separate issue if that would be better?

[mathio]

Yes, this is correct. We will need to implement a post message on our side to notify the embed about any errors.

[mathio]

Hi @patcon

I have some good news. We were able to prioritize your feature request and I just opened a PR: #670

The onReady callback will receive isClosed boolean value to indicate if the form is closed. Forms can be closed manually, based on timestamp or when a response limit is reached (set manually per form, or the limit of your account plan).

Unfortunately we can not implement this callback for forms that are not published or for invalid URLs (form not found) at this time.

I hope this helps your use case.

[patcon]

Thanks @mathio! This def addresses and improves use-cases like mine in the future :)

[typeform-ops-gha]

🎉 This issue has been resolved in version @typeform/embed-v5.3.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀