Complete your first support-chat turn

Section ID: Guide/j84jbpl2s2#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 ID: Guide/j84jbpl2s2#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.

Info: 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 ID: Guide/j84jbpl2s2#step-1-list-threads

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

Response example: List conversation threads. Example identifiers and values are illustrative; substitute authorized values.

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 ID: Guide/j84jbpl2s2#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.

Request example: Create a new conversation thread. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response:

Response example: Create a new conversation thread. Example identifiers and values are illustrative; substitute authorized values.

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 ID: Guide/j84jbpl2s2#step-3-send-a-message

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

Request example: Send a message to a conversation. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response — retain this accepted generation run's runId:

Response example: Send a message to a conversation. Example identifiers and values are illustrative; substitute authorized values.

Info: 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 ID: Guide/j84jbpl2s2#step-4-check-conversation-state

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

Request example: Get full conversation state. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

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

Response example: Get full conversation state. Example identifiers and values are illustrative; substitute authorized values.

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 ID: Guide/j84jbpl2s2#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

Section ID: Guide/j84jbpl2s2#first-project-setup

Status: Upcoming — not yet available.

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

1. Enter the application name and choose a supported data region.

2. Follow the project’s pending, ready or needs-action outcome. Resolve unfinished dependencies before the first call.

3. Once ready, deliberately issue the credentials for the application.

4. 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: Guide/j84jbpl2s2