Interactions API

Interaction APIs create the durable conversation record around workflow execution so transcripts, metadata, summaries, recordings, and debugging context remain inspectable.

Key concepts

Term	Definition
Interaction	The stored conversation session shown in the Interactions product area.
Interaction execution	Runtime processing that advances the workflow for a specific interaction.
Finalization	The step that marks an interaction complete and stores final metadata.
Transcript	Ordered messages, tool calls, tool results, and timestamps.

What you can do

Action	Endpoint
Create an interaction	POST /llm-chain/interaction/create
Execute an interaction	POST /llm-chain/interaction/:id/execute
Finalize an interaction	POST /llm-chain/interaction/:id/finalize

Create an interaction

Create the record before processing messages when your integration wants Octo to preserve the conversation in the Interactions UI.

curl -X POST "$OCTO_BASE_URL/llm-chain/interaction/create" \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowVersionId": "workflow_version_123",
    "channel": "web",
    "context": { "spaceId": "space_123", "externalUserId": "customer_123" }
  }'

Execute an interaction

Execute the interaction when a user message, voice event, or integration event should advance the workflow.

curl -X POST "$OCTO_BASE_URL/llm-chain/interaction/interaction_123/execute" \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can I reschedule my appointment?",
    "context": { "channel": "web" }
  }'

Finalize an interaction

Finalize after the conversation has ended so Octo can store closing metadata, summaries, sentiment, topic, and duration fields when configured.

curl -X POST "$OCTO_BASE_URL/llm-chain/interaction/interaction_123/finalize" \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "completed" }'

Lifecycle

Stage	What happens
Created	The interaction gets an ID, channel, workflow version, and initial context.
Executing	Messages and runtime events advance the workflow graph.
Waiting	The workflow may pause until a resume event or user response arrives.
Finalized	Summary, topic, sentiment, duration, and transcript data are ready for review.

Debugging

1. Open Interactions and search for the created interaction.
2. Confirm the channel, workflow version, and timestamps.
3. Review transcript messages and tool call records.
4. Use the execution path to identify the node where processing stopped or failed.
5. Open the workflow version used by the interaction before making changes.

FAQ

Can I execute without creating an interaction? Direct workflow execution exists for integration use cases, but interaction APIs are preferred when the conversation should be visible in the product history.

Can finalized interactions be edited? Treat finalized interactions as read-only records. Create a new interaction for a new conversation.

Related pages

• Interactions - product UI for transcript and metadata review
• AI Workflow Execution - direct workflow execution and resume routes
• Runtime Guide - graph execution and failure behavior