Skip to main content

​
Overview

The Text Chat API enables developers to integrate TalkifAI text agents into websites, mobile apps, and other applications using REST + Server-Sent Events (SSE) streaming. Base URL: https://api.talkifai.dev/v1/chat Authentication:
  • Session Creation: X-API-Key or X-Studio-Token header
  • All Other Requests: Authorization: Bearer {session_token} (JWT)

​
Endpoints

Create Session

POST /sessions — Create a new chat session

Send Message

POST /sessions/{id}/messages — Send message (SSE stream)

Get History

GET /sessions/{id}/messages — Retrieve message history

End Session

POST /sessions/{id}/end — End session and cleanup

Create Voice Session

POST /voice-sessions — Create LiveKit voice session

​
Authentication

​
Session Creation (Server-Side)

Two authentication methods supported: Method 1: API Key 
POST /v1/chat/sessions
X-API-Key: tk_live_your_api_key_here
Method 2: Studio Token 
POST /v1/chat/sessions
X-Studio-Token: better_auth_session_token

​
All Other Requests (Client-Side)

Authorization: Bearer {session_token}
Session tokens are JWTs returned from /sessions endpoint, valid for 24 hours.

​
Request/Response Models

​
CreateSessionRequest

{
  "agent_id": "string (required)",
  "metadata": "object (optional)",
  "user_identifier": "string (optional, email for memory)"
}

​
CreateSessionResponse

{
  "conversation_id": "string",
  "session_token": "string",
  "agent_name": "string",
  "greeting": "string or null",
  "agent_model": "string"
}

​
SendMessageRequest

{
  "message": "string (required, max 10000 chars)"
}

​
Message

{
  "role": "user | assistant",
  "content": "string",
  "timestamp": "ISO 8601 datetime",
  "token_count": "number or null"
}

​
MessagesResponse

{
  "messages": "Message[]",
  "count": "number"
}

​
EndSessionResponse

{
  "success": "boolean",
  "message": "string"
}

​
SSE Event Types

When sending messages, the response is streamed via Server-Sent Events:
EventDataDescription
stream_start{"agent_name": "..."}Agent started generating
chunk{"delta": "text..."}Incremental text delta
tool_call{"name": "...", "status": "executing"}Tool execution started
tool_result{"name": "...", "status": "completed"}Tool execution finished
handoff{"to": "agent_name"}Multi-agent handoff
stream_end{"usage": {...}, "end_session": bool}Response complete
error{"error": "message"}Error occurred

​
Error Codes

StatusCodeDescription
400message_too_longMessage exceeds 10,000 characters
400not_text_agentAgent is not text architecture
401invalid_api_keyAPI key missing or invalid
401invalid_tokenJWT token expired or invalid
402insufficient_creditsOrganization has no credits
403conversation_mismatchConversation ID doesn’t match token
404session_not_foundSession expired or not found
503—Billing service unavailable

​
Session Lifecycle

1. Create Session (POST /sessions)
   ↓
   Returns: conversation_id, session_token
   ↓
2. Send Messages (POST /sessions/{id}/messages)
   ↓
   SSE stream with chunks
   ↓
3. End Session (POST /sessions/{id}/end)
   ↓
   Cleanup: billing, memory, analysis, webhooks
Auto-Expiry: Sessions expire after 30 minutes of inactivity.

​
SDK Support

Official SDKs:
  • JavaScript/TypeScript (coming soon)
  • Python (coming soon)
  • React Hook (see guide)
Community SDKs:
  • Check npm and PyPI for community-maintained packages

​
Rate Limits

EndpointLimit
Create Session100/minute per API key
Send Message60/minute per session
Get History100/minute per session
End Session60/minute per session
Rate limits are per API key or session token.

​
CORS

Allowed Origins:
  • All origins allowed (*)
  • Configure in your API key settings
Allowed Methods:
  • GET, POST, OPTIONS
Allowed Headers:
  • Content-Type
  • Authorization
  • X-API-Key
  • X-Studio-Token
  • Origin

​
Webhooks

When a chat session ends, a webhook is sent if configured on the agent: 
{
  "event": "chat.ended",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "conversation_id": "chat_...",
    "agent_id": "agent_...",
    "agent_name": "Support Bot",
    "duration": 300,
    "message_count": 20,
    "input_tokens": 150,
    "output_tokens": 300,
    "total_cost": 0.0045
  }
}

​
Next Steps

Create Session

Start with POST /sessions to create your first chat session.

Integration Guide

See the complete guide with React/Next.js examples.