Quick Start

This guide will walk you through the steps to quickly test out the API and start a conversation.

We will start with a stock replica and persona. You’ll be using the stock replica ID rfe12d8b9597 (Nathan) and stock persona ID p9a95912 (Sales Coach). You can run this directly in the API documentation interface after entering your API key.

Step 1: Create a Conversation

1. Endpoint: POST /v2/conversations

2. Description: This endpoint creates a new joinable conversation with the specified replica and persona. You can add a custom conversational context to make the interaction more personalized and fun.

   • Conversational Context: This is an additional context that you can provide on top of the existing context in the persona. It’s a way to refine or make the conversation more specific for a particular session.

3. Request Body Example with Personalized Conversational Context:

{
  "replica_id": "rfe12d8b9597",
  "persona_id": "p9a95912",
  "conversation_name": "Improve Sales Technique",
  "conversational_context": "I want to improve my sales techniques. Help me practice handling common objections from clients and closing deals more effectively."
}

• Explanation: In this example, the conversational_context is set to focus on how to improve the participant’s sales technique. This context will be used in addition to the persona’s default context, making the conversation more tailored and engaging.

4. Response: The API will return a JSON object with details about the conversation, including a conversation_url that you can use to join the conversation.

Step 2: Join the Conversation

• Response Example:

{
    "conversation_id": "c9152e3d6b9414cf",
    "conversation_name": "Improve Sales Technique",
    "conversation_url": "https://yourapi.com/conversations/abc123/join",
    "status": "active",
    "callback_url": "",
    "created_at": "2025-06-30T04:07:20.991294Z"
}

• Join the Conversation: Use the conversation_url to join the conversation directly.

The conversation will timeout and end after 4 minutes by default.

Extra Credit!

• Experiment with Different Combinations: Don’t hesitate to mix and match different Replicas and Personas, along with varying contexts. For example, try pairing a different Replica with the Sales Coach persona and see how the conversation changes when you switch the context. This experimentation can lead to unique and surprising interactions.

Enjoy exploring the diverse possibilities and have fun creating dynamic conversations!