Conversation API

The Conversation API allows you to create and manage conversations within Helper. A conversation is a container for messages exchanged between a user and Helper.

For detailed API reference, see Create Conversation API Reference.

Create Conversation

POST /api/chat/conversation

Creates a new conversation and returns a conversation slug that can be used in subsequent API calls.

Headers

Request Parameters

Example Request Body

{
  "isPrompt": true
}

Response

Example Response

{
  "conversationSlug": "abc123def456"
}

Error Responses

Conversation Behavior

Status

New conversations have different initial statuses based on various factors:

• For isPrompt sources, conversations are created with a closed status
• For authenticated users who are identified as VIPs, conversations start with an open status
• For all other conversations, the default status is closed

Subjects

By default, conversations start with a generic subject. Helper will automatically generate a more specific subject based on the conversation content. For isPrompt conversations the subject is initially set to the prompt content, and then generated if the customer follows up.

Programming Patterns

Creating a Simple Conversation

// After obtaining a session token
const response = await fetch("https://helper.ai/api/chat/conversation", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${sessionToken}`,
  },
  body: JSON.stringify({ isPrompt: false }),
});
 
const { conversationSlug } = await response.json();

Starting a Conversation with Context

You can create a conversation and immediately add context by creating the conversation first, then using the Chat API to send an initial message:

// Create the conversation
const convResponse = await fetch("https://helper.ai/api/chat/conversation", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${sessionToken}`,
  },
  body: JSON.stringify({ isPrompt: false }),
});
 
const { conversationSlug } = await convResponse.json();
 
// Now send an initial message with the Chat API
// See the Chat API documentation for details

API References

For complete API specifications, refer to these API reference pages:

• Create Session API Reference - Authenticate and create a session token
• Create Conversation API Reference - Start a new conversation
• Send Message API Reference - Exchange messages within a conversation