Skip to main content

Conversations

How conversations work on the Travila platform — threads, messages, and the request lifecycle. Configuration, tool calling, and voice each have their own page.

Core Concepts​

Threads​

A thread is a conversation container. Each thread has:

  • A server-generated threadId (UUID) — use this as the conversation_key value on subsequent requests
  • An optional title — human-readable label you can set at creation time
  • Its own message history
  • Independent settings and generation config

Threads are scoped to the authenticated user. One user can have many threads.

Messages​

Messages are the content units within a thread. Each message has a role and content:

RoleDescription
ROLE_USERMessages from the end user
ROLE_ASSISTANTAI-generated responses
ROLE_SYSTEMSystem instructions (injected by the platform or via settings)
ROLE_TOOLResults from MCP tool calls

Conversation State​

Every thread maintains state that includes:

  • Message history (messageHistory) — the full ordered list of messages
  • Generation config — model, temperature, max tokens, etc.
  • Settings — system prompt, context management, interrupt policy
  • Run status — activeRunId (the runId of the in-progress run, or empty when idle)
  • Pending tool approvals — tools waiting for user approval before execution

Conversation Lifecycle​

1. Create a Thread​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/create-thread \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Support Chat"
  }'

The response returns { "thread": { "threadId": "<uuid>", ... } }. Use threadId as the conversation_key on all subsequent requests on this thread. X-On-Behalf-Of is required when calling with a backend secret key.

2. Send a Message​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/send-message \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "support-chat-001",
    "user_message": {
      "role": "ROLE_USER",
      "content": [
        { "type": "CONTENT_PART_TYPE_TEXT", "content": "How do I reset my password?" }
      ]
    }
  }'

When you send a message:

  1. The message is appended to the thread's history.
  2. A generation run starts asynchronously; the HTTP response returns with a runId.
  3. The LLM processes the conversation history and generates a response.
  4. If the model calls tools, tool execution happens automatically (or awaits approval).
  5. The assistant response is appended to messageHistory, annotated with generatedBy: <runId>.

If a prior run was still in progress and the thread's interrupt_policy is INTERRUPT (cancel ongoing), send-message also returns "interruptedPriorRun": true alongside the new runId.

To retrieve the completed assistant reply from an external client, poll conversation-state — see Async Generation.

3. Retrieve State​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/conversation-state \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "support-chat-001"
  }'

Returns messageHistory, activeRunId, usage, model, settings, generation config, and context-management settings. When a run is in progress, activeRunId holds the active run's ID; once settled, activeRunId is empty (or absent from the response) and the assistant message appears in messageHistory. See Async Generation for the full polling recipe.

4. List Threads​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/list-threads \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns all threads for the authenticated user.

Where to next​

PageCovers
GenerationAsync and synchronous generation, appending without generating
ConfigurationGeneration config, agent profiles, settings, context management
Tool CallingApprovals and client-side tools
Voice SessionsReal-time voice (in progress)