API Best Practices
Our goal with the Tough Tongue Public API is to help you create end-to-end conversational workflows that feel native to your application.
Sample Repositories
We've created these demonstrations to help you get started:
- Simple Course: Uses iframe, iframe lifecycle events, and analysis: repo, deployment
- AI Course Creation: Uses OpenAI to create scenarios on Tough Tongue AI: repo, deployment
In this guide, we've covered tips to get the best out of our public APIs. Here is a video walkthrough of this guide and demo repos.
1. Picking the Right Type of Iframe
We currently offer three types of iframe experiences:
Full Iframe
Use this when you need the complete experience—recording the session, getting a detailed analysis, and so on.
Basic Iframe
In most situations, the Basic option is your go-to. It gives an interactive experience with an avatar that simulates an AI agent.
Minimal Iframe
The Minimal option is best for glimpses or previews. For example, you can place it on a landing page or in newsletters to provide a quick look at what your feature does. It's ideal for lightweight marketing content or basic introductions to the platform.
By default, we don't transcribe the session for basic and minimal iframe (and hence evaluation isn't available). In order to transcribe, you should enable the transcription option.
2. Customizing Your Scenario
While you can use the API to set up scenarios, we recommend customizing their appearance and behavior in our Advanced Scenario Creator UI. It offers rich controls and options, such as:
Avatar Look & Voice
Pick from different avatars and voices to match your brand or style.
Conversation Strategy
- Talkative Mode: The AI agent leads the conversation and continues talking even if the human remains silent.
- Quiz Mode: After the session, it jumps directly to an analysis (like a quiz), and no avatar is displayed.
- Conductor Strategy: Precisely control the AI's actions, including when it speaks or ends the call.
A good pattern is to create a few well-defined scenarios in the Scenario Editor and then embed those scenarios in multiple places using our APIs. This way, you build a great experience once and reuse it as often as you like.
3. Delivering an End-to-End Experience
A typical workflow on our platform involves these steps:
Create a Scenario
After you design it in the Scenario Editor, you embed it in your application via an iframe.
Fetch Session Details
Session is a running instance of a scenario which identifies the user's interaction with that scenario. Fetching session details API requires a Sessions ID. You can get session ID either from creating a unique iframe link for each user or catching from an iframe lifecycle event.
Post Session Analysis
Use our "scenario analyze" API to process the transcript recorded during the session, giving you a complete analysis of the interaction.
Note: We do not by default trigger session analysis for sessions created using iFrame. So you do need to hit this API in order for us to give the analysis report.
Using Full Iframe: When you enable the Boolean option Disable Participant Access to Analysis, it tells us to store and analyze the transcript without showing the analysis directly to the end user. If this is disabled in your iframe settings, we won't record the transcript in case of full iframe. Why is it this way? To avoid sending your users to our analysis page, which can be disruptive to your application experience. We also expect most developers will build an evaluation page on their website. We plan to make this more intuitive in the future.
To map a session to a particular user, simply pass the user's name and email as query parameters in the iframe. Then, when calling the list sessions API, you can filter by the email to fetch the relevant session data. Refer to section on pre-populating user information on how to pass user data as URL parameter in Iframe.
4. User Management
If you use our full iframe and map sessions to specific users, you can:
- Display each user's experience and transcript in your own UI.
- Show them how they performed and what they can improve, using our analysis or your own custom logic built on our data.
- Offer a richer, personalized interaction for each user, leveraging both the transcript and our analysis results.
5. Purchase and Monetization
We also provide an option to attach a dollar value to a scenario. This means you can monetize your AI-driven content. You can use our LIST purchase API to get details of purchase. This way, you can manage payments and track user entitlements with ease.
We're excited to see how you'll use the Tough Tongue Public API. If you have any questions or need more help, feel free to email me or book a 15-minute chat here.
Happy building!