cURL Quickstart

Who This Is For

• Testers: Developers verifying the /v1/realtime/client-secrets and /v1/realtime/ice-config endpoints before building a backend.

• Backend and Full-Stack Developers: Those creating a secure proxy (e.g., Node.js, Python, Go) to fetch client secrets and ICE servers for WebRTC integration.

Why cURL?

cURL provides a language-agnostic way to demonstrate HTTP requests, making it easy to test endpoints or adapt them into any backend technology without relying on specific languages like JavaScript or Python.

Prerequisites

• cURL: Ensure installed (curl --version).

• API Key: Obtain from the Orga AI dashboard.

• Backend Proxy: For production, set up a server (e.g., Node.js, Python, Go) to securely handle API requests.

Step 1: Test Client Secrets

Fetch an ephemeral token for authentication, keeping the API key server-side.

ORGA_AI_API_KEY="your_api_key" 
USER_EMAIL="user@example.com"

ENCODED_EMAIL=$(printf %s "$USER_EMAIL" | jq -s -R -r @uri)           

HTTP_STATUS=$(curl -X POST \
"https://api.orga-ai.com/v1/realtime/client-secrets?email=${ENCODED_EMAIL}" \
  -H "Authorization: Bearer $ORGA_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -s -w "%{http_code}" \
  -o response.json)
if [ "$HTTP_STATUS" -eq 200 ]; then
  echo "Success! API request succeeded."
  EPHEMERAL_TOKEN=$(grep -o '"ephemeral_token":"[^"]*"' response.json | cut -d'"' -f4)
  if [ -n "$EPHEMERAL_TOKEN" ]; then
    echo "Success! Token extracted: $EPHEMERAL_TOKEN"
    export EPHEMERAL_TOKEN
  else
    echo "Error: Token extraction failed."
    exit 1
  fi
else
  echo "Error: API request failed (HTTP Status: $HTTP_STATUS)."
  cat response.json
  exit 1
fi

Response Handing

• Success: response.json contains the ephemeral_token (e.g., "abc123").

• Errors:

  • 401 Unauthorized: Invalid or expired API key.

Step 2: Test ICE servers

Retrieve the ICE server configurations for WebRTC connections.

HTTP_STATUS=$(curl -X GET "https://api.orga-ai.com/v1/realtime/ice-config" -H "Authorization: Bearer $EPHEMERAL_TOKEN" -H "Content-Type: application/json" -s -w "%{http_code}" -o ice_config.json)
if [ "$HTTP_STATUS" -eq 200 ]; then
  echo "Success! ICE servers received."
else
  echo "Error: Request failed (HTTP Status: $HTTP_STATUS)."
  cat ice_config.json
  exit 1
fi

Response Handling

• Success: ice_config.json contains an iceServers array, e.g.:

{
  "iceServers": [
    {
      "urls": [
        "stun:stun1.example.net",
        "turn:turn.example.org"
      ],
      "username": "user123",
      "credential": "pass123"
    },
    {
      "urls": ["turns:turns.example.org"]
    }
  ]
}

• Errors:

  • 401 Unauthorized: Invalid or expired ephemeral token.

  • 429 Too Many Requests: Retry after a delay.

Step 3: Start a WebRTC session

The /v1/realtime/calls endpoint requires a WebRTC-capable environment (e.g., browser, mobile app, or WebRTC library like wrtc or aiortc). You can use the Orga AI SDKs, (Web, React Native), for simplified integration or implement a custom WebRTC solution.

Option 1: Use Orga AI SDKs

• Adapt Steps 1 and 2 into a backend proxy (e.g., Node.js, Python, Go) to fetch ephemeral_token and iceServers.

• Pass a fetchSessionConfig function or an endpoint sessionConfigEndpoint to the SDKs (React Native or Web) to handle /v1/realtime/calls.

• See React Native SDK or Web SDK for setup details.

Option 2: Custom WebRTC Implementation

In a WebRTC-capable enviroment:

1. Create an RTCPeerConnection with iceServers from Step 2.

2. Add media tracks (e.g., navigator.mediaDevices.getUserMedia({ audio: true }) in a browser).

3. Generate an SDP offer and collect ICE candidates.

4. Send a POST request to /v1/realtime/calls:

Request:

• Method: POST

• Headers:

{
  "Authorization": "Bearer <EPHEMERAL_TOKEN>",
  "Content-Type": "application/json"
}

• Body:

{
  "offer": {
    "sdp": "<SDP_OFFER>",
    "type": "offer",
    "candidates": [
      {
        "candidate": "<CANDIDATE_STRING>",
        "sdpMid": "<SDP_MID>",
        "sdpMLineIndex": <INDEX>,
        "usernameFragment": "<UFRAG>"
      },
      ...
    ]
  },
  "params": {
    "model": "orga-1-beta",
    "voice": "nova",
    "temperature": 0.5,
    "modalities": ["audio"],
    "history": true,
    "instructions": "Respond in a friendly tone",
    "return_transcription": false
  }
}

• <SDP_OFFER>: Generated by RTCPeerConnection.createOffer().

• <CANDIDATE_STRING>: ICE candidate string (e.g., "candidate:290599562 1 udp 2122260223 192.168.0.27 54070 typ host ...").

• <SDP_MID>, <INDEX>, <UFRAG>: Metadata from ICE candidates.

• Response:

{
  "answer": {
    "sdp": "<REMOTE_SDP>",
    "type": "answer"
  }
}

• Set the answer.sdp as the remote description using RTCPeerConnection.setRemoteDescription.

• Errors:

  • 400 Bad Request: Invalid SDP or missing parameters.

  • 401 Unauthorized: Invalid or expired ephemeral token.

WebRTC Environments

• Browser: Use Chrome/Firefox with native WebRTC APIs.

• Node.js: Use wrtc (npm install wrtc).

• Python: Use aiortc (pip install aiortc).

• Other: Use libraries like libwebrtc (C++).

Tips for Success

• Secure Credentials: Store API keys and tokens in environment variables to prevent exposure.

• Token Expiry: Refresh the ephemeral token if a 401 error occurs (tokens are short-lived).

• Error Handling: Check HTTP status codes (401, 429) and response bodies. Implement retry logic for 429.

• WebRTC Troubleshooting: Verify SDP and ICE candidates are correct. Check network/firewall (ports 3478, 5349, 80, 443). Use browser developer tools for RTCPeerConnection debugging.

• Transcriptions: Set return_transcription: true to receive user and AI transcriptions.