Tough Tongue AI Logo
Return Home

API Integration Guide

This guide helps you use our public API to create and embed high-quality conversation experiences in your application.

API Experience Overview

Our API offers a complete lifecycle for building conversational experiences. You start by creating scenarios that define the conversation structure and AI behavior. Your end users can then interact with these scenarios, which creates a session — a running instance of a scenario. Each user interaction is recorded in the session, and you can retrieve transcripts and detailed results using the Get Session Details endpoint.

You can use our APIs to build rich, interactive conversational features that enhance your application. We'll cover 4 parts here:

  • Creating API token
  • Using API to create scenario
  • Embedding scenario in your application
  • Managing scenarios and sessions

1. Creating API token

To use our API, you'll need to create an API token for authentication from API Keys page. Once you have an API key, you can test the endpoints in our API Playground.

Loading API keys...

Your API token should be included in all API requests as a bearer token in the Authorization header.

2. Using API to create scenarios

Here's how you can programmatically create a new scenario:

POST https://api.toughtongueai.com/api/public/scenarios

Create a new conversation scenario

Bash
1curl -X POST https://api.toughtongueai.com/api/public/scenarios \
2-H "Authorization: Bearer " \
3-H "Content-Type: application/json" \
4-d '{
5  "name": "Customer Support Training",
6  "description": "Internal description for your team",
7  "user_friendly_description": "Practice handling difficult customer inquiries",
8  "ai_instructions": "You are a frustrated customer with a billing issue...",
9  "is_public": true,
10  "is_recording": true
11}'

Required Fields

  • name: The name of your scenario
  • description: Internal description for your reference
  • ai_instructions: Instructions for the AI on how to behave in this scenario

Optional Fields

  • user_friendly_description: Description shown to users
  • pdf_context: Additional context in PDF format (base64 encoded)
  • rubrik: Evaluation criteria
  • is_public: Whether the scenario is publicly accessible
  • passcode: Optional passcode protection
  • is_recording: Whether to record conversations
  • restrict_analysis: Whether to restrict analysis features

3. Embedding scenarios in your application

You can embed conversation scenarios directly in your application using our iframe embed code with three available styles:

HTML
1<!-- Basic Embed (Standard size) -->
2<iframe
3  src="https://app.toughtongueai.com/embed/basic/SCENARIO_ID"
4  width="100%"
5  height="600px"
6  frameborder="0"
7  allow="microphone"
8></iframe>

Replace SCENARIO_ID with your actual scenario ID (e.g., 67bf56c23f44cdf6055a8165).

Live Embed Preview

Select an API key above to load your scenarios for selection

Customization Options

Customize your embed by adding query parameters to the iframe URL:

  • name: Custom conversation name (e.g., ?name=Support%20Training)
  • color: Accent color (e.g., ?color=violet-500)
  • showPulse: Toggle pulse animation (e.g., ?showPulse=false)
  • background: Background color (e.g., ?background=black)
  • hidePoweredBy: Hide branding (e.g., ?hidePoweredBy=true)

For more detailed integration options, after creating a scenario, you can access its dedicated integration page by clicking the "Integration" button on any scenario detail page.

4. Managing scenarios and sessions

You can list all scenarios and track conversation sessions using public APIs.

4.a Listing Scenarios

GET https://api.toughtongueai.com/api/public/scenarios

List all scenarios

Bash
1curl -X GET https://api.toughtongueai.com/api/public/scenarios \
2-H "accept: application/json" \
3-H "Authorization: Bearer "

4.b Listing Sessions for a specific scenario

GET https://api.toughtongueai.com/api/public/sessions

List sessions for a specific scenario

Bash
1curl -X GET "https://api.toughtongueai.com/api/public/sessions?scenario_id=SCENARIO_ID" \
2-H "accept: application/json" \
3-H "Authorization: Bearer "

4.c Listing Featured Scenarios

GET https://api.toughtongueai.com/api/public/featured-scenarios

List featured and public scenarios

Bash
1curl -X GET https://api.toughtongueai.com/api/public/featured-scenarios \
2-H "accept: application/json" \
3-H "Authorization: Bearer "

This endpoint returns a list of scenarios that are featured. This response along with iframe experience can be useful to offer a quick start experience for the for users.

4.d Getting Session Details

GET https://api.toughtongueai.com/api/public/sessions/SESSION_ID

Get detailed session information including transcript and evaluation data

Bash
1curl -X GET https://api.toughtongueai.com/api/public/sessions/SESSION_ID \
2-H "accept: application/json" \
3-H "Authorization: Bearer "

This endpoint provides information about a completed session, including access to the conversation transcript, evaluation results, and improvement suggestions. Replace SESSION_ID with the actual session ID from the sessions list.

Next Steps

  • Test API endpoints in our API Playground to experiment with requests and responses
  • Join our Developer Community to ask questions and share your projects
  • Book a demo to learn more about our API and how to use it

Need Help?

If you encounter any issues or have questions about our API, please contact our support team at help@getarchieai.com