Complete your first support-chat turn

Section: DOC-MA-conversations-quickstart#send-your-first-agent-message.

Complete your first chat turn: create a thread, send a question and read the reply for that accepted run. Use the credentials configured for your deployment and save the conversation identifier so the user can continue the same conversation.

Use this recipe from your backend with one test user and one new conversation. The goal is a visible reply for the run you started, not just four successful HTTP calls. Keep the same user and returned thread ID throughout.

Prerequisites

Section: DOC-MA-conversations-quickstart#prerequisites.

Start with the account and application credentials provisioned for your deployment. Use the authentication guide to choose the credential type for your integration. The current public path uses the legacy default project; arbitrary project headers do not create or select another project.

A secret key (sk_*) carrying the users:impersonate scope (created in your Travila dashboard). See the API Key Integration Guide, or request one from your account admin — ask for that scope explicitly.
A user id to act as. Any stable identifier from your own system works; the examples below use user_123.

Every call needs a user

A secret key identifies your tenant, not a person. Most endpoints act on a specific user's data, so each request below passes X-On-Behalf-Of. Leave it off and the call fails with 401 authenticated user_id is required — see Acting as a user.

Using a publishable key (pk_*) instead? Drop X-On-Behalf-Of and send Authorization: Bearer <user-jwt> — the user comes from the JWT.

Step 1: Confirm the test user’s credentials

Section: DOC-MA-conversations-quickstart#step-1-list-threads.

Check that your API key works by listing your conversation threads.

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.

Response — an empty list since this is a fresh account:

{}

Reference: List conversation threads · Response fields.

The threads key can be absent instead of []; treat an absent list as empty (see Body encoding).

On an existing account, a nonempty list is also valid. If authentication fails, correct the credential pair before creating a thread. This read verifies that the intended user scope is usable without starting paid generation.

Step 2: Start one conversation for that user

Section: DOC-MA-conversations-quickstart#step-2-create-a-thread.

A thread is a conversation container with its own message history and settings. It belongs to the user named in X-On-Behalf-Of, and only that user's requests can reach it.

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": "My First Thread"
}'

Reference: Create a new conversation thread · Request fields.

Response:

{
  "thread": {
    "threadId": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
    "title": "My First Thread",
    "createdAt": "2026-04-23T16:34:02.673Z",
    "updatedAt": "2026-04-23T16:34:02.673Z"
  }
}

Reference: Create a new conversation thread · Response fields.

Use the returned threadId as the conversationKey value in subsequent requests on this thread.

Copy the returned ID into both later requests. The UUID shown in the example is illustrative; using it unchanged does not select the thread you just created.

Step 3: Ask one question and save the run ID

Section: DOC-MA-conversations-quickstart#step-3-send-a-message.

Send a message and the platform will generate an AI response asynchronously.

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": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "What can you help me with?"
      }
    ]
  }
}'

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

Response — retain this accepted generation run's runId:

{
  "runId": "64403669-5989-4ec3-ad9c-d84223f9679f"
}

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

Responses are async

send-message returns immediately. The assistant reply is produced in the background; timing depends on the model, tools and load. Retrieve it by polling conversation-state — see Async Generation for the full recipe.

Send this question once. If the response is lost, follow retry and reconciliation rather than posting it again to see whether anything happened. Keep the UI pending until the original operation is understood.

Step 4: Read the reply for that run

Section: DOC-MA-conversations-quickstart#step-4-check-conversation-state.

Retrieve the full conversation state, including messages, settings, and generation status.

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": "b81d5345-c1f9-4fb9-b558-a6327c75b842"
}'

Reference: Get full conversation state · Request fields.

Response — this successful first-turn example has a matching assistant reply and completed status:

{
  "messageHistory": [
    {
      "role": "ROLE_USER",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "What can you help me with?"
        }
      ],
      "timestamp": "2026-04-23T22:43:44.123Z",
      "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d",
      "sequence": "1"
    },
    {
      "role": "ROLE_ASSISTANT",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "I can assist you with a variety of tasks..."
        }
      ],
      "timestamp": "2026-04-23T22:43:51.653Z",
      "messageId": "3f2d44de-8db6-4f67-8e51-5c600902491b",
      "sequence": "2",
      "generatedBy": "64403669-5989-4ec3-ad9c-d84223f9679f",
      "usage": {
        "promptTokens": 359,
        "completionTokens": 65,
        "totalTokens": 424
      },
      "model": "google/gemini-3.1-flash-lite"
    }
  ],
  "lastRunStatus": "AGENT_STATUS_COMPLETED"
}

Reference: Get full conversation state · Response fields.

While generation is still in progress, activeRunning is true, activeRunId equals the runId from the previous step, and the assistant message has not yet been appended. In this isolated first-turn example, the matching reply appears after completion. In queued or concurrent flows, idle and lastRunStatus can describe a different run; retain an unknown outcome until you can correlate the request. See Async Generation for the polling recipe.

Finished result: the state contains the question, an assistant reply whose generatedBy matches the retained run, and a correlated completed outcome. A failed result is a completed attempt at this recipe with a visible failure, not an empty successful answer.

Read with a delay and an overall deadline. If the deadline arrives first, stop automatic polling and offer another state refresh. Once the turn is resolved, send a follow-up using the same conversation ID to continue.

Extend the working conversation

Section: DOC-MA-conversations-quickstart#whats-next.

Keep this first working thread as your baseline. Add one capability at a time and repeat the send/result check so a file, tool or profile change has an observable outcome.

I want to...	Go to
Understand auth methods, scopes, and key rotation	Authentication & API Keys
Learn how conversations and threads work	Conversations Guide
Use MCP tools in conversations	Agent tools guide
Upload and manage files	Storage Guide
Browse all API endpoints	API Reference

Upcoming recipe: set up the project before issuing credentials

Status: Upcoming — not yet available.

Section: DOC-MA-conversations-quickstart#first-project-setup

For a new support application, create the project before issuing its first credentials:

Enter the application name and choose a supported data region.
Follow the project’s pending, ready or needs-action outcome. Resolve unfinished dependencies before the first call.
Once ready, deliberately issue the credentials for the application.
On reload, return to the same setup rather than creating another project or secret.

Finished result: one ready project and separately issued credentials. Project creation, readiness and credential creation are separate actions.

The quickstart above currently uses your provisioned account and legacy default project. The new project-creation API and setup flow are not yet available.

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

Prerequisites​

Step 1: Confirm the test user’s credentials​

Step 2: Start one conversation for that user​

Step 3: Ask one question and save the run ID​

Step 4: Read the reply for that run​

Extend the working conversation​

Upcoming recipe: set up the project before issuing credentials​