Interactive Choice Actions

Backend AI Dev Spec

SDK Actionsv1.0

Interactive Choice Actions

These SDK actions let the AI bot present structured interactive UI directly inside the chat widget. The backend fires an action; the widget renders the card; the user interacts; the widget sends the response back. No custom frontend code needed — the widget handles all rendering and state.

showMultipleChoiceshowMultipleCheckboxesshowCalendlyshowLeadForm

How It Works — General Flow

Both Actions

Bot decides to ask a question

Your AI logic determines it needs structured input from the user (e.g. qualifying question, preference selection, survey step).

Backend fires the SDK action

Your bot calls sendAction() with either 'showMultipleChoice' or 'showMultipleCheckboxes' and the required data payload.

Widget renders the card

The Captivate widget receives the action and renders the appropriate interactive card above the chat input. The user sees the question and options.

User makes their selection

For showMultipleChoice: user taps one option and it's immediately submitted. For showMultipleCheckboxes: user checks one or more options, then taps the Submit button.

Widget sends response action back

The widget calls sendAction() with the response action ID and the user's selection(s). The card becomes read-only.

Important: The card is dismissed after the user responds. Your bot should listen for the response action and continue the conversation flow accordingly. The widget does not re-show the card on reconnect — store the response server-side.

Overview

Single Select

Renders a card with a question and a list of radio-style options. The user can pick exactly one option. As soon as they tap an option, the selection is locked and the response is sent back automatically — no separate submit button.

Action ID (inbound)

showMultipleChoice

Response Action ID (outbound)

multiple_choice_response

Inbound Action Shape

Bot → Widget

This is the action your backend sends to the widget via the SDK.

json

{
  "id": "showMultipleChoice",
  "data": {
    "questionId": "q_pricing_tier",     // string — unique ID for this question
    "question": "Which plan are you interested in?",  // string — prompt shown to user
    "options": [                         // string[] — list of choices (min 2)
      "Starter",
      "Growth",
      "Enterprise"
    ]
  }
}

Data Field Reference

Field	Type	Status	Description
`questionId`	`string`	required	Unique identifier for this question. Used in the response so you can match the answer to the question.
`question`	`string`	required	The prompt text displayed above the options. Keep it concise — one sentence works best.
`options`	`string[]`	required	Array of option labels. Minimum 2 items. Each string becomes a selectable button in the widget.

Outbound Response Shape

Widget → Bot

After the user selects an option, the widget fires this action back to your bot. Listen for multiple_choice_response in your action handler.

json

{
  "id": "multiple_choice_response",
  "data": {
    "questionId": "q_pricing_tier",     // matches the questionId you sent
    "selectedOption": "Growth"          // the exact label string the user clicked
  }
}

1. Bot sends action

typescript

// In your AI bot handler
await sendAction('showMultipleChoice', {
  questionId: 'q_use_case',
  question: 'What best describes your use case?',
  options: [
    'Customer Support',
    'Lead Generation',
    'Internal Knowledge Base',
    'E-commerce Assistant',
  ],
});

2. Widget renders the card — user picks "Lead Generation"

3. Widget sends response back to bot

json

{
  "id": "multiple_choice_response",
  "data": {
    "questionId": "q_use_case",
    "selectedOption": "Lead Generation"
  }
}

4. Bot receives response and continues flow

typescript

// In your action received handler
if (action.id === 'multiple_choice_response') {
  const { questionId, selectedOption } = action.data;
  // Store the answer, branch conversation logic
  await handleUserAnswer(questionId, selectedOption);
}

Implementation Notes

The card locks immediately after the user taps — no double-submission possible.
If options is an empty array or question is missing, the widget silently ignores the action. Always validate before sending.
questionId can be any unique string — use a UUID or a descriptive slug. It is echoed back verbatim in the response.
The widget does not persist the card across page reloads. Store the response server-side as soon as you receive it.
You can send multiple showMultipleChoice actions in sequence — each renders as a new card above the input.
The option labels are displayed exactly as provided — no truncation. Keep labels under ~40 characters for best mobile display.

Side-by-Side Comparison

Quick Reference

Property	showMultipleChoice	showMultipleCheckboxes	showCalendly
Interaction type	Single option tap	Multi-checkbox + Submit	Calendly booking embed
Submit button	None — auto-submits	Required — user taps Submit	Handled by Calendly UI
Response action	multiple_choice_response	multiple_checkboxes_response	calendly_booking_complete
Response data	selectedOption (string)	selectedOptions (string[])	Empty — use webhook
Constraints	Not applicable	minSelections / maxSelections	Not applicable
Custom label	Not applicable	submitLabel field	message field (intro only)
Full booking data	Not applicable	Not applicable	Via Calendly webhook
Use when	Exactly one answer needed	One or more answers needed	Scheduling a meeting

Captivate Engage · Interactive Actions Spec · For internal backend dev use