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

# userEvent

> Send custom user-defined events on an active call via REST.

Send a custom user-defined event on an active call. User events allow you
to pass arbitrary data between call control applications and event handlers.
Listeners registered for user events on the Relay side will receive the
payload you send here.

## **Request**

### Schema (`Calling.CallUserEventRequest`)

```yaml
components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    CallingCallUserEventRequestCommand:
      type: string
      enum:
        - calling.user_event
      description: >-
        The `calling.user_event` command is used to fire a custom user event on
        the call.
      title: CallingCallUserEventRequestCommand
    CallingCallUserEventRequestParamsEvent:
      type: object
      properties: {}
      description: Arbitrary JSON event data to fire on the call.
      title: CallingCallUserEventRequestParamsEvent
    CallingCallUserEventRequestParams:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/CallingCallUserEventRequestParamsEvent'
          description: Arbitrary JSON event data to fire on the call.
      required:
        - event
      description: An object of parameters that will be utilized by the active command.
      title: CallingCallUserEventRequestParams
    Calling.CallUserEventRequest:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: The unique identifying ID of an existing call.
        command:
          $ref: '#/components/schemas/CallingCallUserEventRequestCommand'
          description: >-
            The `calling.user_event` command is used to fire a custom user event
            on the call.
        params:
          $ref: '#/components/schemas/CallingCallUserEventRequestParams'
          description: An object of parameters that will be utilized by the active command.
      required:
        - id
        - command
        - params
      title: Calling.CallUserEventRequest
```

## **Response**

### Schema (`Calling.CallResponse`)

```yaml
components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    Calling.CallDirection:
      type: string
      enum:
        - inbound
        - outbound
        - outbound-api
      description: The direction of the call.
      title: Calling.CallDirection
    CallingCallLegSource:
      type: string
      enum:
        - realtime_api
      description: Source of this call.
      title: CallingCallLegSource
    Calling.ChargeDetails:
      type: object
      properties:
        description:
          type: string
          description: Description for this charge.
        charge:
          type: number
          format: double
          description: Charged amount.
      required:
        - description
        - charge
      description: One itemized charge applied to the call.
      title: Calling.ChargeDetails
    Calling.CallResponseStatus:
      type: string
      enum:
        - queued
        - initiated
        - created
        - ringing
        - answered
        - ending
        - ended
        - failed
        - canceled
        - completed
      description: The status of the call throughout its lifecycle.
      title: Calling.CallResponseStatus
    CallingCallLegType0:
      type: string
      enum:
        - relay_pstn_call
      title: CallingCallLegType0
    CallingCallLegType1:
      type: string
      enum:
        - relay_sip_call
      title: CallingCallLegType1
    CallingCallLegType2:
      type: string
      enum:
        - relay_webrtc_call
      title: CallingCallLegType2
    CallingCallLegType:
      oneOf:
        - $ref: '#/components/schemas/CallingCallLegType0'
        - $ref: '#/components/schemas/CallingCallLegType1'
        - $ref: '#/components/schemas/CallingCallLegType2'
      description: Type of this call.
      title: CallingCallLegType
    Calling.CallLeg:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: >-
            The unique identifier of the call on SignalWire. This can be used to
            update the call programmatically.
        from:
          type: string
          description: The origin number or address.
        to:
          type: string
          description: The destination number or address.
        direction:
          $ref: '#/components/schemas/Calling.CallDirection'
          description: The direction of the call.
        source:
          $ref: '#/components/schemas/CallingCallLegSource'
          description: Source of this call.
        url:
          type:
            - string
            - 'null'
          description: The URL associated with this call.
        charge:
          type: number
          format: double
          description: Total charge for this call.
        created_at:
          type: string
          format: date-time
          description: The date and time when the call was created.
        charge_details:
          type: array
          items:
            $ref: '#/components/schemas/Calling.ChargeDetails'
          description: Details on charges associated with this call.
        status:
          oneOf:
            - $ref: '#/components/schemas/Calling.CallResponseStatus'
            - type: 'null'
          description: The status of the call.
        duration:
          type:
            - integer
            - 'null'
          description: The duration of the call in seconds.
        duration_ms:
          type:
            - integer
            - 'null'
          description: The duration of the call in milliseconds.
        billing_ms:
          type:
            - integer
            - 'null'
          description: The billable duration of the call in milliseconds.
        type:
          $ref: '#/components/schemas/CallingCallLegType'
          description: Type of this call.
        parent_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: The parent call ID if this is a child call.
      required:
        - id
        - from
        - to
        - direction
        - source
        - url
        - charge
        - created_at
        - charge_details
        - status
        - duration
        - duration_ms
        - billing_ms
        - type
        - parent_id
      description: Returned when the call is a standard PSTN, SIP, or WebRTC call.
      title: Calling.CallLeg
    CallingFabricDeviceLegSource:
      type: string
      enum:
        - realtime_api
      description: Source of this call.
      title: CallingFabricDeviceLegSource
    CallingFabricDeviceLegType:
      type: string
      enum:
        - fabric_subscriber_device_leg
      description: Type of this call.
      title: CallingFabricDeviceLegType
    Calling.FabricDeviceLeg:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: >-
            The unique identifier of the call on SignalWire. This can be used to
            update the call programmatically.
        from:
          type: string
          description: The origin number or address.
        to:
          type: string
          description: The destination number or address.
        direction:
          $ref: '#/components/schemas/Calling.CallDirection'
          description: The direction of the call.
        source:
          $ref: '#/components/schemas/CallingFabricDeviceLegSource'
          description: Source of this call.
        url:
          type:
            - string
            - 'null'
          description: The URL associated with this call.
        charge:
          type: number
          format: double
          description: Total charge for this call.
        created_at:
          type: string
          format: date-time
          description: The date and time when the call was created.
        charge_details:
          type: array
          items:
            $ref: '#/components/schemas/Calling.ChargeDetails'
          description: Details on charges associated with this call.
        status:
          description: >-
            The status of the call. Always null for Fabric subscriber device
            legs.
        type:
          $ref: '#/components/schemas/CallingFabricDeviceLegType'
          description: Type of this call.
      required:
        - id
        - from
        - to
        - direction
        - source
        - url
        - charge
        - created_at
        - charge_details
        - status
        - type
      description: >-
        Returned when the call is a Fabric subscriber device leg. The `status`
        field is always null for this type.
      title: Calling.FabricDeviceLeg
    Calling.CallResponse:
      oneOf:
        - $ref: '#/components/schemas/Calling.CallLeg'
        - $ref: '#/components/schemas/Calling.FabricDeviceLeg'
      title: Calling.CallResponse
```

## **Example**

```typescript {9}
import { RestClient } from "@signalwire/sdk";

const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});

await client.calling.userEvent("call-id-xxx", {
  event: { action: "order.confirmed", order_id: "ORD-12345", amount: 49.99 },
});
```

> Send custom user-defined events on an active call via REST.