Text Chat API

https://api.talkifai.dev/v1/chat

POST /v1/chat/sessions
X-API-Key: tk_live_your_key_here
Content-Type: application/json

{
  "agent_id": "5b710eca-ee67-4c3a-aeb6-8b541f451b40"
}

{
  "conversation_id": "chat_5b710eca_user123_1705312800000",
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "agent_name": "Support Agent",
  "greeting": "Hello! How can I help you today?",
  "agent_model": "gpt-4o-mini"
}

POST /v1/chat/sessions/{conversation_id}/messages
Authorization: Bearer {session_token}
Content-Type: application/json

{
  "message": "What are your business hours?"
}

event: stream_start
data: {"agent_name": "Support Agent"}

event: chunk
data: {"delta": "Our business "}

event: chunk
data: {"delta": "hours are 9am–6pm EST."}

event: stream_end
data: {"usage": {"input_tokens": 12, "output_tokens": 18}, "end_session": false}

const response = await fetch(
  `https://api.talkifai.dev/v1/chat/sessions/${conversationId}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${sessionToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ message: userInput })
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();
let fullText = '';
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });

  // SSE events are separated by blank lines
  const blocks = buffer.split('\n\n');
  buffer = blocks.pop(); // keep any incomplete trailing block

  for (const block of blocks) {
    let eventType = '';
    let dataStr = '';

    for (const line of block.split('\n')) {
      if (line.startsWith('event: ')) eventType = line.slice(7).trim();
      else if (line.startsWith('data: ')) dataStr = line.slice(6);
    }

    if (!dataStr) continue;
    const data = JSON.parse(dataStr);

    if (eventType === 'stream_start') {
      // Show loading indicator
    } else if (eventType === 'chunk') {
      fullText += data.delta;
      // Update chat bubble with streaming text
    } else if (eventType === 'tool_call') {
      // Optionally show "Looking that up..." indicator
    } else if (eventType === 'tool_result') {
      // Tool finished — agent continues
    } else if (eventType === 'handoff') {
      // { from_agent, to_agent } — a subagent took over
    } else if (eventType === 'stream_end') {
      setIsLoading(false); // clear loading state
      if (data.end_session) {
        // Agent called end_chat — close the session immediately
        endSession();
      }
    } else if (eventType === 'error') {
      setIsLoading(false); // clear loading — don't leave UI hanging
      showError(data.error || 'Something went wrong. Please try again.');
    }
  }
}

GET /v1/chat/sessions/{conversation_id}/messages
Authorization: Bearer {session_token}

{
  "messages": [
    {
      "role": "assistant",
      "content": "Hello! How can I help you today?",
      "timestamp": "2024-01-15T10:00:00+00:00",
      "token_count": null
    },
    {
      "role": "user",
      "content": "What are your business hours?",
      "timestamp": "2024-01-15T10:00:08+00:00",
      "token_count": null
    },
    {
      "role": "assistant",
      "content": "Our business hours are 9am–6pm EST, Monday through Friday.",
      "timestamp": "2024-01-15T10:00:09+00:00",
      "token_count": 18
    }
  ],
  "count": 3
}

POST /v1/chat/sessions/{conversation_id}/end
Authorization: Bearer {session_token}

{
  "success": true,
  "message": "Session ended successfully"
}

POST /sessions          → session_token + conversation_id
        ↓
POST /messages          → SSE stream (repeatable)
        ↓
POST /end               → billing cleanup + memory + webhooks