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://dev.api.toughtongueai.com/api/public/scenarios

Create a new conversation scenario

Bash
1curl -X POST https://dev.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  "session_analysis": {
12    "admin_email": "admin@example.com",
13    "is_auto_analysis": true,
14    "is_auto_submit": true
15  }
16}'

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
  • session_analysis: Configuration for session analysis
    • admin_email: Email address to send analysis reports to
    • is_auto_analysis: Whether to automatically trigger analysis when session ends
    • is_auto_submit: Whether to automatically submit session data without user interaction

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://dev.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

Embedding Private Scenarios

For private scenarios, you need to generate a short-lived access token (valid for 1 hour) to enable iframe access. Only scenario creators can generate access tokens for their scenarios. The token is automatically converted to a secure cookie for seamless authentication.

Step 1: Generate Access Token

Bash
1curl -X POST https://dev.api.toughtongueai.com/api/public/scenario-access-token \
2  -H "Authorization: Bearer YOUR_API_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "scenario_id": "SCENARIO_ID"
6  }'

Step 2: Embed with Access Token

Use the access token as the scenarioAccessToken query parameter. The system will automatically convert this to a secure cookie for authentication:

HTML
1<!-- Private scenario embed with access token -->
2<iframe
3  src="https://dev.toughtongueai.com/embed/SCENARIO_ID?scenarioAccessToken=YOUR_ACCESS_TOKEN"
4  width="100%"
5  height="800px"
6  frameborder="0"
7  allow="microphone"
8></iframe>

Important Notes:

  • Parameter Name: Use scenarioAccessToken (not accessToken)
  • Access tokens expire after 1 hour - generate new tokens as needed
  • Only scenario creators can generate access tokens for their scenarios
  • The token is automatically converted to a secure cookie, enabling seamless authentication across iframe boundaries
  • For production use, generate tokens server-side and pass them securely to your frontend

How Authentication Works:

  1. Your server generates an access token using your API key
  2. You pass the token to the iframe via scenarioAccessToken parameter
  3. The iframe automatically converts the token to a secure cookie
  4. All subsequent requests use the cookie for authentication
  5. The cookie expires when the token expires (1 hour)

Pre-populating User Information

You can pre-populate user information by adding URL parameters to your embed URL for all embed styles (Full, Basic, and Minimal):

HTML
1<!-- Embed with pre-populated user information -->
2<iframe
3  src="https://dev.toughtongueai.com/embed/SCENARIO_ID?userName=John%20Doe&userEmail=john@example.com"
4  width="100%"
5  height="800px"
6  frameborder="0"
7  allow="microphone"
8></iframe>

Available User Parameters

  • userName: The user's full name
  • userEmail: The user's email address

When both parameters are provided, the user credentials dialog will be skipped automatically. This is useful for integrations where user information is already available in your application.

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)

Dynamic Variables

For scenarios that use dynamic variables in their AI instructions, you can pass variable values directly through the iframe URL using t_ prefixed parameters.

HTML
1<!-- Embed with dynamic variables -->
2<iframe
3  src="https://dev.toughtongueai.com/embed/SCENARIO_ID?t_company_name=Acme%20Corp&t_user_role=Manager&t_interview_type=Technical"
4  width="100%"
5  height="800px"
6  frameborder="0"
7  allow="microphone"
8></iframe>

Dynamic Variables Notes:

  • Prefix all dynamic variables with t_ followed by the variable name
  • Variable names should match exactly what's defined in the scenario's AI instructions (e.g., {{ company_name }})
  • URL-encode special characters in variable values (spaces become %20)
  • Only scenarios that use dynamic variables in their AI instructions will benefit from this feature
  • If variables are not provided, the scenario will run with default behavior (no variable substitution)

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.

Handling Iframe Events

Embedded scenarios emit events that your application can listen for to track session lifecycle. These events are sent via the standard window.postMessage API.

Available Events

  • onStart: Emitted when a session begins (agent is connected)
  • onStop: Emitted when a session ends (agent is disconnected)
  • onSubmit: Emitted when post-session data submission is completed

Event Payload Structure

Bash
1// All events follow this format:
2{
3  event: 'onStart' | 'onStop' | 'onTerminated' | 'onSubmit',  // Event type
4  sessionId: string,                           // Unique session identifier
5  timestamp: number                            // Unix timestamp in milliseconds
6}

Listening for Events

Add this code to the page that hosts your iframe to listen for events:

Bash
1// Add this code to your page that hosts the iframe
2window.addEventListener('message', (event) => {
3  // Optional: verify the origin for security
4  // if (event.origin !== 'https://dev.toughtongueai.com') return;
5

6  const data = event.data;
7

8  if (data && data.event) {
9    switch (data.event) {
10      case 'onStart':
11        console.log('Session started:', data);
12        // Handle session start: initialize analytics, etc.
13        break;
14

15      case 'onStop':
16        console.log('Session stopped:', data);
17        // Handle session end
18        break;
19

20      case 'onSubmit':
21        console.log('Submission completed:', data);
22        // Handle submission completion: redirect to results, etc.
23        break;
24    }
25  }
26});

For more detailed examples and a live demo of iframe events, visit the Integration page for any of your scenarios by clicking the "Integration" button on the 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://dev.api.toughtongueai.com/api/public/scenarios

List all scenarios

Bash
1curl -X GET https://dev.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://dev.api.toughtongueai.com/api/public/sessions

List sessions for a specific scenario with optional email filtering

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

This endpoint lists all sessions for a specific scenario. You can optionally filter sessions by user email. The scenario_id parameter is required, while user_email is optional.

4.c Listing Featured Scenarios

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

List featured and public scenarios

Bash
1curl -X GET https://dev.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://dev.api.toughtongueai.com/api/public/sessions/SESSION_ID

Get detailed session information including transcript and evaluation data

Bash
1curl -X GET https://dev.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.

4.e Analyzing Session Data

POST https://dev.api.toughtongueai.com/api/public/sessions/analyze

Run evaluation and improvement analysis on a completed session

Bash
1curl -X POST https://dev.api.toughtongueai.com/api/public/sessions/analyze \
2-H "accept: application/json" \
3-H "Content-Type: application/json" \
4-H "Authorization: Bearer " \
5-d '{"session_id": "SESSION_ID"}'

This endpoint allows you to analyze a completed session by running both evaluation and improvement analysis. It uses the session's stored transcript and the scenario's rubric to perform this analysis. Replace SESSION_ID with the ID of the session you want to analyze.

4.f Listing Purchases

GET https://dev.api.toughtongueai.com/api/public/purchases

List all the purchases across all scenarios in your account

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

This endpoint returns a list of all purchases made across all scenarios in your account. It includes details such as the purchase amount, status, and buyer information. This is useful for tracking revenue and user engagement with your paid scenarios.

4.g Creating Scenario Access Tokens

POST https://dev.api.toughtongueai.com/api/public/scenario-access-token

Generate a short-lived access token for private scenario embedding

Bash
1curl -X POST https://dev.api.toughtongueai.com/api/public/scenario-access-token \
2-H "accept: application/json" \
3-H "Content-Type: application/json" \
4-H "Authorization: Bearer " \
5-d '{"scenario_id": "SCENARIO_ID"}'

This endpoint generates a short-lived access token (valid for 1 hour) that can be used to embed private scenarios in iframes. Only scenario creators can generate access tokens for their scenarios. The token should be appended to the iframe URL as a query parameter:?scenarioAccessToken=YOUR_ACCESS_TOKEN

Security Best Practices:

  • Generate access tokens server-side to keep your API token secure
  • Never expose access tokens in client-side source code
  • Refresh tokens before they expire to maintain uninterrupted access

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