Update the status of the media session

PUT/webrtc/sessions/{mediaSessionId}/status

Update the status of the media session, this may include updating SDP media

The API consumer shall construct the API path using the mediaSessionId supplied in the session creation response (origination) or in the invitation notification (termination).

Path ParametersExpand Collapse

mediaSessionId: string

Header ParametersExpand Collapse

"x-correlator": optional string

Body ParametersJSONExpand Collapse

answer: optional SdpDescriptor { sdp }

OFFER: An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section.

ANSWER: This type represents an answer in WebRTC Signaling. This element is not present in case there is no answer yet, or the session invitation has been declined by the Terminating Participant.This element MUST NOT be present in a request from the application to the server to create a session.

sdp: optional string

An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section

callType: optional "REGULAR" or "EMERGENCY"

Type of call. When set to EMERGENCY, the client MAY provide locationDetails. If omitted, treated as REGULAR.

One of the following:

"REGULAR"

"EMERGENCY"

locationDetails: optional WebRtcLocationDetails { confidence, coordinates, method, 2 more }

Details about the caller’s location and related information. This object adheres to 3GPP TS 24.229, RFC 4119, RFC 5139, and RFC 5491 for PIDF-LO compatibility.

confidence: optional object { pdf, value }

The confidence level of the location information.

pdf: optional "normal" or "uniform"

The probability density function (PDF) associated with the confidence value.

One of the following:

"normal"

"uniform"

value: optional number

The confidence value (percentage).

minimum0

maximum100

coordinates: optional WebRtcCircleCoordinates { latitude, longitude, radius } or WebRtcEllipsoidCoordinates { latitude, longitude, orientation, 4 more }

The coordinates of the caller’s location, specific to the chosen shape.

One of the following:

WebRtcCircleCoordinates object { latitude, longitude, radius }

latitude: number

Latitude of the center point in decimal degrees (WGS84).

formatfloat

longitude: number

Longitude of the center point in decimal degrees (WGS84).

formatfloat

radius: number

Radius of the circle in meters, indicating the uncertainty.

formatfloat

WebRtcEllipsoidCoordinates object { latitude, longitude, orientation, 4 more }

latitude: number

Latitude in the WGS 84 geocentric coordinate system.

formatfloat

longitude: number

Longitude in the WGS 84 geocentric coordinate system.

formatfloat

orientation: number

Orientation of the ellipsoid in degrees.

semiMajorAxis: number

Length of the semi-major axis of the ellipsoid in meters.

semiMinorAxis: number

Length of the semi-minor axis of the ellipsoid in meters.

verticalAxis: number

Length of the vertical axis of the ellipsoid in meters.

zAxis: number

Altitude (optional) in the WGS 84 geocentric coordinate system.

formatfloat

method: optional "GPS" or "DBH" or "DBH_HELO" or "Other"

The method used to obtain the location information.

GPS: Global Positioning System (highly accurate)
DBH: Device-Based Hybrid
DBH_HELO: Device-Based Hybrid using Apple Hybridized Emergency Location
Other: Other methods (e.g., landmarks, IP Based etc.)

One of the following:

"GPS"

"DBH"

"DBH_HELO"

"Other"

shape: optional "Circle" or "Ellipsoid"

The shape representing the caller’s location (Circle or Ellipsoid).

One of the following:

"Circle"

"Ellipsoid"

timestamp: optional string

The timestamp (in ISO 8601 format) indicating when the location information was Calculated. \nThis is crucial for emergency services to assess the timeliness of the data. if not provided current timestamp will be used by default”

formatdate-time

mediaSessionId: optional string

The media session ID created by the network. The mediaSessionId shall not be included in POST requests by the client, but must be included in the notifications from the network to the client device.

offer: optional SdpDescriptor { sdp }

OFFER: An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section.

sdp: optional string

An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section

originatorAddress: optional string

Subscriber address (Sender or Receiver)

originatorName: optional string

Friendly name of the call originator

receiverAddress: optional string

Subscriber address (Sender or Receiver)

receiverName: optional string

Friendly name of the call terminator

status: optional "Initial" or "InProgress" or "Ringing" or 12 more

Provides the status of the media session. During the session creation, this attribute SHALL NOT be included in the request.

One of the following:

"Initial"

"InProgress"

"Ringing"

"Proceeding"

"Connected"

"Terminated"

"Hold"

"Resume"

"SessionCancelled"

"Declined"

"Failed"

"Waiting"

"NoAnswer"

"NotReachable"

"Busy"

ReturnsExpand Collapse

MediaSessionInformation object { answer, callType, locationDetails, 7 more }

answer: optional SdpDescriptor { sdp }

OFFER: An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section.

sdp: optional string

An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section

callType: optional "REGULAR" or "EMERGENCY"

Type of call. When set to EMERGENCY, the client MAY provide locationDetails. If omitted, treated as REGULAR.

One of the following:

"REGULAR"

"EMERGENCY"

locationDetails: optional WebRtcLocationDetails { confidence, coordinates, method, 2 more }

Details about the caller’s location and related information. This object adheres to 3GPP TS 24.229, RFC 4119, RFC 5139, and RFC 5491 for PIDF-LO compatibility.

confidence: optional object { pdf, value }

The confidence level of the location information.

pdf: optional "normal" or "uniform"

The probability density function (PDF) associated with the confidence value.

One of the following:

"normal"

"uniform"

value: optional number

The confidence value (percentage).

minimum0

maximum100

coordinates: optional WebRtcCircleCoordinates { latitude, longitude, radius } or WebRtcEllipsoidCoordinates { latitude, longitude, orientation, 4 more }

The coordinates of the caller’s location, specific to the chosen shape.

One of the following:

WebRtcCircleCoordinates object { latitude, longitude, radius }

latitude: number

Latitude of the center point in decimal degrees (WGS84).

formatfloat

longitude: number

Longitude of the center point in decimal degrees (WGS84).

formatfloat

radius: number

Radius of the circle in meters, indicating the uncertainty.

formatfloat

WebRtcEllipsoidCoordinates object { latitude, longitude, orientation, 4 more }

latitude: number

Latitude in the WGS 84 geocentric coordinate system.

formatfloat

longitude: number

Longitude in the WGS 84 geocentric coordinate system.

formatfloat

orientation: number

Orientation of the ellipsoid in degrees.

semiMajorAxis: number

Length of the semi-major axis of the ellipsoid in meters.

semiMinorAxis: number

Length of the semi-minor axis of the ellipsoid in meters.

verticalAxis: number

Length of the vertical axis of the ellipsoid in meters.

zAxis: number

Altitude (optional) in the WGS 84 geocentric coordinate system.

formatfloat

method: optional "GPS" or "DBH" or "DBH_HELO" or "Other"

The method used to obtain the location information.

GPS: Global Positioning System (highly accurate)
DBH: Device-Based Hybrid
DBH_HELO: Device-Based Hybrid using Apple Hybridized Emergency Location
Other: Other methods (e.g., landmarks, IP Based etc.)

One of the following:

"GPS"

"DBH"

"DBH_HELO"

"Other"

shape: optional "Circle" or "Ellipsoid"

The shape representing the caller’s location (Circle or Ellipsoid).

One of the following:

"Circle"

"Ellipsoid"

timestamp: optional string

formatdate-time

mediaSessionId: optional string

The media session ID created by the network. The mediaSessionId shall not be included in POST requests by the client, but must be included in the notifications from the network to the client device.

offer: optional SdpDescriptor { sdp }

OFFER: An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section.

sdp: optional string

An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section

originatorAddress: optional string

Subscriber address (Sender or Receiver)

originatorName: optional string

Friendly name of the call originator

receiverAddress: optional string

Subscriber address (Sender or Receiver)

receiverName: optional string

Friendly name of the call terminator

status: optional "Initial" or "InProgress" or "Ringing" or 12 more

Provides the status of the media session. During the session creation, this attribute SHALL NOT be included in the request.

One of the following:

"Initial"

"InProgress"

"Ringing"

"Proceeding"

"Connected"

"Terminated"

"Hold"

"Resume"

"SessionCancelled"

"Declined"

"Failed"

"Waiting"

"NoAnswer"

"NotReachable"

"Busy"

Update the status of the media session

curl https://api.example.com/camara/webrtc/sessions/$MEDIA_SESSION_ID/status \
    -X PUT \
    -H "Authorization: Bearer $CAMARA_BEARER_TOKEN"

{
  "receiverSessionStatus": {
    "status": "InProgress",
    "answer": {
      "sdp": "\"v=0\\r\\no=- 8066321617929821805 2 IN IP4 127.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\nm=\naudio 42988 RTP/SAVPF 102 113\\r\\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2\n:c9e\\r\\nb=AS:64\\r\\na=rtcp:9 IN IP4 0.0.0.0\\r\\na=candidate:1645903805 1 udp\n2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typhost generation 0\nnetwork-id 3 network-cost 900\\r\\na=ice-ufrag:4eKp\\r\\na=ice-pwd:D4sF5Pv9vx9\nggaqxBlHbAFMx\\r\\na=ice-options:trickle renomination\\r\\na=mid:audio\\r\\na=\nextmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions\n-01\\r\\na=sendrecv\\r\\na=rtcp-mux\\r\\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm\n3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\\r\\na=rtpmap:102 AMR-WB/16000\\r\\na=fmtp:102\noctet-align=0; mode-set=0,1,2; mode-change-capability=2\\r\\na=rtpmap:113 telephone-event/16000\\r\\n\"\n"
    }
  }
}

{
  "receiverSessionStatus": {
    "status": "Ringing"
  }
}

{
  "receiverSessionStatus": {
    "status": "Connected",
    "answer": {
      "sdp": "\"v=0\\r\\no=- 4576312012535546667 4 IN IP4 127.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\nm=audio 47510 RTP/SAVPF 102 113\\r\\nc=IN\nIP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\\r\\nb=AS:64\\r\\na=rtcp:9 IN IP4 0.0.0.0\\r\\na=candidate:3108871805 1 udp\n2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\\r\\na=\nice-ufrag:47Nx\\r\\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\\r\\na=ice-options:trickle renomination\\r\\na=mid:audio\\r\\na=\nextmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\\r\\na=sendrecv\\r\\na=rtcp-mux\\r\n\\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\\r\\na=rtpmap:102 AMR-WAB/16000\n\\r\\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\\r\\na=rtpmap:113 telephone-event/16000\\r\\na=\nptime:20\\r\\n\"\n"
    }
  }
}

{
  "ReceiverSessionStatus": {
    "status": "Hold",
    "answer": {
      "sdp": "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n"
    }
  }
}

{
  "ReceiverSessionStatus": {
    "status": "Resume",
    "answer": {
      "sdp": "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n"
    }
  }
}

{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Client specified an invalid argument, request body or query param."
}

{
  "status": 400,
  "code": "OUT_OF_RANGE",
  "message": "Client specified an invalid range."
}

{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required."
}

{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action."
}

{
  "status": 403,
  "code": "INVALID_TOKEN_CONTEXT",
  "message": "originator info is not consistent with access token."
}

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found."
}

{
  "status": 404,
  "code": "IDENTIFIER_NOT_FOUND",
  "message": "Device identifier not found."
}

Returns Examples

{
  "receiverSessionStatus": {
    "status": "InProgress",
    "answer": {
      "sdp": "\"v=0\\r\\no=- 8066321617929821805 2 IN IP4 127.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\nm=\naudio 42988 RTP/SAVPF 102 113\\r\\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2\n:c9e\\r\\nb=AS:64\\r\\na=rtcp:9 IN IP4 0.0.0.0\\r\\na=candidate:1645903805 1 udp\n2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typhost generation 0\nnetwork-id 3 network-cost 900\\r\\na=ice-ufrag:4eKp\\r\\na=ice-pwd:D4sF5Pv9vx9\nggaqxBlHbAFMx\\r\\na=ice-options:trickle renomination\\r\\na=mid:audio\\r\\na=\nextmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions\n-01\\r\\na=sendrecv\\r\\na=rtcp-mux\\r\\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm\n3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\\r\\na=rtpmap:102 AMR-WB/16000\\r\\na=fmtp:102\noctet-align=0; mode-set=0,1,2; mode-change-capability=2\\r\\na=rtpmap:113 telephone-event/16000\\r\\n\"\n"
    }
  }
}

{
  "receiverSessionStatus": {
    "status": "Ringing"
  }
}

{
  "receiverSessionStatus": {
    "status": "Connected",
    "answer": {
      "sdp": "\"v=0\\r\\no=- 4576312012535546667 4 IN IP4 127.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\nm=audio 47510 RTP/SAVPF 102 113\\r\\nc=IN\nIP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\\r\\nb=AS:64\\r\\na=rtcp:9 IN IP4 0.0.0.0\\r\\na=candidate:3108871805 1 udp\n2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\\r\\na=\nice-ufrag:47Nx\\r\\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\\r\\na=ice-options:trickle renomination\\r\\na=mid:audio\\r\\na=\nextmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\\r\\na=sendrecv\\r\\na=rtcp-mux\\r\n\\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\\r\\na=rtpmap:102 AMR-WAB/16000\n\\r\\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\\r\\na=rtpmap:113 telephone-event/16000\\r\\na=\nptime:20\\r\\n\"\n"
    }
  }
}

{
  "ReceiverSessionStatus": {
    "status": "Hold",
    "answer": {
      "sdp": "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n"
    }
  }
}

{
  "ReceiverSessionStatus": {
    "status": "Resume",
    "answer": {
      "sdp": "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n"
    }
  }
}

{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Client specified an invalid argument, request body or query param."
}

{
  "status": 400,
  "code": "OUT_OF_RANGE",
  "message": "Client specified an invalid range."
}

{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required."
}

{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action."
}

{
  "status": 403,
  "code": "INVALID_TOKEN_CONTEXT",
  "message": "originator info is not consistent with access token."
}

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found."
}

{
  "status": 404,
  "code": "IDENTIFIER_NOT_FOUND",
  "message": "Device identifier not found."
}