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

GET /

Join an ad-hoc audio conference

Reference: https://signalwire.com/docs/apis/relay/server/calling/calling-join-conference

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: calling.join_conference
  version: subpackage_callingJoinConference.calling.join_conference
  description: Join an ad-hoc audio conference
channels:
  /:
    description: Join an ad-hoc audio conference
    publish:
      operationId: subpackage_callingJoinConference.calling.join_conference-publish
      summary: Server messages
      message:
        oneOf:
          - $ref: >-
              #/components/messages/subpackage_callingJoinConference.calling.join_conference-server-0-onCallingJoinConferenceConferenceEvent
          - $ref: >-
              #/components/messages/subpackage_callingJoinConference.calling.join_conference-server-1-onCallingJoinConferenceResponse
    subscribe:
      operationId: subpackage_callingJoinConference.calling.join_conference-subscribe
      summary: calling.join_conference
      message:
        name: callingJoinConference
        title: calling.join_conference
        payload:
          $ref: >-
            #/components/schemas/calling.join_conference_callingJoinConferenceRequest
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  messages:
    subpackage_callingJoinConference.calling.join_conference-server-0-onCallingJoinConferenceConferenceEvent:
      name: onCallingJoinConferenceConferenceEvent
      title: calling.conference
      payload:
        $ref: '#/components/schemas/calling.join_conference_conferenceEvent'
    subpackage_callingJoinConference.calling.join_conference-server-1-onCallingJoinConferenceResponse:
      name: onCallingJoinConferenceResponse
      title: calling.join_conference response
      payload:
        $ref: >-
          #/components/schemas/calling.join_conference_callingJoinConferenceResponse
  schemas:
    ChannelsCallingJoinConferenceMessagesConferenceEventJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingJoinConferenceMessagesConferenceEventJsonrpc
    ChannelsCallingJoinConferenceMessagesConferenceEventMethod:
      type: string
      enum:
        - signalwire.event
      description: Always `signalwire.event`.
      title: ChannelsCallingJoinConferenceMessagesConferenceEventMethod
    ChannelsCallingJoinConferenceMessagesConferenceEventParamsEventType:
      type: string
      enum:
        - calling.conference
      description: The event type — identifies which event this is.
      title: ChannelsCallingJoinConferenceMessagesConferenceEventParamsEventType
    Calling.ConferenceStatus:
      type: string
      enum:
        - conference-end
        - conference-start
        - participant-leave
        - participant-join
        - participant-mute
        - participant-unmute
        - participant-deaf
        - participant-undeaf
        - participant-hold
        - participant-unhold
        - participant-modify
        - participant-speech-start
        - participant-speech-stop
        - announcement-end
        - announcement-fail
        - record-start
        - record-pause
        - record-resume
        - record-stop
        - bot-join
        - bot-leave
      title: Calling.ConferenceStatus
    Calling.ConferenceReasonEnded:
      type: string
      enum:
        - conference-ended-via-api
        - last-participant-kicked
        - last-participant-left
        - participant-with-end-conference-on-exit-kicked
        - participant-with-end-conference-on-exit-left
      title: Calling.ConferenceReasonEnded
    Calling.ConferenceParams:
      type: object
      properties:
        node_id:
          type: string
          description: >-
            Opaque identifier that, paired with `call_id`, addresses the call
            this event was delivered for. Treat it as opaque and echo back the
            value you received.
        segment_id:
          type: string
          description: Identifier of the call segment this event belongs to.
        tag:
          type: string
          description: The `tag` you set when placing the call, if any.
        subscriber_id:
          type: string
          description: The subscriber the call belongs to, when it is a subscriber call.
        address_id:
          type: string
          description: The address the call belongs to, when it is a subscriber call.
        subscriber_name:
          type: string
          description: >-
            Display name of the subscriber, when it is a subscriber call and a
            name is set.
        conference_id:
          type: string
          description: The UUID of the conference.
        conference_node_id:
          type: string
          description: >-
            Opaque identifier of the node hosting the conference. Distinct from
            `node_id`, which identifies the call.
        name:
          type: string
          description: The name of the conference.
        region:
          type: string
          description: >-
            The region the conference is running in (`global`, `us`, `eu`, or
            `ch`).
        size:
          type: integer
          description: The number of members currently in the conference.
        status:
          $ref: '#/components/schemas/Calling.ConferenceStatus'
          description: What happened in the conference — one of the values below.
        call_id:
          type: string
          description: >-
            The `call_id` of the call this event was delivered for. For
            participant events, the participant the event is about.
        muted:
          type: boolean
          description: Whether the participant is muted. Present on participant events.
        deaf:
          type: boolean
          description: >-
            Whether the participant is deafened (can't hear the conference).
            Present on participant events.
        hold:
          type: boolean
          description: Whether the participant is on hold. Present on participant events.
        coaching:
          type: boolean
          description: >-
            Whether the participant is coaching another participant. Present on
            participant events.
        call_id_to_coach:
          type: string
          description: >-
            The `call_id` of the participant being coached. Present on coaching
            participant events.
        end_on_leave:
          type: boolean
          description: >-
            Whether the conference ends when this participant leaves. Present on
            participant events.
        start_on_join:
          type: boolean
          description: >-
            Whether the conference starts when this participant joins. Present
            on participant events.
        call_id_ending_conf:
          type: string
          description: >-
            The `call_id` of the participant whose departure ended the
            conference. Present on `conference-end`.
        reason_ended:
          $ref: '#/components/schemas/Calling.ConferenceReasonEnded'
          description: Why the conference ended. Present on `conference-end`.
        recording_url:
          type: string
          format: uri
          description: >-
            Link to the conference recording. Present on `record-*` events and
            on `conference-end` when the conference was recorded.
        recording_duration:
          type: integer
          description: >-
            Recording duration in seconds. Present on `record-stop` and on
            `conference-end` when the conference was recorded.
        recording_file_size:
          type: integer
          description: >-
            Recording file size in bytes. Present on `record-stop` and on
            `conference-end` when the conference was recorded.
        announce_url:
          type: string
          format: uri
          description: >-
            The URL of the announcement being played. Present on announcement
            events.
      required:
        - conference_id
        - conference_node_id
        - name
        - region
        - size
        - status
      description: >-
        The details of a conference event. Read `status` first: it tells you
        what

        happened and therefore which of the optional fields below are filled in.
      title: Calling.ConferenceParams
    ChannelsCallingJoinConferenceMessagesConferenceEventParams:
      type: object
      properties:
        event_type:
          $ref: >-
            #/components/schemas/ChannelsCallingJoinConferenceMessagesConferenceEventParamsEventType
          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.ConferenceParams'
          description: The event-specific payload.
      required:
        - event_type
        - event_channel
        - timestamp
        - params
      description: The event envelope.
      title: ChannelsCallingJoinConferenceMessagesConferenceEventParams
    calling.join_conference_conferenceEvent:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingJoinConferenceMessagesConferenceEventJsonrpc
          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/ChannelsCallingJoinConferenceMessagesConferenceEventMethod
          description: Always `signalwire.event`.
        params:
          $ref: >-
            #/components/schemas/ChannelsCallingJoinConferenceMessagesConferenceEventParams
          description: The event envelope.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        Fires throughout a conference's life: when it starts and ends, and each
        time a

        participant joins, leaves, mutes, holds, speaks, or an announcement
        plays.

        Check `status` to see what happened. Events are delivered per call: for
        each

        call you control in the conference, you receive that call's own
        participant

        events plus the conference start and end, and every event carries that

        call's `call_id` and `node_id`. Events about other participants are not

        delivered; to receive every conference event, use `status_callback` on

        `calling.join_conference`.
      title: calling.join_conference_conferenceEvent
    ChannelsCallingJoinConferenceMessagesCallingJoinConferenceResponseJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: >-
        ChannelsCallingJoinConferenceMessagesCallingJoinConferenceResponseJsonrpc
    Calling.JoinConferenceResult:
      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
      title: Calling.JoinConferenceResult
    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.join_conference_callingJoinConferenceResponse:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingJoinConferenceMessagesCallingJoinConferenceResponseJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: The id of the request this responds to.
        result:
          $ref: '#/components/schemas/Calling.JoinConferenceResult'
          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.join_conference_callingJoinConferenceResponse
    ChannelsCallingJoinConferenceMessagesCallingJoinConferenceRequestJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingJoinConferenceMessagesCallingJoinConferenceRequestJsonrpc
    ChannelsCallingJoinConferenceMessagesCallingJoinConferenceRequestMethod:
      type: string
      enum:
        - calling.join_conference
      description: The name of the JSON-RPC method being invoked.
      title: ChannelsCallingJoinConferenceMessagesCallingJoinConferenceRequestMethod
    Calling.ConferenceBeep:
      type: string
      enum:
        - 'true'
        - 'false'
        - onEnter
        - onExit
      title: Calling.ConferenceBeep
    CallingJoinConferenceParamsWaitUrl1:
      type: string
      enum:
        - ''
      title: CallingJoinConferenceParamsWaitUrl1
    CallingJoinConferenceParamsWaitUrl:
      oneOf:
        - type: string
          format: uri
        - $ref: '#/components/schemas/CallingJoinConferenceParamsWaitUrl1'
      description: >-
        A URL to cXML, or to an mp3/wav file, to play while this participant
        waits for the conference to start. Defaults to hold music. Set to an
        empty string to wait in silence.
      title: CallingJoinConferenceParamsWaitUrl
    Calling.ConferenceRecord:
      type: string
      enum:
        - do-not-record
        - record-from-start
      title: Calling.ConferenceRecord
    Calling.ConferenceRegion:
      type: string
      enum:
        - global
        - us
        - eu
        - ch
      title: Calling.ConferenceRegion
    Calling.ConferenceTrim:
      type: string
      enum:
        - trim-silence
        - do-not-trim
      title: Calling.ConferenceTrim
    Calling.ConferenceAcl:
      type: string
      enum:
        - private
        - public-read
      title: Calling.ConferenceAcl
    Calling.ConferenceCallbackEventType:
      type: string
      enum:
        - relay
        - cxml
        - laml
      title: Calling.ConferenceCallbackEventType
    Calling.ConferenceCallbackMethod:
      type: string
      enum:
        - GET
        - POST
      title: Calling.ConferenceCallbackMethod
    CallingStreamDeviceParamsStatusUrlMethod:
      type: string
      enum:
        - GET
        - POST
      default: POST
      description: HTTP method for `status_url`.
      title: CallingStreamDeviceParamsStatusUrlMethod
    Calling.StreamDeviceParams:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Stream target — `wss://` required.
        name:
          type: string
          description: Optional stream name.
        codec:
          type: string
          description: >-
            Codec, optionally with rate/ptime modifiers — `@<ms>i` sets the
            packetization

            interval (how many milliseconds of audio per packet), `@<hz>h` sets
            the sample

            rate (e.g. `PCMU@40i`, `L16@24000h@40i`). One of
            `PCMU|PCMA|G722|L16`.
        status_url:
          type: string
          format: uri
          description: Webhook for stream status.
        status_url_method:
          $ref: '#/components/schemas/CallingStreamDeviceParamsStatusUrlMethod'
          default: POST
          description: HTTP method for `status_url`.
        realtime:
          type: boolean
          default: false
          description: >-
            When `true`, stream audio in real time rather than buffered. Default
            `false`.
        authorization_bearer_token:
          type: string
          description: Bearer token sent to the stream endpoint.
        custom_parameters:
          type: object
          additionalProperties:
            description: Any type
          description: Arbitrary custom parameters forwarded to the stream endpoint.
      required:
        - url
      description: >-
        Parameters for connecting a call to a bidirectional audio stream over
        WebSocket (`calling.connect`, `stream` device type).
      title: Calling.StreamDeviceParams
    Calling.JoinConferenceParams:
      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.
        name:
          type: string
          description: >-
            The name of the conference to join. If a conference with this name
            does not exist yet, it is created.
        muted:
          type: boolean
          default: false
          description: >-
            Join the conference with this participant muted. Defaults to
            `false`.
        beep:
          $ref: '#/components/schemas/Calling.ConferenceBeep'
          description: >-
            Whether a beep plays as participants enter or leave. Defaults to
            `true`.
        start_on_enter:
          type: boolean
          default: true
          description: >-
            Whether the conference starts when this participant enters. Defaults
            to `true`.
        end_on_exit:
          type: boolean
          default: false
          description: >-
            Whether the conference ends for everyone when this participant
            leaves. Defaults to `false`.
        wait_url:
          $ref: '#/components/schemas/CallingJoinConferenceParamsWaitUrl'
          description: >-
            A URL to cXML, or to an mp3/wav file, to play while this participant
            waits for the conference to start. Defaults to hold music. Set to an
            empty string to wait in silence.
        max_participants:
          type: integer
          minimum: 1
          description: >-
            The maximum number of participants allowed in the conference.
            Defaults to `100000`. Values below 2 or above 100000 are ignored and
            the default is used.
        record:
          $ref: '#/components/schemas/Calling.ConferenceRecord'
          description: >-
            Whether and when to record the conference. Defaults to
            `do-not-record`.
        region:
          $ref: '#/components/schemas/Calling.ConferenceRegion'
          description: >-
            The region where the conference media is hosted. Defaults to
            `global`.
        trim:
          $ref: '#/components/schemas/Calling.ConferenceTrim'
          description: >-
            Whether to trim silence from the recording. Defaults to
            `trim-silence`.
        acl:
          $ref: '#/components/schemas/Calling.ConferenceAcl'
          description: >-
            Controls who can access the conference recording: `private` or
            `public-read`.
        coach:
          type: string
          description: >-
            The `call_id` (UUID) of the participant being coached. A coach can
            be heard only by the call being coached, not by the rest of the
            conference. Not set by default.
        status_callback:
          type: string
          format: uri
          description: A URL to receive conference status callbacks. Not set by default.
        status_callback_event:
          type: string
          description: >-
            A space-separated list of which conference events to deliver to

            `status_callback`. Available events: `start`, `end`, `join`,
            `leave`,

            `mute`, `hold`, `modify`, `speaker`, `announcement`. Defaults to
            `end` when

            `status_callback` is set.
        status_callback_event_type:
          $ref: '#/components/schemas/Calling.ConferenceCallbackEventType'
          description: The payload format for `status_callback`. Defaults to `relay`.
        status_callback_method:
          $ref: '#/components/schemas/Calling.ConferenceCallbackMethod'
          description: >-
            The HTTP method used to deliver `status_callback`. Defaults to
            `POST`. Ignored when `status_callback_event_type` is `relay`.
        recording_status_callback:
          type: string
          format: uri
          description: A URL to receive recording status callbacks. Not set by default.
        recording_status_callback_event:
          type: string
          description: >-
            Which recording lifecycle event to deliver to
            `recording_status_callback`:

            `in-progress`, `completed`, or `absent`. Only a single event is
            applied;

            any other value, including a list of several events, is treated as

            `completed`. Defaults to `completed`.
        recording_status_callback_event_type:
          $ref: '#/components/schemas/Calling.ConferenceCallbackEventType'
          description: >-
            The payload format for `recording_status_callback`. Defaults to
            `relay`.
        recording_status_callback_method:
          $ref: '#/components/schemas/Calling.ConferenceCallbackMethod'
          description: >-
            The HTTP method used to deliver `recording_status_callback`.
            Defaults to `POST`. Ignored when
            `recording_status_callback_event_type` is `relay`.
        stream:
          $ref: '#/components/schemas/Calling.StreamDeviceParams'
          description: >-
            Attach a bidirectional WebSocket audio stream to the conference, for
            example to

            feed audio to a bot or transcription service. Uses the same stream
            settings as

            the stream device in `calling.connect`.
      required:
        - node_id
        - call_id
        - name
      title: Calling.JoinConferenceParams
    calling.join_conference_callingJoinConferenceRequest:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingJoinConferenceMessagesCallingJoinConferenceRequestJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: Request id, echoed on the correlated response.
        method:
          $ref: >-
            #/components/schemas/ChannelsCallingJoinConferenceMessagesCallingJoinConferenceRequestMethod
          description: The name of the JSON-RPC method being invoked.
        params:
          $ref: '#/components/schemas/Calling.JoinConferenceParams'
          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.join_conference_callingJoinConferenceRequest

```