BotNotice Voice API

openapi: 3.2.0
info:
  title: BotNotice Voice API
  version: 1.0.0
  summary: AI disclosure notices, consent records and call receipts for websites and AI phone agents, plus an open dataset of AI disclosure laws.
  description: 'BotNotice shows a "you''re talking to AI" notice beside a website''s chat, keeps a tamper-evident record of every notice, checks consent before AI phone calls and keeps a receipt per call. Plans: Chatbot Disclosure $12.99/month per website; Disclosure + Records $29.99/month per website; Managed Compliance $199/month per website; 14-day free trial on plans with records; no sales call, sign up at https://botnotice.app. The scan and the law dataset need no key. The consent, voice and content endpoints take a per-site token from the dashboard (Voice page for the voice token, Content page for the content-register token). Nothing here is legal advice.'
  termsOfService: https://botnotice.app/legal/terms
  contact:
    name: BotNotice support
    email: support@botnotice.app
    url: https://botnotice.app/support
  license:
    name: 'Law dataset: CC BY 4.0'
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://botnotice.app
tags:
- name: Voice
  description: 'What an AI call must open with, and the receipt per call. Token: the site''s voice token (bni_…).'
paths:
  /api/voice/policy:
    get:
      tags:
      - Voice
      operationId: voicePolicy
      security:
      - voiceToken: []
      - {}
      summary: What a call for this site must open with
      description: The disclosure line, in the site's language, from its law determination. The site key (?k=) is enough to read it, since the line is spoken to every caller. Cache for up to an hour; policyVersion changes when the settings or the profile change.
      parameters:
      - name: k
        in: query
        required: false
        schema:
          type: string
        description: The site key, instead of the token
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoicePolicy'
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '402':
          description: No active plan
  /api/voice/event:
    post:
      tags:
      - Voice
      operationId: voiceEvent
      security:
      - voiceToken: []
      summary: The receipt for a call
      description: Point the voice platform's webhook here. Understands BotNotice's own shape, Retell's webhooks (call_started, call_ended, call_analyzed) and Vapi's server messages (status-update, end-of-call-report). A transcript in an end-of-call message is read once for the disclosure and where it fell, then dropped; only the platform's call id is kept.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  call_id:
                    type: string
                  event:
                    type: string
                    enum:
                    - started
                    - disclosed
                    - handoff_human
                    - ended
                  at:
                    type: string
                    description: ISO time
                  agent:
                    type: string
                  transcript:
                    type: string
                    description: Only with ended; read once, not stored
                required:
                - call_id
                - event
              - type: object
                description: A Retell or Vapi webhook body, as sent
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  platform:
                    type: string
                  recorded:
                    type: array
                    items:
                      type: object
                      properties:
                        call_id:
                          type: string
                        written:
                          type: integer
                  kept:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '402':
          description: No active plan
components:
  schemas:
    VoicePolicy:
      type: object
      properties:
        business:
          type: string
        language:
          type: string
        disclosure:
          type: string
          description: The line to speak at the start of the call
        timing:
          type: string
          enum:
          - start
        repeatEveryHours:
          type:
          - integer
          - 'null'
        askForHuman:
          type: boolean
        minorsNotice:
          type: boolean
        inProfile:
          type: boolean
        laws:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              slug:
                type: string
              jurisdiction:
                type: string
              timing:
                type: string
              effective:
                type:
                - string
                - 'null'
        policyVersion:
          type:
          - integer
          - 'null'
  securitySchemes:
    voiceToken:
      type: http
      scheme: bearer
      description: The site's voice token (starts with bni_), from the dashboard's Voice page. Also accepted as ?token= on voice endpoints, and as x-vapi-secret on /api/voice/event.
    registerToken:
      type: http
      scheme: bearer
      description: The site's content-register token, from the dashboard's Content page.
externalDocs:
  description: Human documentation
  url: https://botnotice.app/docs/api