Skip to main content

Build a support conversation the user can return to

Section: DOC-MA-conversations#add-conversations-to-your-app.

Give a customer a support conversation they can leave and reopen with its history intact. Create a thread only for a new conversation, send the first question, follow its reply and reuse that thread when the customer returns.

This recipe uses backend requests for one authenticated user. Start with one unresolved turn at a time so the application can correlate the accepted run with its reply.

Before you start​

Section: DOC-MA-conversations#start-here.

Have the deployment's backend secret key and the authenticated user represented by X-On-Behalf-Of. Derive the user from your application session; do not accept an arbitrary client-supplied identity. For browser/mobile credentials, follow authentication.

In the requests below, replace support-chat-001 with the threadId returned by creation. Keep that identifier in your application's conversation record. Use the first-call quickstart if credentials are not yet set up.

Recipe: answer a support question, then reopen the same thread​

Section: DOC-MA-conversations#conversation-lifecycle.

The customer asks how to reset their password. Your app creates one thread, sends that question and displays the correlated answer. On a later visit, it lists the user's threads and loads the selected thread's state instead of creating a duplicate conversation.

Step 1: Create the support thread once​

Section: DOC-MA-conversations#1-create-a-thread.

curl -X POST https://api.travila.ai/api/v1/llm/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"
}'

Reference: Create a new conversation thread · Request fields.

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

Step 2: Send the customer’s first question​

Section: DOC-MA-conversations#2-send-a-message.

Use the created thread ID in this request and retain the returned runId. A lost response is an unresolved send; follow retry and reconciliation before attempting it again.

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

Reference: Send a message to a conversation · Request fields.

When no prior run is active, an accepted send follows this flow. If another run is active, the interrupt policy may queue, reject, ignore or replace it:

  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 interruptPolicy is INTERRUPT_POLICY_CANCEL_ONGOING (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.

Step 3: Display the reply for the accepted run​

Section: DOC-MA-conversations#3-retrieve-state.

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

Reference: Get full conversation state · Request fields.

Returns messageHistory, the run status fields, totalUsage, settings, generation config, and context-management settings. While a run is in progress, activeRunning is true and activeRunId holds the run's ID; after activity stops, activeRunning is absent. Match any assistant reply by generatedBy and check the outcome for your run; a failed or queued request may have no completed reply. See Async Generation for the full polling recipe.

Render messages by stable identity and numeric 64-bit sequence. Keep the submitted operation pending or unknown until its outcome is correlated; missing activeRunning alone does not prove success. Offer a read/reconnect action when your bounded wait ends.

Step 4: Reopen the conversation on the next visit​

Section: DOC-MA-conversations#4-list-threads.

When the user returns, list their threads, let them choose this support conversation and read its state with the selected thread ID. Send a follow-up with that same ID to continue the history.

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

Reference: List conversation threads · Request fields.

Returns one page of the authenticated user's threads — 50 by default and up to 200 with limit — ordered by lastMessageAt descending, then threadId descending. Follow nextPageToken until a response has no token. See list-threads for the cursor and concurrency rules.

Finished result: the customer sees the original question and its correlated reply, can reopen that thread, and adds follow-ups to its existing history. A short page of threads is not a complete inventory when a continuation token is present.

Recover the same conversation when a reply is missing​

Section: DOC-MA-conversations#core-concepts.

After a lost connection, reload the existing thread with the same authenticated user. Keep its threadId as the conversationKey; a title is a display label, not the identity used for recovery.

Merge messageHistory by message ID and numeric sequence and render each message according to its role. Read current activity separately from the accepted question’s result. lastRunStatus is the latest recorded outcome and can describe newer work, while an assistant message’s generatedBy can identify its run.

Use the reconnect recipe for a pending or unknown turn, tool approvals when a decision is waiting, and the state reference for exact fields. Reopening history does not require another create or send request.

Section: DOC-MA-conversations#related.

Document ID: DOC-MA-conversations. Section identities and revisions.