Skip to main content

​
Conversations

Conversations are interactions between identities (users) and your assistants through channels. The API supports both standard chat messages and streaming conversations for real-time interactions.

​
Send Message

POST /conversation/:identity_id/chat/:channel_id

Sends a message to start or continue a conversation with an identity through a specific channel.
​
:identity_id
string
required
Identity unique identifier
​
:channel_id
string
required
Channel unique identifier

​
Request Body

​
string
required
Message text content
​
object
Additional metadata for the message

​
Response

​
message
string
Success message
​
data
object

​
Streaming Conversations

GET /conversation/:identity_id/streaming

Establishes a streaming connection for real-time conversation. Returns Server-Sent Events (SSE) stream.
​
:identity_id
string
required
Identity unique identifier

​
Query Parameters

​
string
required
Channel unique identifier
​
string
required
Initial message to send

​
Response

The endpoint returns a Server-Sent Events (SSE) stream. Each event contains: 
data: {"type": "token", "content": "partial text"}
data: {"type": "token", "content": " more text"}
data: {"type": "complete", "content": "full response"}

​
Event Types

  • token - Partial response token (streaming)
  • complete - Complete response message
  • error - Error occurred during streaming

​
How Conversations Work

  1. Identity - Each conversation is associated with an identity (user)
  2. Channel - Messages are sent through a specific channel (WhatsApp, web, custom, etc.)
  3. Assistant - The channel’s connected worker/assistant processes the message
  4. Memory - Conversation history is automatically stored and retrieved
  5. Response - The assistant generates a response based on context and memory

​
Streaming vs Standard Messages

​
Standard Messages (/chat/:channel_id)

  • Synchronous request/response
  • Returns complete response after processing
  • Best for: Simple integrations, webhooks, batch processing

​
Streaming (/streaming)

  • Real-time token-by-token response
  • Lower perceived latency
  • Best for: Interactive UIs, chat applications, real-time experiences

​
Examples

​
Send Standard Message

curl -X POST https://api.plati.ai/conversation/identity123/chat/channel456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, I need help with my order",
    "metadata": {
      "source": "web"
    }
  }'

​
Streaming Conversation (JavaScript)

const identityId = 'identity123';
const channelId = 'channel456';
const message = 'Tell me about your products';

const eventSource = new EventSource(
  `https://api.plati.ai/conversation/${identityId}/streaming?channel_id=${channelId}&message=${encodeURIComponent(message)}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === 'token') {
    // Append token to UI
    appendToChat(data.content);
  } else if (data.type === 'complete') {
    // Final response
    console.log('Complete:', data.content);
    eventSource.close();
  } else if (data.type === 'error') {
    console.error('Error:', data.content);
    eventSource.close();
  }
};

​
Streaming Conversation (cURL)

curl -N -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.plati.ai/conversation/identity123/streaming?channel_id=channel456&message=Hello"

​
Conversation Flow

  1. User sends a message through a channel
  2. System identifies the user’s identity
  3. Retrieves conversation history and memory
  4. Routes to appropriate worker/assistant
  5. Assistant processes with full context
  6. Response is generated and sent back
  7. Conversation history is updated

​
Memory Integration

Conversations automatically use the identity’s memory system:
  • Previous conversation context
  • User preferences and data
  • Stage information
  • Custom associations
See the Memory API for more details.

​
Error Handling

Common error scenarios:
  • 404 - Identity or channel not found
  • 400 - Invalid message format
  • 401 - Authentication failed
  • 500 - Server error during processing

​
Next Steps

Identity

Learn about identity management

Memory

Understand memory system

Channels

Set up communication channels

Stages

Track user journey stages