> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Current Media Call State

> Returns ongoing media calls the authenticated user is part of. It shows call's latest server-side state — `ringing`, `active`, etc.

### Changelog
| Version | Description |
| ------- | ----------- |
| 8.4.0   | Added       |


## OpenAPI

````json GET /api/v1/media-calls.state
{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Settings"
  },
  "servers": [
    {
      "url": "https://apiexplorer.support.rocket.chat"
    }
  ],
  "tags": [
    {
      "name": "Settings"
    },
    {
      "name": "Audit"
    },
    {
      "name": "Cloud"
    },
    {
      "name": "DNS"
    },
    {
      "name": "E2E"
    },
    {
      "name": "Import"
    },
    {
      "name": "Bulk User Import"
    },
    {
      "name": "Instances"
    },
    {
      "name": "Federation"
    },
    {
      "name": "Moderation"
    },
    {
      "name": "Device Management"
    },
    {
      "name": "Password policy"
    },
    {
      "name": "Video Conference"
    },
    {
      "name": "Media Calls"
    }
  ],
  "paths": {
    "/api/v1/media-calls.state": {
      "get": {
        "tags": [
          "Media Calls"
        ],
        "summary": "Get Current Media Call State",
        "description": "Returns ongoing media calls the authenticated user is part of. It shows call's latest server-side state — `ringing`, `active`, etc.\n\n### Changelog\n| Version | Description |\n| ------- | ----------- |\n| 8.4.0   | Added       |\n",
        "operationId": "post-api-v1-get-media-calls.state",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-User-Id"
          },
          {
            "$ref": "#/components/parameters/X-Auth-Token"
          }
        ],
        "responses": {
          "200": {
            "description": "The list of in-flight calls for the authenticated user.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "calls": {
                      "type": "array",
                      "description": "All in-flight calls the authenticated user participates in.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "_id": {
                            "type": "string",
                            "format": "uuid",
                            "description": "Unique identifier of the call.",
                            "example": "9f44ec94-2046-4fac-976b-fa8b0e022b08"
                          },
                          "service": {
                            "type": "string",
                            "enum": [
                              "webrtc"
                            ],
                            "description": "Underlying media service powering the call.",
                            "example": "webrtc"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "direct"
                            ],
                            "description": "Call topology.",
                            "example": "direct"
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "ringing",
                              "active"
                            ],
                            "description": "Current lifecycle state of the call.\n- `ringing` : invitation sent, callee has not yet answered.\n- `active` : call accepted and media is flowing.\n",
                            "example": "ringing"
                          },
                          "createdBy": {
                            "type": "object",
                            "description": "The actor who created the call.",
                            "properties": {
                              "type": {
                                "type": "string",
                                "example": "user"
                              },
                              "id": {
                                "type": "string",
                                "description": "Rocket.Chat user id.",
                                "example": "aEGCdnFoBFCFNdiyX"
                              },
                              "contractId": {
                                "type": "string",
                                "format": "uuid",
                                "description": "Device/session contract id registered with the media-call service.",
                                "example": "7b96e74d-1e01-412a-8bcb-145db1bc9ac4"
                              }
                            }
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time",
                            "description": "When the call record was created on the server.",
                            "example": "2026-04-30T13:30:53.165Z"
                          },
                          "caller": {
                            "type": "object",
                            "description": "The party initiating the call. Always carries `contractId`.",
                            "properties": {
                              "type": {
                                "type": "string",
                                "example": "user"
                              },
                              "id": {
                                "type": "string",
                                "example": "aEGCdnFoBFCFNdiyX"
                              },
                              "contractId": {
                                "type": "string",
                                "example": "7b96e74d-1e01-412a-8bcb-145db1bc9ac4"
                              },
                              "displayName": {
                                "type": "string",
                                "example": "Funke Olasupo"
                              },
                              "username": {
                                "type": "string",
                                "example": "funke.olasupo"
                              }
                            }
                          },
                          "callee": {
                            "type": "object",
                            "description": "The party being called. `contractId` is omitted while\nthe call is `ringing` (no device has answered yet)\nand populated once accepted.\n",
                            "properties": {
                              "type": {
                                "type": "string",
                                "example": "user"
                              },
                              "id": {
                                "type": "string",
                                "example": "iaZWAXecuCuBx4FnX"
                              },
                              "contractId": {
                                "type": "string",
                                "description": "Set once the call is accepted.",
                                "example": "7488b84e-e096-46fb-8d62-1e6e3db479c9"
                              },
                              "displayName": {
                                "type": "string",
                                "example": "Agent1"
                              },
                              "username": {
                                "type": "string",
                                "example": "agent1"
                              }
                            }
                          },
                          "expiresAt": {
                            "type": "string",
                            "description": "When the current state will expire if no further activity occurs.",
                            "example": "2026-04-30T13:33:12.993Z"
                          },
                          "uids": {
                            "type": "array",
                            "description": "User IDs of every participant in the call.",
                            "items": {
                              "type": "string"
                            },
                            "example": [
                              "aEGCdnFoBFCFNdiyX",
                              "iaZWAXecuCuBx4FnX"
                            ]
                          },
                          "ended": {
                            "type": "boolean",
                            "description": "Always `false` for entries returned by this endpoint.",
                            "example": false
                          },
                          "callerRequestedId": {
                            "type": "string",
                            "description": "Client-supplied correlation id for the call request.",
                            "example": "7b96e74d-1e01-412a-8bcb-145db1bc9ac4-38b61a15-8c41-4ee4-be75-977c48cd94ea"
                          },
                          "features": {
                            "type": "array",
                            "description": "Feature flags negotiated for this call.",
                            "items": {
                              "type": "string"
                            },
                            "example": [
                              "audio",
                              "screen-share",
                              "transfer",
                              "hold"
                            ]
                          },
                          "_updatedAt": {
                            "type": "string",
                            "description": "When the call record was last updated.",
                            "example": "2026-04-30T13:31:12.993Z"
                          },
                          "acceptedAt": {
                            "type": "string",
                            "description": "Set once the callee accepts. Absent while ringing.",
                            "example": "2026-04-30T13:31:10.07Z"
                          },
                          "activatedAt": {
                            "type": "string",
                            "description": "Set once media becomes active. Absent while ringing.",
                            "example": "2026-04-30T13:31:12.698Z"
                          }
                        }
                      }
                    },
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                },
                "examples": {
                  "ringing": {
                    "summary": "Outbound call is still ringing",
                    "value": {
                      "calls": [
                        {
                          "_id": "9f44ec94-2046-4fac-976b-fa8b0e022b08",
                          "service": "webrtc",
                          "kind": "direct",
                          "state": "ringing",
                          "createdBy": {
                            "type": "user",
                            "id": "aEGCdnFoBFCFNdiyX",
                            "contractId": "7b96e74d-1e01-412a-8bcb-145db1bc9ac4"
                          },
                          "createdAt": "2026-04-30T13:30:53.165Z",
                          "caller": {
                            "type": "user",
                            "id": "aEGCdnFoBFCFNdiyX",
                            "contractId": "7b96e74d-1e01-412a-8bcb-145db1bc9ac4",
                            "displayName": "Funke Olasupo",
                            "username": "funke.olasupo"
                          },
                          "callee": {
                            "type": "user",
                            "id": "iaZWAXecuCuBx4FnX",
                            "displayName": "Agent1",
                            "username": "agent1"
                          },
                          "expiresAt": "2026-04-30T13:33:02.878Z",
                          "uids": [
                            "aEGCdnFoBFCFNdiyX",
                            "iaZWAXecuCuBx4FnX"
                          ],
                          "ended": false,
                          "callerRequestedId": "7b96e74d-1e01-412a-8bcb-145db1bc9ac4-38b61a15-8c41-4ee4-be75-977c48cd94ea",
                          "features": [
                            "audio",
                            "screen-share",
                            "transfer",
                            "hold"
                          ],
                          "_updatedAt": "2026-04-30T13:31:02.878Z"
                        }
                      ],
                      "success": true
                    }
                  },
                  "active": {
                    "summary": "Call has been picked up and is active",
                    "value": {
                      "calls": [
                        {
                          "_id": "9f44ec94-2046-4fac-976b-fa8b0e022b08",
                          "service": "webrtc",
                          "kind": "direct",
                          "state": "active",
                          "createdBy": {
                            "type": "user",
                            "id": "aEGCdnFoBFCFNdiyX",
                            "contractId": "7b96e74d-1e01-412a-8bcb-145db1bc9ac4"
                          },
                          "createdAt": "2026-04-30T13:30:53.165Z",
                          "caller": {
                            "type": "user",
                            "id": "aEGCdnFoBFCFNdiyX",
                            "contractId": "7b96e74d-1e01-412a-8bcb-145db1bc9ac4",
                            "displayName": "Funke Olasupo",
                            "username": "funke.olasupo"
                          },
                          "callee": {
                            "type": "user",
                            "id": "iaZWAXecuCuBx4FnX",
                            "contractId": "7488b84e-e096-46fb-8d62-1e6e3db479c9",
                            "displayName": "Agent1",
                            "username": "agent1"
                          },
                          "expiresAt": "2026-04-30T13:33:12.993Z",
                          "uids": [
                            "aEGCdnFoBFCFNdiyX",
                            "iaZWAXecuCuBx4FnX"
                          ],
                          "ended": false,
                          "callerRequestedId": "7b96e74d-1e01-412a-8bcb-145db1bc9ac4-38b61a15-8c41-4ee4-be75-977c48cd94ea",
                          "features": [
                            "audio",
                            "screen-share",
                            "transfer",
                            "hold"
                          ],
                          "_updatedAt": "2026-04-30T13:31:12.993Z",
                          "acceptedAt": "2026-04-30T13:31:10.07Z",
                          "activatedAt": "2026-04-30T13:31:12.698Z"
                        }
                      ],
                      "success": true
                    }
                  },
                  "empty": {
                    "summary": "User has no in-flight calls",
                    "value": {
                      "calls": [],
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/authorizationError"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "X-User-Id": {
        "name": "X-User-Id",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": "CkCPNctrgCDfmWLqC",
        "description": "The user ID."
      },
      "X-Auth-Token": {
        "name": "X-Auth-Token",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": "1Dd4iN_ClKn5jl-xPC36snQ4s9Zd5GZnXCQuCNSKcVE",
        "description": "The authentication token."
      }
    },
    "responses": {
      "authorizationError": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            },
            "examples": {
              "Authorization Error": {
                "value": {
                  "status": "error",
                  "message": "You must be logged in to do this."
                }
              }
            }
          }
        }
      }
    }
  }
}
````