powsoo_show_card reference

powsoo_show_card is the single tool definition Powsoo uses. Paste it into your voice platform’s agent or assistant configuration.

Retell — server-side custom function

Set the function type to Server-side and the URL to https://api.powsoo.com/v1/retell/tools/show-card.

{
  "type": "function",
  "name": "powsoo_show_card",
  "description": "Display an interactive card on the user's screen and wait for their tap response. Use this whenever you want the user to confirm captured data (emails, phone numbers, addresses, names), present choices, or collect structured input visually instead of asking them to spell it back.",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Short heading shown at the top of the card"
      },
      "description": {
        "type": "string",
        "description": "Optional explanatory text below the title"
      },
      "fields": {
        "type": "array",
        "description": "Editable rows shown to the user",
        "items": {
          "type": "object",
          "properties": {
            "label": { "type": "string" },
            "value": { "type": "string" },
            "type": {
              "type": "string",
              "enum": ["text", "email", "phone", "address", "date", "select", "multiselect", "consent"]
            },
            "editable": { "type": "boolean", "default": true },
            "options": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": { "type": "string" },
                  "label": { "type": "string" }
                }
              }
            }
          },
          "required": ["label"]
        }
      },
      "actions": {
        "type": "array",
        "description": "Buttons the user can tap. The chosen action's value is returned to you.",
        "items": {
          "type": "object",
          "properties": {
            "label": { "type": "string" },
            "value": { "type": "string" },
            "style": { "type": "string", "enum": ["primary", "secondary", "danger"] }
          },
          "required": ["label", "value"]
        },
        "minItems": 1
      }
    },
    "required": ["title", "actions"]
  },
  "execution_message_description": "Showing a card on screen for the user to confirm or edit.",
  "speak_during_execution": false,
  "speak_after_execution": false
}

Vapi — assistant tools array

"async": false is required — it tells the assistant to wait for the card result before continuing.

{
  "type": "function",
  "async": false,
  "function": {
    "name": "powsoo_show_card",
    "description": "Display an interactive card on the user's screen and wait for their tap response.",
    "parameters": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "description": { "type": "string" },
        "fields": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": { "type": "string" },
              "value": { "type": "string" },
              "type": { "type": "string", "enum": ["text", "email", "phone", "address", "date", "select", "multiselect", "consent"] },
              "editable": { "type": "boolean", "default": true },
              "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } } }
            },
            "required": ["label"]
          }
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": { "type": "string" },
              "value": { "type": "string" },
              "style": { "type": "string", "enum": ["primary", "secondary", "danger"] }
            },
            "required": ["label", "value"]
          },
          "minItems": 1
        }
      },
      "required": ["title", "actions"]
    }
  }
}

Parameters

Parameter	Type	Required	Description
title	string	✓	Short heading at the top of the card.
description	string	—	Optional sub-text below the title.
fields	Field[]	—	Editable rows. Omit for a buttons-only card.
actions	Action[]	✓	At least one button the user can tap.

Field

Property	Type	Required	Description
label	string	✓	Shown to the user. Also the key in the result fields map.
value	string	—	Pre-filled value (STT-captured). User can edit before confirming.
type	FieldType	—	Input widget to render. Defaults to text. See Field types.
editable	boolean	—	Whether the user can edit this field. Defaults to true.
options	Option[]	—	Required for select and multiselect types.

Action

Property	Type	Required	Description
label	string	✓	Button text displayed to the user.
value	string	✓	Returned in the result action field when tapped.
style	"primary" | "secondary" | "danger"	—	Visual style. Defaults to "secondary".

Return value

{
  "status": "edited",
  "action": "confirm",
  "fields": { "Email": "john.smith@acme.com" },
  "edited": ["Email"]
}

Field	Type	Description
status	"confirmed" | "edited" | "skipped"	confirmed = no edits made. edited = at least one field changed. skipped = skip/cancel action tapped.
action	string	The value of the tapped action button.
fields	Record<string, string>	All field values after any edits. Keys are field label values.
edited	string[]	Labels of fields changed from the pre-filled value.