# Ask a question (approval, yes/no, or reply)

Set webhookId to a saved Reply webhook (whk_…) to receive answered, expired, or canceled events using its configured subscriptions. Live Activity presentations return immediately with accepted: 0 and queued device attempts; subsequent reads report provider acceptance. Queued work is not delivery or a human answer.

HTML: https://notify.belweave.ai/docs/api/postInteractions

Required scopes: `interactions:create`, `notifications:send`

```http
POST /api/agent/interactions
Authorization: Bearer ntf_your_token
```

## Operation schema

```json
{
  "summary": "Ask a question (approval, yes/no, or reply)",
  "description": "Set webhookId to a saved Reply webhook (whk_…) to receive answered, expired, or canceled events using its configured subscriptions. Live Activity presentations return immediately with accepted: 0 and queued device attempts; subsequent reads report provider acceptance. Queued work is not delivery or a human answer.",
  "operationId": "postInteractions",
  "security": [
    {
      "bearer": [
        "interactions:create",
        "notifications:send"
      ]
    }
  ],
  "x-notify-scopes": [
    "interactions:create",
    "notifications:send"
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string"
      },
      "required": false
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            },
            "prompt": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000
            },
            "kind": {
              "type": "string",
              "enum": [
                "approval",
                "yes_no",
                "reply"
              ]
            },
            "imageUrl": {
              "type": "string",
              "maxLength": 2048,
              "format": "uri"
            },
            "url": {
              "type": "string",
              "maxLength": 2048,
              "format": "uri"
            },
            "deviceIds": {
              "minItems": 1,
              "maxItems": 50,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              }
            },
            "group": {
              "type": "string",
              "pattern": "^dgrp_[A-Za-z0-9_-]{8,64}$"
            },
            "expiresInSeconds": {
              "default": 900,
              "type": "integer",
              "minimum": 30,
              "maximum": 86400
            },
            "presentation": {
              "type": "string",
              "enum": [
                "notification",
                "live_activity"
              ]
            },
            "style": {
              "type": "string",
              "enum": [
                "approval",
                "shell",
                "verdict",
                "signal"
              ]
            },
            "primaryLabel": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "secondaryLabel": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "callback": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "maxLength": 2048,
                  "format": "uri"
                },
                "token": {
                  "type": "string",
                  "minLength": 16,
                  "maxLength": 512
                },
                "target": {
                  "type": "object",
                  "properties": {
                    "connectorId": {
                      "type": "string",
                      "pattern": "^conn_[A-Za-z0-9_-]{8,64}$"
                    },
                    "route": {
                      "type": "string",
                      "pattern": "^(@|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)$"
                    },
                    "path": {
                      "type": "string",
                      "maxLength": 2048,
                      "pattern": "^\\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$"
                    }
                  },
                  "required": [
                    "connectorId",
                    "route",
                    "path"
                  ]
                }
              }
            },
            "webhookId": {
              "type": "string",
              "pattern": "^whk_[A-Za-z0-9_-]{1,100}$"
            }
          },
          "required": [
            "title",
            "prompt",
            "kind"
          ],
          "allOf": [
            {
              "not": {
                "required": [
                  "group",
                  "deviceIds"
                ]
              }
            },
            {
              "if": {
                "properties": {
                  "presentation": {
                    "const": "live_activity"
                  }
                },
                "required": [
                  "presentation"
                ]
              },
              "then": {
                "properties": {
                  "kind": {
                    "enum": [
                      "approval",
                      "yes_no"
                    ]
                  },
                  "prompt": {
                    "maxLength": 240
                  },
                  "expiresInSeconds": {
                    "maximum": 28800
                  }
                },
                "not": {
                  "anyOf": [
                    {
                      "required": [
                        "url"
                      ]
                    },
                    {
                      "required": [
                        "imageUrl"
                      ]
                    }
                  ]
                }
              },
              "else": {
                "not": {
                  "anyOf": [
                    {
                      "required": [
                        "style"
                      ]
                    },
                    {
                      "required": [
                        "primaryLabel"
                      ]
                    },
                    {
                      "required": [
                        "secondaryLabel"
                      ]
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/InteractionCreated"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Missing, unknown, revoked, or expired token",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "The token lacks a required scope or the account lacks permission",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Not found for this account",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

Resolve schema references against [OpenAPI](https://notify.belweave.ai/openapi.json).