Skip to content
camara
Get started
API Reference
Webrtc
Sessions

Creates voice and/or video session

POST/webrtc/sessions

Creates a voice and/or video session

Header ParametersExpand Collapse
registrationId: string
"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.

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

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.

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.

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

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"

Creates voice and/or video session

curl https://api.example.com/camara/webrtc/sessions \
    -X POST \
    -H "Authorization: Bearer $CAMARA_BEARER_TOKEN"
{
  "originatorAddress": "tel:+17085852753",
  "originatorName": "tel:+17085852753",
  "receiverAddress": "tel:+17085854000",
  "receiverName": "tel:+17085854000",
  "offer": {
    "sdp": "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\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:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\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\n"
  },
  "status": "Initial",
  "mediaSessionId": "0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD"
}
{
  "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": 501,
  "code": "CALLTYPE_EMERGENCY_NOT_SUPPORTED",
  "message": "Server does not support call type EMERGENCY."
}
Returns Examples
{
  "originatorAddress": "tel:+17085852753",
  "originatorName": "tel:+17085852753",
  "receiverAddress": "tel:+17085854000",
  "receiverName": "tel:+17085854000",
  "offer": {
    "sdp": "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\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:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\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\n"
  },
  "status": "Initial",
  "mediaSessionId": "0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD"
}
{
  "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": 501,
  "code": "CALLTYPE_EMERGENCY_NOT_SUPPORTED",
  "message": "Server does not support call type EMERGENCY."
}