docs/backend-doc/02-create-conversation.md

How to Create a Conversation

Summary

Create a new conversation with a student personality and coach pairing. This initializes the conversation context and returns a conversation ID for sending messages.

Endpoint

POST /api/conversations/create

• Authentication: Required (Basic Auth)
• Content-Type: application/json

Example Request

curl -X POST http://localhost:3000/api/conversations/create \
  -u "teacher_wang:cz-2025" \
  -H "Content-Type: application/json" \
  -d '{
    "studentPromptId": "grade_3",
    "coachPromptId": "empathetic",
    "title": "數學課專注力問題"
  }'

Example Response

{
  "conversation": {
    "id": "403db363-ee32-4ec9-aae0-2017af936d52",
    "userId": "d05a01b7-804e-4cde-9d59-7af8e30ed0b1",
    "studentPromptId": "grade_3",
    "studentName": "小三學生",
    "coachPromptId": "empathetic",
    "coachName": "王老師",
    "title": "數學課專注力問題",
    "createdAt": "2025-01-27T10:30:00Z"
  },
  "message": "Conversation created successfully"
}

Required Fields

• studentPromptId (string) - Student grade level
  • Options: grade_1 through grade_9, or coach_direct
• coachPromptId (string) - Coach personality type
  • Options: empathetic, structured, balanced

Optional Fields

• title (string) - Custom conversation title
• include3ConversationSummary (boolean) - Include summary of last 3 conversations with this student

Student Personalities

• grade_1 through grade_6 - Elementary school (國小) students
• grade_7 through grade_9 - Junior high school (國中) students
• coach_direct - Direct coach conversation (no student simulation)

Coach Types

• empathetic - 王老師 (Empathetic, supportive approach)
• structured - 李老師 (Structured, systematic approach)
• balanced - 陳老師 (Balanced approach)

Next Steps

After creating a conversation, use the returned conversation.id to:

• Send messages to the student
• Ask the coach for help
• Add system messages for context

Reference

See OpenAPI spec for details: /docs/openapi.yaml → /api/conversations/create