Create WebRTC Connection

POST

https://api.orga-ai.com/v1/realtime/calls

Creates a new real-time call session with Orga AI by exchanging a WebRTC SDP offer for an SDP answer and receiving a conversation_id.

This endpoint finalizes the negotiation between your client and Orga’s servers.
You must call it with an ephemeral token from /v1/realtime/client-secrets.

This call is typically made from your frontend or mobile app, not your backend, using the short-lived ephemeral token.

Headers

Name	Required	Description
`Authorization`	✅	The ephemeral token issued by `POST /v1/realtime/client-secrets`
`Content-Type`	✅	`application/json`

Request Body

The request body includes a WebRTC SDP offer (plus ICE candidates) and optional configuration parameters.

Full Example:


{
  "offer": {
    "sdp": "v=0\r\no=- 3971856138 3971856138 IN IP4 0.0.0.0\r\ns=- ...",
    "type": "offer",
    "candidates": [
      {
        "candidate": "candidate:842163049 1 udp 1677729535 192.168.1.2 51856 typ srflx raddr 0.0.0.0 rport 0",
        "sdpMid": "audio",
        "sdpMLineIndex": 0
      }
    ]
  },
  "params": {
    "voice": "alloy",
    "model": "orga-1-beta",
    "temperature": 0.5,
    "return_transcription": false,
    "instructions": null,
    "modalities": ["audio", "video"],
    "history": true
  }
}

Field	Type	Required	Description
offer	object	✅	Client’s SDP data used to start the WebRTC session
offer.sdp	string	✅	Full local SDP offer from RTCPeerConnection.localDescription.sdp
offer.type	string	✅	Typically “offer”
offer.candidates	array	✅	ICE candidates gathered from the client
params	object	—	Optional session configuration
params.voice	string	optional	Voice model (“alloy” by default)
params.model	string	optional	Model used for the interaction
params.temperature	number	optional	Sampling temperature
params.return_transcription	boolean	optional	Whether to return user audio transcriptions
params.instructions	string	optional	System or persona instructions string
params.modalities	array	optional	Active modalities, e.g. [“audio”,“video”]
params.history	boolean	optional	Persist session context/history

The params object may be sent empty ({}) — default values will be applied by the API.

Example Request (cURL)


curl -X POST "https://api.orga-ai.com/v1/realtime/calls" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "offer": {
      "sdp": "v=0\r\no=- 3971856138...",
      "type": "offer",
      "candidates": []
    },
    "params": {
      "model": "orga-1-beta",
      "voice": "alloy"
    }
  }'

Example Response


{
  "answer": {
    "sdp": "v=0\r\no=- 3971856138 3971856138 IN IP4 0.0.0.0\r\ns=-...",
    "type": "answer"
  },
  "conversation_id": "6913388afae3c6dd9a59b7ad"
}

Field	Type	Description
answer	object	SDP answer created by Orga to complete the connection
answer.sdp	string	Session Description Protocol (SDP) answer to feed into your RTCPeerConnection.setRemoteDescription()
answer.type	string	Always “answer”
conversation_id	string	Identifier for this real-time session

🧠 Next Step: Use answer.sdp and answer.type to set Orga’s response as the remote description in your peer connection.


await peerConnection.setRemoteDescription(answer);

Error Responses

401 — Invalid Ephemeral Token

Returned when your ephemeral token is expired or invalid.


{
  "error": {
    "message": "Invalid ephemeral token",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

403 — Missing Authorization Header

Returned when no bearer token was provided.


{
  "error": {
    "message": "Not authenticated",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

422 — Missing Required Fields

Returned when mandatory properties are missing from the request body.

Missing offer:


{
  "detail": [
    {
      "loc": ["body", "offer"],
      "msg": "Field required",
      "type": "missing",
      "input": null
    }
  ]
}

Missing params:


{
  "detail": [
    {
      "loc": ["body", "params"],
      "msg": "Field required",
      "type": "missing",
      "input": null
    }
  ]
}

Usage Notes

Always call this endpoint after generating an SDP offer and ICE candidates.
Requires the ephemeral token from /v1/realtime/client-secrets.
params are optional — defaults will be used if omitted or sent empty.
The response’s answer should be applied to your local RTCPeerConnection immediately to finalize the handshake.
The conversation_id can be used to identify or resume sessions.

💡 Tip: The client-secrets → ice-config → calls chain completes the full real‑time connection flow.