Interactions

When the assistant needs more information, it returns an interaction_required status. Send a follow-up message to continue.

How Interactions Work

Some tool calls require user input before the assistant can proceed. When this happens, the response status is interaction_required and the interaction field describes what the assistant is waiting for. Send a follow-up message to the same chat to continue the conversation.

Interaction Tools

Tool	Description
`presentStyleOptions`	Presents a list of visual styles for the user to choose from
`askBrandDetails`	Asks the user for brand information (colors, logos, guidelines)
`askSocialHandles`	Asks for social media handles to include in generated content
`presentStyles`	Shows available styles with previews for the user to select
`completeOnboarding`	Finalizes the onboarding flow after collecting user preferences
`dailySuggestion`	Offers a daily content suggestion for the user to accept or modify

Example Flow

The assistant presents style options and waits for the user to pick one.

1. Response with interaction_required

{
  "status": "interaction_required",
  "assistantText": "I found several styles that match. Which one would you like?",
  "toolCalls": [
    {
      "toolName": "presentStyleOptions",
      "toolCallId": "tc_abc123",
      "args": {
        "styles": [
          { "id": "style_1", "name": "Cinematic" },
          { "id": "style_2", "name": "Minimalist" },
          { "id": "style_3", "name": "Bold & Vibrant" }
        ]
      }
    }
  ],
  "interaction": {
    "toolCallId": "tc_abc123",
    "toolName": "presentStyleOptions",
    "description": "Presenting style options for user selection",
    "options": [
      { "id": "style_1", "name": "Cinematic" },
      { "id": "style_2", "name": "Minimalist" },
      { "id": "style_3", "name": "Bold & Vibrant" }
    ]
  },
  "error": null
}

2. Follow-up message to continue

{
  "message": "Let's go with Cinematic"
}

3. Assistant continues

{
  "status": "complete",
  "assistantText": "Great choice! I'll apply the Cinematic style to your video.",
  "toolCalls": [...],
  "interaction": null,
  "error": null
}