Call2Me Widgets API

openapi: 3.2.0
info:
  title: Call2Me Widgets API
  description: '# Call2Me Voice AI Platform API


    Programmatic interface to build, deploy and operate voice AI agents that can place

    and receive phone calls in real time. Designed to be consumed by humans **and** by

    AI agent frameworks (function-calling LLMs, MCP servers, automation platforms like

    Composio, Pipedream, Zapier, n8n).


    ## What you can do


    - **Place outbound calls** — give an agent a phone number to dial; the AI handles

    the conversation end-to-end and returns a transcript + recording.

    - **Manage AI agents** — create personalities, attach voices, system prompts,

    knowledge bases and post-call actions.

    - **Schedule calls** — one-shot or recurring (cron-like) outbound calls.

    - **Knowledge base (RAG)** — upload documents/URLs so the agent answers from your

    data with reduced hallucination.

    - **Inbound** — provision phone numbers that route to your agents.


    ## Common LLM tool-calling use cases


    | Goal | Endpoint |

    |------|----------|

    | "Call this person and read them this script" | `POST /v1/calls` |

    | "Schedule a follow-up tomorrow at 14:00" | `POST /v1/schedules` |

    | "Get the transcript of last call" | `GET /v1/calls/{id}` |

    | "Add this PDF to the agent''s brain" | `POST /v1/knowledge-base/{id}/sources` |


    ## Authentication


    Every request requires a Bearer token issued from the dashboard:


    ```

    Authorization: Bearer c2m_sk_xxxxxxxxxxxxxxxx

    ```


    Get your API key from the API Keys page.

    Keys are scoped per-workspace and can be rotated/revoked any time.


    ## Rate Limits


    | Plan | Requests/min | Concurrent Calls |

    |------|-------------|------------------|

    | Free | 60 | 1 |

    | Pro | 600 | 10 |

    | Enterprise | Unlimited | Unlimited |


    ## SDKs & Integrations


    - Python SDK

    - Node.js SDK

    - OpenAPI 3.1 spec: `/openapi.json` (use it to generate clients or register the

    service with AI tool platforms)


    ## Support


    - Email: support@call2me.app

    - Docs: https://docs.call2me.app

    - Discord: https://discord.gg/call2me'
  version: 1.0.0
  x-logo:
    url: https://call2me.app/logo.png
    altText: Call2Me Logo
  contact:
    name: Call2Me Support
    url: https://call2me.app/support
    email: support@call2me.app
  license:
    name: Commercial — see Terms of Service
    url: https://call2me.app/terms
  termsOfService: https://call2me.app/terms
servers:
- url: https://api.call2me.app
  description: Production
- url: http://localhost:8000
  description: Local Development
security:
- BearerAuth: []
tags:
- name: Widgets
  description: Embeddable chat/voice widgets you can drop into a website. Each widget is bound to an agent and produces a `` snippet plus optional domain allow-list.
paths:
  /v1/widgets:
    post:
      tags:
      - Widgets
      summary: Create Widget
      description: Create a new chat widget.
      operationId: create_widget_v1_widgets_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWidgetRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Widgets
      summary: List Widgets
      description: List widgets for the user. Optionally filter by agent_id (user-scoped).
      operationId: list_widgets_v1_widgets_get
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}:
    get:
      tags:
      - Widgets
      summary: Get Widget
      description: Get widget details.
      operationId: get_widget_v1_widgets__widget_id__get
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Widgets
      summary: Update Widget
      description: Update widget settings.
      operationId: update_widget_v1_widgets__widget_id__patch
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWidgetRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Widgets
      summary: Delete Widget
      description: Delete a widget.
      operationId: delete_widget_v1_widgets__widget_id__delete
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}/sessions:
    get:
      tags:
      - Widgets
      summary: List Widget Sessions
      description: List chat sessions for a widget with pagination.
      operationId: list_widget_sessions_v1_widgets__widget_id__sessions_get
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}/sessions/{session_id}/messages:
    get:
      tags:
      - Widgets
      summary: Get Session Messages
      description: Get messages for a chat session.
      operationId: get_session_messages_v1_widgets__widget_id__sessions__session_id__messages_get
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}/preview:
    get:
      tags:
      - Widgets
      summary: Widget Preview Page
      description: Serve a preview HTML page with the widget embedded.
      operationId: widget_preview_page_v1_widgets__widget_id__preview_get
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/a/{slug}:
    get:
      tags:
      - Widgets
      summary: Public Assistant Page
      description: Public shareable assistant page (call2me.app/a/{slug} proxies here).
      operationId: public_assistant_page_v1_a__slug__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}/regenerate-greeting-audio:
    post:
      tags:
      - Widgets
      summary: Regenerate Greeting Audio
      description: 'Generate TTS audio from greeting_message and upload to R2.


        Rate limited to 10 requests per hour per user.'
      operationId: regenerate_greeting_audio_v1_widgets__widget_id__regenerate_greeting_audio_post
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}/greeting.mp3:
    get:
      tags:
      - Widgets
      summary: Serve Greeting Audio
      description: 'Public: Proxy greeting audio from R2. Cached aggressively.'
      operationId: serve_greeting_audio_v1_widgets__widget_id__greeting_mp3_get
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}/config:
    get:
      tags:
      - Widgets
      summary: Get Widget Config
      description: 'Public: Get widget config for rendering. No auth required.'
      operationId: get_widget_config_v1_widgets__widget_id__config_get
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}/voice-token:
    post:
      tags:
      - Widgets
      summary: Widget Voice Token
      description: 'Public: issue a short-lived LiveKit token for a widget voice session.


        Billing accrues to the widget owner''s wallet (same path as phone calls).

        Admission (mode/credit/daily-limit) is decided by _resolve_widget_voice.


        Two guards run BEFORE admission, because admission burns the widget''s

        daily visitor quota on the way through:


        1. Origin allow-list. The chat endpoint has always enforced this; voice

        did not, so a widget could be embedded on any site and spend the

        owner''s balance per minute. An Origin header is forgeable by a

        script, but it does stop the realistic case — someone dropping the

        public widget id into their own page.

        2. Per-IP daily cap. The per-widget cap alone lets one visitor exhaust

        the day''s quota and lock out real ones; this bounds a single source.'
      operationId: widget_voice_token_v1_widgets__widget_id__voice_token_post
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}/chat:
    post:
      tags:
      - Widgets
      summary: Widget Chat
      description: 'Public: Send a chat message and get AI response. No auth required.


        Billing is charged to the widget owner''s wallet.'
      operationId: widget_chat_v1_widgets__widget_id__chat_post
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatMessageRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{widget_id}/embed.js:
    get:
      tags:
      - Widgets
      summary: Widget Embed Script
      description: Serve the embeddable widget JavaScript.
      operationId: widget_embed_script_v1_widgets__widget_id__embed_js_get
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: string
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CreateWidgetRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        name:
          type: string
          title: Name
        greeting_message:
          type: string
          title: Greeting Message
          default: Hi! How can I help you?
        placeholder_text:
          type: string
          title: Placeholder Text
          default: Type a message...
        primary_color:
          type: string
          title: Primary Color
          default: '#6366f1'
        position:
          type: string
          title: Position
          default: bottom-right
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        show_branding:
          type: boolean
          title: Show Branding
          default: true
        language:
          type: string
          title: Language
          default: tr-TR
        auto_open:
          type: boolean
          title: Auto Open
          default: false
        auto_open_delay_ms:
          type: integer
          title: Auto Open Delay Ms
          default: 3000
        allowed_domains:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Domains
        voice_greeting_enabled:
          type: boolean
          title: Voice Greeting Enabled
          default: false
        voice_greeting_voice:
          type: string
          title: Voice Greeting Voice
          default: nova
        voice_mode:
          type: string
          title: Voice Mode
          default: chat
        voice_session_limit_sec:
          type: integer
          title: Voice Session Limit Sec
          default: 300
      type: object
      required:
      - agent_id
      - name
      title: CreateWidgetRequest
    ChatMessageRequest:
      properties:
        message:
          type: string
          title: Message
        visitor_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Visitor Id
        visitor_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Visitor Name
      type: object
      required:
      - message
      title: ChatMessageRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UpdateWidgetRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        greeting_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Greeting Message
        placeholder_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Placeholder Text
        primary_color:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Color
        position:
          anyOf:
          - type: string
          - type: 'null'
          title: Position
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        show_branding:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Show Branding
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        auto_open:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Auto Open
        auto_open_delay_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Auto Open Delay Ms
        allowed_domains:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Domains
        active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Active
        voice_greeting_enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Voice Greeting Enabled
        voice_greeting_voice:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Greeting Voice
        voice_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Mode
        voice_session_limit_sec:
          anyOf:
          - type: integer
          - type: 'null'
          title: Voice Session Limit Sec
        public_slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Public Slug
      type: object
      title: UpdateWidgetRequest
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API key
externalDocs:
  description: Full developer documentation
  url: https://docs.call2me.app