> 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.

# ai.sidecar

GET /

Receive ai.sidecar events

Reference: https://signalwire.com/docs/apis/relay/client/fabric/ai-sidecar

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: ai.sidecar
  version: subpackage_aiSidecar.ai.sidecar
  description: Receive ai.sidecar events
channels:
  /:
    description: Receive ai.sidecar events
    publish:
      operationId: subpackage_aiSidecar.ai.sidecar-publish
      summary: ai.sidecar
      message:
        name: onAiSidecarFabricAiSidecarEvent
        title: ai.sidecar
        payload:
          $ref: '#/components/schemas/ai.sidecar_fabricAiSidecarEvent'
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  schemas:
    ChannelsAiSidecarMessagesFabricAiSidecarEventJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsAiSidecarMessagesFabricAiSidecarEventJsonrpc
    ChannelsAiSidecarMessagesFabricAiSidecarEventMethod:
      type: string
      enum:
        - signalwire.event
      description: Always `signalwire.event`.
      title: ChannelsAiSidecarMessagesFabricAiSidecarEventMethod
    ChannelsAiSidecarMessagesFabricAiSidecarEventParamsEventType:
      type: string
      enum:
        - ai.sidecar
      description: The event type — identifies which event this is.
      title: ChannelsAiSidecarMessagesFabricAiSidecarEventParamsEventType
    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
    Fabric.FabricAiSidecarParams:
      type: object
      properties:
        call_id:
          type: string
          description: >-
            Unique identifier of the call this event is about. Always present on
            Fabric events.
        node_id:
          type: string
          description: The node the call leg lives on.
        room_session_id:
          type: string
          description: >-
            The room session this call leg belongs to. In a 1:1 call this equals
            the `call_id`.
        segment_id:
          type: string
          description: >-
            Identifier of the call segment this event belongs to, for
            correlating events within the same segment.
        tag:
          type: string
          description: >-
            The `tag` the leg was dialed with, when a server-side application
            set one on the dial. Absent otherwise.
        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:
        - call_id
        - node_id
        - room_session_id
        - call_info
        - sidecar_event
      title: Fabric.FabricAiSidecarParams
    ChannelsAiSidecarMessagesFabricAiSidecarEventParams:
      type: object
      properties:
        event_type:
          $ref: >-
            #/components/schemas/ChannelsAiSidecarMessagesFabricAiSidecarEventParamsEventType
          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/Fabric.FabricAiSidecarParams'
          description: The event-specific payload.
      required:
        - event_type
        - event_channel
        - timestamp
        - params
      description: The event envelope.
      title: ChannelsAiSidecarMessagesFabricAiSidecarEventParams
    ai.sidecar_fabricAiSidecarEvent:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsAiSidecarMessagesFabricAiSidecarEventJsonrpc
          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/ChannelsAiSidecarMessagesFabricAiSidecarEventMethod
          description: Always `signalwire.event`.
        params:
          $ref: >-
            #/components/schemas/ChannelsAiSidecarMessagesFabricAiSidecarEventParams
          description: The event envelope.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        Fires on a Call Fabric call leg when the AI sidecar reports activity.
        Same fields as the Calling API's `calling.ai.sidecar` event. SWML or a
        server-side application attaches the sidecar to the leg; there is no
        client request that attaches it.
      title: ai.sidecar_fabricAiSidecarEvent

```