> This page is for APIs.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# calling.ai_sidecar

GET /

Attach a real-time AI observer (sidecar) to the call

Reference: https://signalwire.com/docs/apis/relay/server/calling/calling-ai-sidecar

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: calling.ai_sidecar
  version: subpackage_callingAiSidecar.calling.ai_sidecar
  description: Attach a real-time AI observer (sidecar) to the call
channels:
  /:
    description: Attach a real-time AI observer (sidecar) to the call
    publish:
      operationId: subpackage_callingAiSidecar.calling.ai_sidecar-publish
      summary: Server messages
      message:
        oneOf:
          - $ref: >-
              #/components/messages/subpackage_callingAiSidecar.calling.ai_sidecar-server-0-onCallingAiSidecarAiSidecarEvent
          - $ref: >-
              #/components/messages/subpackage_callingAiSidecar.calling.ai_sidecar-server-1-onCallingAiSidecarResponse
    subscribe:
      operationId: subpackage_callingAiSidecar.calling.ai_sidecar-subscribe
      summary: calling.ai_sidecar
      message:
        name: callingAiSidecar
        title: calling.ai_sidecar
        payload:
          $ref: '#/components/schemas/calling.ai_sidecar_callingAiSidecarRequest'
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  messages:
    subpackage_callingAiSidecar.calling.ai_sidecar-server-0-onCallingAiSidecarAiSidecarEvent:
      name: onCallingAiSidecarAiSidecarEvent
      title: calling.ai.sidecar
      payload:
        $ref: '#/components/schemas/calling.ai_sidecar_aiSidecarEvent'
    subpackage_callingAiSidecar.calling.ai_sidecar-server-1-onCallingAiSidecarResponse:
      name: onCallingAiSidecarResponse
      title: calling.ai_sidecar response
      payload:
        $ref: '#/components/schemas/calling.ai_sidecar_callingAiSidecarResponse'
  schemas:
    ChannelsCallingAiSidecarMessagesAiSidecarEventJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingAiSidecarMessagesAiSidecarEventJsonrpc
    ChannelsCallingAiSidecarMessagesAiSidecarEventMethod:
      type: string
      enum:
        - signalwire.event
      description: Always `signalwire.event`.
      title: ChannelsCallingAiSidecarMessagesAiSidecarEventMethod
    ChannelsCallingAiSidecarMessagesAiSidecarEventParamsEventType:
      type: string
      enum:
        - calling.ai.sidecar
      description: The event type — identifies which event this is.
      title: ChannelsCallingAiSidecarMessagesAiSidecarEventParamsEventType
    Calling.AiCallInfo:
      type: object
      properties:
        project_id:
          type: string
          description: Your project ID.
        space_id:
          type: string
          description: Your space ID.
        content_type:
          type: string
          description: The content type of the delivery.
        content_disposition:
          type: string
          description: The content disposition of the delivery.
        conversation_type:
          type: string
          description: The kind of conversation this delivery describes.
        call_id:
          type: string
          description: The call ID.
      required:
        - content_type
        - content_disposition
        - conversation_type
        - call_id
      description: >-
        Call/session context attached to AI transcribe, translate, and sidecar
        webhook deliveries, as a

        sibling of the documented event fields. Added on every delivery.
      title: Calling.AiCallInfo
    Calling.AiSidecarCallbackType:
      type: string
      enum:
        - start
        - turn
        - request
        - thought
        - insight
        - skip
        - tool_call
        - tool_result
        - action
        - global_data_change
        - history_pruned
        - error
        - ask_request
        - ask_answer
        - stop
        - final
      title: Calling.AiSidecarCallbackType
    Calling.AiSidecarEventBody:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Calling.AiSidecarCallbackType'
          description: >-
            The callback type. Determines which type-specific fields are
            present.
        ts:
          type: integer
          format: int64
          description: When the event was produced, as a Unix timestamp in microseconds.
        tick_id:
          type: integer
          format: int64
          description: >-
            Groups callbacks that the sidecar produced together in one
            processing pass — callbacks from the same pass share a `tick_id`.
        channel_data:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            Call/channel context (`call_id`, plus caller id fields when
            available).
        ask_id:
          type: string
          description: >-
            Matches the `ask_id` returned by `calling.ai_sidecar.ask`,
            correlating this

            callback with the question you sent. Present on `ask_request` and
            `ask_answer`,

            and on `request`, `thought`, `tool_call`, and `tool_result`
            callbacks produced

            while answering an ask.
        raw:
          type: string
          description: >-
            The raw insight or answer text. Present on `type: insight` and on
            `type: ask_answer` (the reply to your `calling.ai_sidecar.ask`).
        summary:
          type: string
          description: >-
            The end-of-session summary text. Present on `type: final` when a
            summary was generated.
        text:
          type: string
          description: >-
            The reasoning text on `type: thought`, or the text the sidecar would
            have spoken on an `action` callback for a `say` action.
        name:
          type: string
          description: >-
            The tool (function) name. Present on `type: tool_call` and
            `tool_result`.
        arguments:
          type: string
          description: >-
            The tool-call arguments, delivered as a raw JSON string. Present on
            `type: tool_call`.
        response:
          type: string
          description: >-
            The tool-call response, delivered as a raw JSON string. Present on
            `type: tool_result`.
        reason:
          type: string
          description: >-
            Why the sidecar took no action this pass (`type: skip`), or why a
            `say` action was not spoken (`type: action`).
        error_reason:
          type: string
          description: 'A machine-readable error reason. Present on `type: error`.'
        detail:
          type: string
          description: >-
            Human-readable error detail. Present on some `type: error`
            callbacks.
        function:
          type: string
          description: >-
            The SWAIG function whose webhook failed. Present on `type: error`
            for webhook failures.
        http_code:
          type: integer
          description: >-
            HTTP status of the failed webhook request. Present on `type: error`
            for webhook failures.
        curl_code:
          type: integer
          description: >-
            Transport error code of the failed webhook request. Present on
            `type: error` for webhook failures.
        stripped:
          type: integer
          description: >-
            How many malformed tool calls were dropped. Present on `type: error`
            with `error_reason: malformed_tool_call`.
        dropped_count:
          type: integer
          description: >-
            How many history entries were dropped. Present on `type:
            history_pruned`.
        kept_count:
          type: integer
          description: >-
            How many history entries were kept after pruning. Present on `type:
            history_pruned`.
        tokens_before:
          type: integer
          description: 'Token count before pruning. Present on `type: history_pruned`.'
        tokens_after:
          type: integer
          description: 'Token count after pruning. Present on `type: history_pruned`.'
        iter:
          type: integer
          description: >-
            The current iteration. Present on the `request`, `thought`,
            `tool_call`, `tool_result`, `insight`, and `ask_answer` callbacks.
        total_iters:
          type: integer
          description: >-
            The total iterations. Present on the `insight` and `ask_answer`
            callbacks.
        triggered_by:
          type: string
          description: >-
            `ask` when the callback was produced while answering a

            `calling.ai_sidecar.ask` question. Present on `ask_answer`, and on
            `request`,

            `thought`, `tool_call`, and `tool_result` callbacks produced by an
            ask.
        model:
          type: string
          description: 'The model in use. Present on `type: start`, `request`, and `final`.'
        global_data:
          type: object
          additionalProperties:
            description: Any type
          description: 'The session''s global data. Present on `type: start` and `final`.'
        tools:
          type: array
          items:
            type: string
          description: >-
            Names of the SWAIG functions available to the sidecar. Present on
            `type: start`.
        transcript_delta:
          type: string
          description: >-
            The new transcript text since the previous turn. Present on `type:
            turn`.
        customer_text:
          type: string
          description: 'The customer''s text for this turn. Present on `type: turn`.'
        agent_text:
          type: string
          description: 'The agent''s text for this turn. Present on `type: turn`.'
        messages_count:
          type: integer
          description: 'Number of messages sent to the model. Present on `type: request`.'
        messages_token_count:
          type: integer
          description: >-
            Token count of the messages sent to the model. Present on `type:
            request`.
        tool_choice:
          type: string
          description: 'The tool-choice mode sent to the model. Present on `type: request`.'
        action:
          description: 'The SWAIG action item. Present on `type: action`.'
        source_function:
          type: string
          description: >-
            The SWAIG function that returned the action. Present on `type:
            action` when known.
        executed:
          type: boolean
          description: >-
            Whether the action was applied to the call. Present on `type:
            action`.
        spoken:
          type: boolean
          description: >-
            Whether the text was spoken. Present (and `false`) on `type: action`
            for a `say` action.
        key:
          type: string
          description: >-
            The global-data key that changed. Present on `type:
            global_data_change`.
        old_value:
          description: >-
            The key's previous value. Present on `type: global_data_change` when
            the key existed.
        new_value:
          description: 'The key''s new value. Present on `type: global_data_change`.'
        question:
          type: string
          description: 'The question you sent. Present on `type: ask_request`.'
        stop_reason:
          type: string
          description: 'Why the session ended. Present on `type: stop` and `final`.'
        history:
          type: array
          items:
            description: Any type
          description: 'The sidecar''s conversation history. Present on `type: final`.'
        transcript:
          type: array
          items:
            description: Any type
          description: 'The call transcript. Present on `type: final`.'
        event_log:
          type: array
          items:
            description: Any type
          description: 'The session''s event log. Present on `type: final`.'
        stats:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            Session counters (ticks, insights, skips, tool calls, errors,
            tokens). Present on `type: final`.
        metrics:
          type: object
          additionalProperties:
            description: Any type
          description: 'Detailed session telemetry. Present on `type: final`.'
        started_at:
          type: integer
          format: int64
          description: >-
            When the session started, as a Unix timestamp in microseconds.
            Present on `type: final`.
        ended_at:
          type: integer
          format: int64
          description: >-
            When the session ended, as a Unix timestamp in microseconds. Present
            on `type: final`.
        duration_ms:
          type: integer
          format: int64
          description: 'Session duration in milliseconds. Present on `type: final`.'
      required:
        - type
        - ts
        - tick_id
        - channel_data
      description: >-
        The sidecar event, carried on the wire under `sidecar_event`. Beyond the
        common fields, each

        `type` adds its own type-specific fields — the optional fields below
        indicate which type they

        belong to.


        This is a real-time debug/observability stream: it surfaces the
        sidecar's internal activity —

        model reasoning, tool calls and their results, history pruning, and an
        end-of-session rollup.

        Treat its exact shape as unstable: individual `type` variants may carry
        additional fields, and

        the set of fields can change between releases.
      title: Calling.AiSidecarEventBody
    Calling.AiSidecarEventData:
      type: object
      properties:
        node_id:
          type: string
          description: >-
            Opaque identifier that, paired with `call_id`, addresses this call.
            Echo back the value you received; treat it as opaque.
        call_id:
          type: string
          description: Unique identifier of the call.
        segment_id:
          type: string
          description: >-
            Identifier of the call segment this event belongs to, for
            correlating events within the same segment of a call.
        tag:
          type: string
          description: >-
            The `tag` you set when placing the call, echoed back so you can
            match the event to your request.
        call_info:
          $ref: '#/components/schemas/Calling.AiCallInfo'
          description: Call/session context for this delivery.
        sidecar_event:
          $ref: '#/components/schemas/Calling.AiSidecarEventBody'
          description: >-
            The sidecar event. Its `type` field determines which type-specific
            fields it carries.
      required:
        - node_id
        - call_id
        - call_info
        - sidecar_event
      title: Calling.AiSidecarEventData
    ChannelsCallingAiSidecarMessagesAiSidecarEventParams:
      type: object
      properties:
        event_type:
          $ref: >-
            #/components/schemas/ChannelsCallingAiSidecarMessagesAiSidecarEventParamsEventType
          description: The event type — identifies which event this is.
        event_channel:
          type: string
          description: >-
            The channel the event was delivered on — for Calling events, the
            `protocol`

            string your connection received from `signalwire.connect`.
        timestamp:
          type: number
          format: double
          description: >-
            When the event was emitted, as a Unix timestamp in seconds. Always
            present.
        project_id:
          type: string
          description: >-
            Your project ID. Present on Calling events and most Call Fabric
            events; absent on `call.joined`, `call.left`, `member.joined`, and
            `member.left`.
        space_id:
          type: string
          description: >-
            Your space ID. Present on Calling events and most Call Fabric
            events; absent on `call.joined`, `call.left`, `member.joined`, and
            `member.left`.
        params:
          $ref: '#/components/schemas/Calling.AiSidecarEventData'
          description: The event-specific payload.
      required:
        - event_type
        - event_channel
        - timestamp
        - params
      description: The event envelope.
      title: ChannelsCallingAiSidecarMessagesAiSidecarEventParams
    calling.ai_sidecar_aiSidecarEvent:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingAiSidecarMessagesAiSidecarEventJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: >-
            Event id — a unique UUID generated for each event. Events are
            notifications: you do not reply to them.
        method:
          $ref: >-
            #/components/schemas/ChannelsCallingAiSidecarMessagesAiSidecarEventMethod
          description: Always `signalwire.event`.
        params:
          $ref: >-
            #/components/schemas/ChannelsCallingAiSidecarMessagesAiSidecarEventParams
          description: The event envelope.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        A server-pushed `signalwire.event` frame. `EventType` identifies which
        event this is

        (e.g. `calling.call.play`); `Data` is the event-specific payload carried
        at `params.params`.
      title: calling.ai_sidecar_aiSidecarEvent
    ChannelsCallingAiSidecarMessagesCallingAiSidecarResponseJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingAiSidecarMessagesCallingAiSidecarResponseJsonrpc
    Calling.AiSidecarResult:
      type: object
      properties:
        code:
          type: string
          description: >-
            Result code as a string. `"200"` means success. Failures use an
            HTTP-style code

            such as `"400"` (bad request), `"403"`, `"404"` (call not found),
            `"405"`, `"409"`

            (conflict, for example another operation is still running), `"410"`
            (call gone),

            or `"500"`. If the call could not be reached in time, `code` is a
            lowercase error

            identifier instead, such as `response_timeout`, `not_available`, or

            `internal_error`.
        message:
          type: string
          description: >-
            Human-readable description of the result. On failure, it explains
            what went wrong. Always check `code`; `message` may be omitted when
            there is nothing extra to report.
        call_id:
          type: string
          description: The call this result is for, echoed from your request.
      required:
        - code
      description: >-
        Acknowledgement of a `calling.ai_sidecar` request. `message` is the raw
        status

        line: `"+OK started\n"` when a sidecar was attached, or `"+OK
        summarizing\n"`

        when `action.summarize` was sent. On failure `code` is `"400"` and
        `message`

        carries the error text, e.g. `"-ERR: lang is required\n"`.
      title: Calling.AiSidecarResult
    JsonRpcErrorCode0:
      type: string
      enum:
        - '-32000'
      title: JsonRpcErrorCode0
    JsonRpcErrorCode1:
      type: string
      enum:
        - '-32001'
      title: JsonRpcErrorCode1
    JsonRpcErrorCode2:
      type: string
      enum:
        - '-32002'
      title: JsonRpcErrorCode2
    JsonRpcErrorCode3:
      type: string
      enum:
        - '-32003'
      title: JsonRpcErrorCode3
    JsonRpcErrorCode4:
      type: string
      enum:
        - '-32004'
      title: JsonRpcErrorCode4
    JsonRpcErrorCode5:
      type: string
      enum:
        - '-32005'
      title: JsonRpcErrorCode5
    JsonRpcErrorCode6:
      type: string
      enum:
        - '-32600'
      title: JsonRpcErrorCode6
    JsonRpcErrorCode7:
      type: string
      enum:
        - '-32601'
      title: JsonRpcErrorCode7
    JsonRpcErrorCode8:
      type: string
      enum:
        - '-32602'
      title: JsonRpcErrorCode8
    JsonRpcErrorCode9:
      type: string
      enum:
        - '-32603'
      title: JsonRpcErrorCode9
    JsonRpcErrorCode10:
      type: string
      enum:
        - '-32700'
      title: JsonRpcErrorCode10
    JsonRpcErrorCode:
      oneOf:
        - $ref: '#/components/schemas/JsonRpcErrorCode0'
        - $ref: '#/components/schemas/JsonRpcErrorCode1'
        - $ref: '#/components/schemas/JsonRpcErrorCode2'
        - $ref: '#/components/schemas/JsonRpcErrorCode3'
        - $ref: '#/components/schemas/JsonRpcErrorCode4'
        - $ref: '#/components/schemas/JsonRpcErrorCode5'
        - $ref: '#/components/schemas/JsonRpcErrorCode6'
        - $ref: '#/components/schemas/JsonRpcErrorCode7'
        - $ref: '#/components/schemas/JsonRpcErrorCode8'
        - $ref: '#/components/schemas/JsonRpcErrorCode9'
        - $ref: '#/components/schemas/JsonRpcErrorCode10'
      title: JsonRpcErrorCode
    JsonRpcError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/JsonRpcErrorCode'
          description: >-
            The error code — a negative integer identifying the failure. See
            `JsonRpcErrorCode` for the full list of values and meanings.
        message:
          type: string
          description: A human-readable description of what went wrong.
        original_request:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            An echo of the request that failed — the full JSON-RPC frame you
            sent

            (`jsonrpc`, `id`, `method`, `params`). Always present.
        requester_nodeid:
          type: string
          description: >-
            The node that sent the failed request. Present only on some routing
            errors.
        requester_identity:
          type: string
          description: >-
            The identity of the requester. Present only on some routing errors;
            same value as `requester_nodeid`.
        responder_nodeid:
          type: string
          description: >-
            The node that was handling the request. Present only on some routing
            errors.
        responder_identity:
          type: string
          description: >-
            The identity of the responder. Present only on some routing errors;
            same value as `responder_nodeid`.
        last_hop_timeout:
          type: boolean
          description: >-
            `true` when the request timed out on its final hop inside
            SignalWire. Present only on some timeout errors.
      required:
        - code
        - message
        - original_request
      description: >-
        A JSON-RPC 2.0 error object, delivered on the `error` field of a
        `JsonRpcResponse` when

        a request fails at the protocol level (bad version, authentication,
        scope, params, or

        your project's connection limit). It replaces `result` — a frame carries
        one or the other, never both.
      title: JsonRpcError
    calling.ai_sidecar_callingAiSidecarResponse:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingAiSidecarMessagesCallingAiSidecarResponseJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: The id of the request this responds to.
        result:
          $ref: '#/components/schemas/Calling.AiSidecarResult'
          description: The method result. Present when the request succeeded.
        error:
          $ref: '#/components/schemas/JsonRpcError'
          description: >-
            Present instead of `result` when the request failed at the protocol
            level.
      required:
        - jsonrpc
        - id
      description: >-
        A JSON-RPC response frame correlated to a request by `id`. On success
        the frame carries

        `result` (the method result). If the request fails at the protocol level
        — an

        incompatible version, failed authentication, insufficient scope, invalid
        params, or your

        project's connection limit — the frame carries `error` instead of
        `result`. Many

        method-level failures (for example most Calling failures) are reported
        the other way: a

        normal `result` whose own `code` is not `"200"`. Each method documents
        which form its

        failures take.


        An `error` returned for `signalwire.connect` is followed by the service
        closing the

        WebSocket; open a new connection to try again. The same happens when

        `signalwire.reauthenticate` sends credentials that are rejected, except
        for a

        Subscriber Access Token. Errors on any other request leave the
        connection open.
      title: calling.ai_sidecar_callingAiSidecarResponse
    ChannelsCallingAiSidecarMessagesCallingAiSidecarRequestJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingAiSidecarMessagesCallingAiSidecarRequestJsonrpc
    ChannelsCallingAiSidecarMessagesCallingAiSidecarRequestMethod:
      type: string
      enum:
        - calling.ai_sidecar
      description: The name of the JSON-RPC method being invoked.
      title: ChannelsCallingAiSidecarMessagesCallingAiSidecarRequestMethod
    SWML.Calling.AISidecarPromptText:
      type: object
      properties:
        text:
          type: string
          description: The operator prompt as a single block of text.
      required:
        - text
      title: SWML.Calling.AISidecarPromptText
    SWML.Calling.AISidecarPomSectionBodyContent:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          description: Title for the section
        subsections:
          type: array
          items:
            $ref: '#/components/schemas/SWML.Calling.AISidecarPOM'
          description: Optional array of nested subsections
        numbered:
          type: boolean
          description: Whether to number the section
        numberedBullets:
          type: boolean
          description: Whether to number the bullets
        body:
          type: string
          description: Body text for the section
        bullets:
          type: array
          items:
            type: string
          description: Optional array of bullet points
      required:
        - body
      description: Content model with body text and optional bullets
      title: SWML.Calling.AISidecarPomSectionBodyContent
    SWML.Calling.AISidecarPomSectionBulletsContent:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          description: Title for the section
        subsections:
          type: array
          items:
            $ref: '#/components/schemas/SWML.Calling.AISidecarPOM'
          description: Optional array of nested subsections
        numbered:
          type: boolean
          description: Whether to number the section
        numberedBullets:
          type: boolean
          description: Whether to number the bullets
        body:
          type: string
          description: Body text for the section (optional)
        bullets:
          type: array
          items:
            type: string
          description: Array of bullet points
      required:
        - bullets
      description: Content model with bullets and optional body
      title: SWML.Calling.AISidecarPomSectionBulletsContent
    SWML.Calling.AISidecarPOM:
      oneOf:
        - $ref: '#/components/schemas/SWML.Calling.AISidecarPomSectionBodyContent'
        - $ref: '#/components/schemas/SWML.Calling.AISidecarPomSectionBulletsContent'
      title: SWML.Calling.AISidecarPOM
    SWML.Calling.AISidecarPromptPom:
      type: object
      properties:
        pom:
          type: array
          items:
            $ref: '#/components/schemas/SWML.Calling.AISidecarPOM'
          description: >-
            The operator prompt as a Prompt Object Model (POM) — a structured
            array of sections that SignalWire renders into a markdown document
            before sending it to the model.
      required:
        - pom
      title: SWML.Calling.AISidecarPromptPom
    SWML.Calling.AISidecarPrompt:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/SWML.Calling.AISidecarPromptText'
        - $ref: '#/components/schemas/SWML.Calling.AISidecarPromptPom'
      title: SWML.Calling.AISidecarPrompt
    CallingAiSidecarParamsModel0:
      type: string
      enum:
        - gpt-4o-mini
      title: CallingAiSidecarParamsModel0
    CallingAiSidecarParamsModel1:
      type: string
      enum:
        - gpt-4.1-mini
      title: CallingAiSidecarParamsModel1
    CallingAiSidecarParamsModel2:
      type: string
      enum:
        - gpt-4.1-nano
      title: CallingAiSidecarParamsModel2
    CallingAiSidecarParamsModel:
      oneOf:
        - $ref: '#/components/schemas/CallingAiSidecarParamsModel0'
        - $ref: '#/components/schemas/CallingAiSidecarParamsModel1'
        - $ref: '#/components/schemas/CallingAiSidecarParamsModel2'
        - type: string
      description: >-
        The model used for the sidecar's advice and its end-of-call summaries.
        Suggested values: `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-4.1-nano`.
        **Default:** `gpt-4o-mini`.
      title: CallingAiSidecarParamsModel
    CallingAiSidecarParamsDirectionItems:
      type: string
      enum:
        - remote-caller
        - local-caller
      title: CallingAiSidecarParamsDirectionItems
    CallingAiSidecarParamsCustomerRole:
      type: string
      enum:
        - remote-caller
        - local-caller
      default: remote-caller
      description: >-
        Which leg is the customer, used as the turn-end trigger source.
        **Default:** `remote-caller`.
      title: CallingAiSidecarParamsCustomerRole
    SWML.Calling.AISidecarSWAIGDefaults:
      type: object
      properties:
        web_hook_url:
          type: string
          description: >-
            Default webhook URL for functions that do not set their own
            `web_hook_url`. Authentication can also be set in the url in the
            format of `username:password@url`. Credentials embedded in the URL
            take precedence over `web_hook_auth_user` and
            `web_hook_auth_password`.
        web_hook_auth_user:
          type: string
          description: >-
            Default username for basic auth on the function webhook, for
            functions that don't set their own `web_hook_auth_user`.
        web_hook_auth_password:
          type: string
          description: >-
            Default password for basic auth on the function webhook, for
            functions that don't set their own `web_hook_auth_password`.
      title: SWML.Calling.AISidecarSWAIGDefaults
    SwmlCallingAiSidecarFunctionParametersType:
      type: string
      enum:
        - object
      description: The container type for the function's arguments. Always `object`.
      title: SwmlCallingAiSidecarFunctionParametersType
    SwmlCallingAiSidecarFunctionParameters:
      type: object
      properties: {}
      description: >-
        The properties the function accepts, keyed by property name. Each
        property sets a `type` and an optional

        `description`: `string`, `integer`, and `number` properties also accept
        `enum` and `default`, `boolean`

        properties accept `default`, `array` properties need an `items` schema,
        and `object` properties accept nested

        `properties` and `required`, at any depth. Other validation keywords
        such as `pattern`, `format`, `minimum`, and

        `maximum` are not supported; express those constraints in the property
        `description`. The sidecar does not

        check the model's arguments against this schema, so validate them in
        your webhook.
      title: SwmlCallingAiSidecarFunctionParameters
    SWML.Calling.AISidecarFunctionParameters:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SwmlCallingAiSidecarFunctionParametersType'
          description: The container type for the function's arguments. Always `object`.
        properties:
          $ref: '#/components/schemas/SwmlCallingAiSidecarFunctionParameters'
          description: >-
            The properties the function accepts, keyed by property name. Each
            property sets a `type` and an optional

            `description`: `string`, `integer`, and `number` properties also
            accept `enum` and `default`, `boolean`

            properties accept `default`, `array` properties need an `items`
            schema, and `object` properties accept nested

            `properties` and `required`, at any depth. Other validation keywords
            such as `pattern`, `format`, `minimum`, and

            `maximum` are not supported; express those constraints in the
            property `description`. The sidecar does not

            check the model's arguments against this schema, so validate them in
            your webhook.
        required:
          type: array
          items:
            type: string
          description: The names of the required properties.
      required:
        - type
        - properties
      title: SWML.Calling.AISidecarFunctionParameters
    SWML.Calling.AISidecarSWAIGFunction:
      type: object
      properties:
        function:
          type: string
          description: >-
            The name of the function. This is the only required field; the model
            calls the function by this name.
        description:
          type: string
          description: >-
            A description of what the function does, sent to the model so it
            knows when to call it.
        purpose:
          type: string
          description: >-
            Fallback for `description` — used only when `description` is not
            set.
        parameters:
          $ref: '#/components/schemas/SWML.Calling.AISidecarFunctionParameters'
          description: >-
            The JSON-Schema object describing the function's arguments. When
            omitted, the function takes no arguments.
        web_hook_url:
          type: string
          description: >-
            Webhook URL for this function. Falls back to
            `defaults.web_hook_url`. Authentication can also be set in the url
            in the format of `username:password@url`. Credentials embedded in
            the URL take precedence over `web_hook_auth_user` and
            `web_hook_auth_password`.
        web_hook_auth_user:
          type: string
          description: >-
            Username for basic auth on this function's webhook. Falls back to
            `defaults.web_hook_auth_user`.
        web_hook_auth_password:
          type: string
          description: >-
            Password for basic auth on this function's webhook. Falls back to
            `defaults.web_hook_auth_password`.
      required:
        - function
      title: SWML.Calling.AISidecarSWAIGFunction
    SwmlCallingAiSidecarMcpServerHeaders:
      type: object
      properties: {}
      description: >-
        HTTP headers sent to the MCP server. Authorization tokens go here —
        there is no separate auth field. Header values are sent exactly as
        written; variables such as `${global_data.token}` are not expanded.
      title: SwmlCallingAiSidecarMcpServerHeaders
    SwmlCallingAiSidecarMcpServerResourceVars:
      type: object
      properties: {}
      description: >-
        Values for `{name}` placeholders in the URI templates of the server's
        resources. When a resource

        URI contains `{customer_id}`, the value of the `customer_id` key
        replaces it. Values are used exactly

        as written; variables such as `${global_data.customer_id}` are not
        expanded. A placeholder with no

        matching key is left as it is. Used only when `resources` is enabled.
      title: SwmlCallingAiSidecarMcpServerResourceVars
    SWML.Calling.AISidecarMCPServer:
      type: object
      properties:
        url:
          type: string
          description: The MCP (Model Context Protocol) server URL. Required.
        headers:
          $ref: '#/components/schemas/SwmlCallingAiSidecarMcpServerHeaders'
          description: >-
            HTTP headers sent to the MCP server. Authorization tokens go here —
            there is no separate auth field. Header values are sent exactly as
            written; variables such as `${global_data.token}` are not expanded.
        resources:
          type: boolean
          default: false
          description: >-
            Whether to fetch the server's resources into `global_data`, when the
            server advertises resource support. **Default:** `false`.
        resource_vars:
          $ref: '#/components/schemas/SwmlCallingAiSidecarMcpServerResourceVars'
          description: >-
            Values for `{name}` placeholders in the URI templates of the
            server's resources. When a resource

            URI contains `{customer_id}`, the value of the `customer_id` key
            replaces it. Values are used exactly

            as written; variables such as `${global_data.customer_id}` are not
            expanded. A placeholder with no

            matching key is left as it is. Used only when `resources` is
            enabled.
      required:
        - url
      title: SWML.Calling.AISidecarMCPServer
    SWML.Calling.AISidecarSWAIG:
      type: object
      properties:
        defaults:
          $ref: '#/components/schemas/SWML.Calling.AISidecarSWAIGDefaults'
          description: Default settings applied to all functions that do not override them.
        functions:
          type: array
          items:
            $ref: '#/components/schemas/SWML.Calling.AISidecarSWAIGFunction'
          description: An array of functions the model can call during the conversation.
        mcp_servers:
          type: array
          items:
            $ref: '#/components/schemas/SWML.Calling.AISidecarMCPServer'
          description: >-
            An array of MCP (Model Context Protocol) servers whose tools and
            resources are made available to the model.
      title: SWML.Calling.AISidecarSWAIG
    SWML.Calling.AISidecarPermissions:
      type: object
      properties:
        swaig_allow_swml:
          type: boolean
          default: true
          description: Whether SWAIG tools may run SWML on the call. **Default:** `true`.
        swaig_allow_settings:
          type: boolean
          default: true
          description: >-
            Whether the sidecar accepts a `settings` action returned by a SWAIG
            tool. Either way, a `settings` action

            does not change the sidecar's evaluations, which keep using the
            sidecar's `model` and default model settings.

            **Default:** `true`.
        swaig_set_global_data:
          type: boolean
          default: true
          description: >-
            Has no effect: SWAIG tools can set and unset the sidecar's global
            data whatever this is set to. To keep

            tool actions, including global data changes, from taking effect, set
            `act_on_channel` in the sidecar's

            `params` to `false`.

            **Default:** `true`.
      title: SWML.Calling.AISidecarPermissions
    CallingAiSidecarParamsGlobalData:
      type: object
      properties: {}
      description: >-
        A key-value object of data that is available throughout the sidecar
        session. You can reference it in the prompt with variable expansion, and
        it is included in the requests sent to your tools.

        It also persists across sessions on the same call leg.
      title: CallingAiSidecarParamsGlobalData
    SwmlCallingAiSidecarParamsSummaryModel0:
      type: string
      enum:
        - gpt-4o-mini
      title: SwmlCallingAiSidecarParamsSummaryModel0
    SwmlCallingAiSidecarParamsSummaryModel1:
      type: string
      enum:
        - gpt-4.1-mini
      title: SwmlCallingAiSidecarParamsSummaryModel1
    SwmlCallingAiSidecarParamsSummaryModel2:
      type: string
      enum:
        - gpt-4.1-nano
      title: SwmlCallingAiSidecarParamsSummaryModel2
    SwmlCallingAiSidecarParamsSummaryModel:
      oneOf:
        - $ref: '#/components/schemas/SwmlCallingAiSidecarParamsSummaryModel0'
        - $ref: '#/components/schemas/SwmlCallingAiSidecarParamsSummaryModel1'
        - $ref: '#/components/schemas/SwmlCallingAiSidecarParamsSummaryModel2'
        - type: string
      description: >-
        The model used for the end-of-call conversation summary, distinct from
        `model` (the sidecar's own model). Suggested values: `gpt-4o-mini`,
        `gpt-4.1-mini`, `gpt-4.1-nano`. **Default:** `gpt-4o-mini`.
      title: SwmlCallingAiSidecarParamsSummaryModel
    SwmlCallingAiSidecarParamsSpeechEngine:
      type: string
      enum:
        - deepgram
        - google
      default: deepgram
      description: The speech recognition engine to use. **Default:** `deepgram`.
      title: SwmlCallingAiSidecarParamsSpeechEngine
    SWML.Calling.AISidecarParams:
      type: object
      properties:
        idle_timeout_ms:
          type: integer
          minimum: 50
          maximum: 5000
          default: 200
          description: >-
            How long the customer can be silent, in milliseconds, after they
            finish speaking before the sidecar evaluates the conversation. Lower
            values make the sidecar react faster. Range: 50-5000. **Default:**
            `200`.
        min_interval_ms:
          type: integer
          minimum: 0
          maximum: 60000
          default: 0
          description: >-
            The minimum time, in milliseconds, between evaluations — a throttle
            that limits how often the sidecar runs on a busy call. Range:
            0-60000. **Default:** `0`.
        max_iters_per_tick:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
          description: >-
            The maximum number of model steps in a single evaluation, or in
            answering a question sent with the

            `calling.ai_sidecar.ask` command. Each step is one model response,
            which can call several tools at once.

            When the limit is reached the evaluation stops, whether or not the
            model has produced its advice. Range: 1-20. **Default:** `5`.
        max_history_tokens:
          type: integer
          minimum: 1000
          maximum: 200000
          default: 8000
          description: >-
            A soft token budget for the sidecar's running conversation history.
            When the history grows past it, the

            oldest complete exchanges are dropped, keeping the sidecar's
            instructions at the start. Dropping stops once

            eight or fewer messages follow the instructions, so the history can
            stay above the budget. An exchange is

            always dropped whole, so fewer than eight messages can remain.
            Range: 1000-200000. **Default:** `8000`.
        act_on_channel:
          type: boolean
          default: true
          description: >-
            Whether actions returned by your tools (such as transferring or
            hanging up the call) take effect on the call, or are only reported
            as callbacks. **Default:** `true`.
        final_summary:
          type: boolean
          default: false
          description: >-
            Whether to generate a closing summary of the sidecar's session when
            the call ends. The result is included in the final callback.
            **Default:** `false`.
        ai_summary:
          type: boolean
          default: false
          description: >-
            Whether to generate an end-of-call summary of the conversation
            itself, distinct from `final_summary` (which summarizes the
            sidecar's session). **Default:** `false`.
        ai_summary_prompt:
          type: string
          description: A custom prompt for the end-of-call conversation summary.
        summary_model:
          $ref: '#/components/schemas/SwmlCallingAiSidecarParamsSummaryModel'
          default: gpt-4o-mini
          description: >-
            The model used for the end-of-call conversation summary, distinct
            from `model` (the sidecar's own model). Suggested values:
            `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-4.1-nano`. **Default:**
            `gpt-4o-mini`.
        live_events:
          type: boolean
          default: false
          description: >-
            Whether to emit a callback for each utterance the speech recognizer
            produces. **Default:** `false`.
        verbose_utterances:
          type: boolean
          default: false
          description: >-
            Whether each utterance callback includes full speech-recognition
            detail, such as word timings and alternatives. This increases the
            callback size, so leave it off unless you need it. **Default:**
            `false`.
        speech_engine:
          $ref: '#/components/schemas/SwmlCallingAiSidecarParamsSpeechEngine'
          default: deepgram
          description: The speech recognition engine to use. **Default:** `deepgram`.
        speech_timeout:
          type: integer
          minimum: 0
          maximum: 600000
          description: >-
            How long, in milliseconds, the recognizer waits before finalizing
            speech. Range: 0-600000. When omitted or `0`, `60000` is used.
        vad_silence_ms:
          type: integer
          minimum: 0
          maximum: 60000
          description: >-
            The amount of silence, in milliseconds, used to detect the end of
            speech. Range: 0-60000. When omitted or `0`, `700` is used with the
            `deepgram` speech engine and `500` with `google`.
        vad_thresh:
          type: integer
          minimum: 0
          maximum: 10000
          description: >-
            How sensitively the recognizer detects speech. Range: 0-10000. When
            omitted or `0`, `400` is used.
        debug_level:
          type: integer
          minimum: 0
          maximum: 100
          default: 0
          description: 'Speech-engine debug verbosity. Range: 0-100. **Default:** `0`.'
        debug:
          type: boolean
          default: false
          description: >-
            Whether to enable verbose logging for the sidecar. **Default:**
            `false`.
        transcribe_prompt:
          type: string
          description: >-
            The default prompt for an on-demand summary (`action.summarize`)
            that sets no `prompt` of its own. It is not

            sent to the speech recognizer; use `hints` to help it recognize
            specific terms. This is distinct from the

            operator `prompt` and from `ai_summary_prompt`, which is used for
            the end-of-call summary.
      title: SWML.Calling.AISidecarParams
    SwmlCallingAiSidecarSummarizeActionSummarize:
      type: object
      properties:
        webhook:
          type: string
          description: >-
            The webhook URL the summary is sent to. Defaults to the sidecar's
            configured `url`.
        prompt:
          type: string
          description: >-
            The prompt used to write the summary. Defaults to the sidecar's
            `params.transcribe_prompt`; when that

            is not set either, built-in summary instructions are used.
      description: >-
        Generate a one-off summary of the conversation, instead of starting a
        sidecar, and send it to a webhook.

        It needs a sidecar already attached to the call: without one the request
        fails, and no sidecar is started.
      title: SwmlCallingAiSidecarSummarizeActionSummarize
    SWML.Calling.AISidecarSummarizeAction:
      type: object
      properties:
        summarize:
          $ref: '#/components/schemas/SwmlCallingAiSidecarSummarizeActionSummarize'
          description: >-
            Generate a one-off summary of the conversation, instead of starting
            a sidecar, and send it to a webhook.

            It needs a sidecar already attached to the call: without one the
            request fails, and no sidecar is started.
      required:
        - summarize
      title: SWML.Calling.AISidecarSummarizeAction
    Calling.AiSidecarParams:
      type: object
      properties:
        node_id:
          type: string
          description: >-
            Opaque identifier that, paired with `call_id`, addresses this call.
            Echo back the value you received; treat it as opaque.
        call_id:
          type: string
          description: Unique identifier of the call.
        prompt:
          $ref: '#/components/schemas/SWML.Calling.AISidecarPrompt'
          description: >-
            The operator prompt that instructs the sidecar how to coach the
            agent. May be a plain string or a Prompt Object Model (POM).

            SignalWire automatically adds built-in instructions for the
            sidecar's role, so your prompt only needs to describe the coaching
            behavior. When omitted, the sidecar uses a minimal default prompt,
            so setting one is strongly recommended.
        model:
          $ref: '#/components/schemas/CallingAiSidecarParamsModel'
          default: gpt-4o-mini
          description: >-
            The model used for the sidecar's advice and its end-of-call
            summaries. Suggested values: `gpt-4o-mini`, `gpt-4.1-mini`,
            `gpt-4.1-nano`. **Default:** `gpt-4o-mini`.
        direction:
          type: array
          items:
            $ref: '#/components/schemas/CallingAiSidecarParamsDirectionItems'
          default:
            - remote-caller
            - local-caller
          description: >-
            The call legs to observe. Both legs are required, in either order —
            an empty or single-leg value is rejected. When omitted, both legs
            are observed. **Default:** both legs (`remote-caller` and
            `local-caller`).
        customer_role:
          $ref: '#/components/schemas/CallingAiSidecarParamsCustomerRole'
          default: remote-caller
          description: >-
            Which leg is the customer, used as the turn-end trigger source.
            **Default:** `remote-caller`.
        url:
          type: string
          format: uri
          description: >-
            The webhook URL the sidecar POSTs its callbacks to. Receives both
            transcription events and sidecar callbacks.

            When unset, callbacks are published only on the relay topic and no
            webhook POST is made.

            Basic auth can be embedded in the URL in the format
            `username:password@url`.
        SWAIG:
          $ref: '#/components/schemas/SWML.Calling.AISidecarSWAIG'
          description: SWAIG functions and MCP servers available to the sidecar.
        permissions:
          $ref: '#/components/schemas/SWML.Calling.AISidecarPermissions'
          description: SWAIG permission overrides. Defaults to all permissions enabled.
        global_data:
          $ref: '#/components/schemas/CallingAiSidecarParamsGlobalData'
          description: >-
            A key-value object of data that is available throughout the sidecar
            session. You can reference it in the prompt with variable expansion,
            and it is included in the requests sent to your tools.

            It also persists across sessions on the same call leg.
        hints:
          type: array
          items:
            type: string
          description: >-
            Hints that improve speech recognition of specific terms, such as
            product names, competitor names, jargon, or customer names. Strongly
            recommended.
        params:
          $ref: '#/components/schemas/SWML.Calling.AISidecarParams'
          description: Tuning options for the sidecar.
        action:
          $ref: '#/components/schemas/SWML.Calling.AISidecarSummarizeAction'
          description: >-
            Summarize the conversation instead of starting a sidecar. When you
            include `action.summarize`,

            the request asks the sidecar already attached to the call for a
            one-off summary and returns

            rather than attaching a sidecar. The other properties, including
            `lang`, are not used and can be omitted.
        lang:
          type: string
          minLength: 1
          description: >-
            The conversation language as a single BCP-47 tag. Sets the speech
            recognition

            language and is shared with the model as a hint. Required to attach
            a sidecar;

            not used with `action.summarize`.
      required:
        - node_id
        - call_id
      title: Calling.AiSidecarParams
    calling.ai_sidecar_callingAiSidecarRequest:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingAiSidecarMessagesCallingAiSidecarRequestJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: Request id, echoed on the correlated response.
        method:
          $ref: >-
            #/components/schemas/ChannelsCallingAiSidecarMessagesCallingAiSidecarRequestMethod
          description: The name of the JSON-RPC method being invoked.
        params:
          $ref: '#/components/schemas/Calling.AiSidecarParams'
          description: The method's input parameters.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        A JSON-RPC request frame. `Method` is the method name; `Params` is the
        method's input.
      title: calling.ai_sidecar_callingAiSidecarRequest

```