Audio in.
An answer back.

01 / START HERE

Your application owns the call.

Kooya Answer classifies the far-end opening audio as human, machine or unknown. Your dialer decides what to do next. The service does not originate calls or hang them up.

1. Register a client and source.Kooya provisions a scoped API key and a source configured for WAV, WSS, optional direct SRTP, WebRTC or SIP.
2. Send audio with call identity.Declare the source and provide a stable client reference. Isolate the callee or far-end track.
3. Receive the judgment.Use the HTTP response, WSS judgment message, LiveKit data message, configured HTTPS webhook or authenticated session polling.
4. Apply your call policy.Map human, machine and unknown to your own routing, disposition and agent workflow.

02 / CONNECTION METHODS

Choose the media path that fits.

Direct SRTP is an optional UDP media path. The client creates an authenticated session over HTTPS, supplies one SDES key line, then sends encrypted media to the returned UDP address. This implementation accepts AES_CM_128_HMAC_SHA1_80 and rejects plaintext, tampered and replayed packets before audio is counted. The public service keeps direct SRTP disabled until its deployment and network path are explicitly qualified. SIP signaling and its SRTP media remain a separate LiveKit integration. SDES keying specification ↗

03 / AUDIO FORMATS AND FRAMING

Send one isolated callee channel.

• PCMU and PCMA use 8 kHz mono. Direct G.722 decodes to 16 kHz mono PCM while its RTP clock runs at 8 kHz. RTP payload mappings are checked.
• For stereo source audio, select the left or right callee channel. Mixed agent and callee audio is not accepted as an isolated caller source.
• WebRTC sends negotiated Opus media through LiveKit; the media adapter decodes it before evaluation.
• Adapters normalize selected audio to mono PCM16 at 16 kHz and feed the detector in 20 ms frames: 320 samples / 640 bytes.
• Send raw audio chunks, not a WAV header, over WSS. Each binary message is bounded at 65,536 bytes; use 20 ms chunks where possible.
• The detector commits a judgment from at most the first 15 seconds of audio. Recording can continue after that decision until the transport ends.

04 / HTTP WAV EVALUATION

Upload audio and receive a session result.

Send source_id, callee_isolated=true, the optional client_reference, and the audio file as multipart form data. The source must be configured for WAV upload.

curl --fail-with-body \
  -H "Authorization: Bearer $AMD_API_KEY" \
  -H "Idempotency-Key: dialer-call-1842" \
  -F "source_id=$AMD_SOURCE_ID" \
  -F "callee_isolated=true" \
  -F "client_reference=dialer-call-1842" \
  -F "audio=@opening.wav;type=audio/wav" \
  https://api.amd.kooyaai.com/v1/evaluations

A completed evaluation returns session_id and result. If processing is still underway, the response is 202; use the returned session identifier with GET /v1/sessions/{session_id}. Reuse the same Idempotency-Key when retrying the same request.

05 / AUTHENTICATED WSS

Open a session, then stream audio.

Create a session with the configured WSS source. Include source_id, callee_isolated:true and a call reference. Every session admission requires an Idempotency-Key header: use one unique value per call and reuse that value only when retrying the same request. The response supplies session_id, the configured audio contract, and audio_websocket_path.

{
  "source_id": "YOUR_SOURCE_UUID",
  "callee_isolated": true,
  "client_reference": "dialer-call-1842"
}

Connect to wss://api.amd.kooyaai.com plus the returned path and send the same Bearer key in the WebSocket Authorization header. Send binary audio only, then send the exact control message {"type":"stop"} when the far-end stream ends.

The service sends {"type":"judgment","result":{...}} when the detector commits. The result is also pollable by session ID. Send stop or call the session end endpoint so full-session recording can finish; the 15-second detector decision does not stop recording.

06 / DIRECT SRTP · OPTIONAL

Encrypted UDP media with an HTTPS admission.

The service returns a UDP address only after it admits the source, validates the RTP contract and matches a ready media worker. Direct SRTP is disabled by default. Do not send production traffic until the deployment operator enables the dedicated ingress profile and confirms the public UDP route and carrier compatibility.

{
  "source_id": "YOUR_SOURCE_UUID",
  "callee_isolated": true,
  "client_reference": "dialer-call-1842",
  "rtp": {
    "remote_ip": "YOUR_PUBLIC_MEDIA_IP",
    "remote_port": 25000,
    "ssrc": 48151623,
    "payload_type": 0,
    "codec": "pcmu",
    "sample_rate": 8000,
    "channels": 1,
    "channel_selection": "mono",
    "srtp_crypto": "a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:<base64-30-byte-master-key-and-salt>"
  }
}

Send the key-bearing attribute only in the authenticated HTTPS JSON request. The API never returns or stores the key; it retains a one-way fingerprint and passes the key through its private non-persistent control queue to the media worker. The worker verifies SRTP authentication before RTP parsing, decoding or usage metering. UDP media is direct network traffic; HTTP, WebSocket and Nginx do not proxy it. Configure the caller's negotiated remote IP and source port in the request.

07 / WEBRTC AND SIP

Browser media and telephony have separate paths.

WebRTC signaling uses WSS on rtc.amd.kooyaai.com; WebRTC media uses its encrypted ICE/DTLS-SRTP path and TURN when required. When SIP is explicitly enabled, secure signaling uses TLS on sip.amd.kooyaai.com:5061 and SRTP media uses its own UDP RTP range. Plain SIP 5060 is never published. These media ports are direct network traffic, separate from the HTTPS API.

08 / JUDGMENT AND POLLING

Use the decision that was actually made.

“Machine” does not identify a precise voicemail-beep time or guarantee that a mailbox is ready to record. The result does not authorize hangup or other call control.

{
  "event_id": "EVENT_UUID",
  "event_type": "session.judgment",
  "session_id": "SESSION_UUID",
  "client_reference": "dialer-call-1842",
  "decision": "machine",
  "mapped_decision": "VOICEMAIL",
  "audio_analyzed_ms": 8240,
  "decision_audio_ms": 8240,
  "processing_wall_ms": 87,
  "received_audio_ms": 8240,
  "recorded_audio_ms": 8240,
  "detector_version": "KP02",
  "metadata": {}
}

Poll GET /v1/sessions/{session_id} or its returned status_url after a timeout or lost connection. End a live session with POST /v1/sessions/{session_id}/end; its response may remain 202 while recording finishes.

09 / WEBHOOKS AND CUSTOM BODY MAPPING

Your endpoint. Your JSON shape.

Configure an HTTPS webhook at the client or source level; a source-specific configuration overrides its client's configuration. Delivery is stored durably and sent after the judgment transaction commits. The stable event identifier is sent as X-AMD-Event-ID. Use custom body mapping to fit the result into your existing event contract.

{
  "call_id": "{{client_reference}}",
  "amd": {
    "status": "{{mapped_decision}}",
    "audio_ms": {{audio_analyzed_ms}}
  },
  "event_id": "{{event_id}}"
}

• Map supported event fields into JSON values with {{variable}} placeholders; whole-value placeholders retain their JSON type.
• Configure a decision map such as human → HUMAN, machine → VOICEMAIL and unknown → REVIEW.
• Add custom headers; secret references are encrypted and secret values are not returned by normal read APIs.
• Return a 2xx response after durably accepting the event. Retries may repeat a delivery, so deduplicate by event_id or X-AMD-Event-ID.
• Only public HTTPS destinations are accepted. Destination IPs are checked and DNS is revalidated for each delivery; redirects are not followed.

Webhook delivery is at least once. Configure your preferred body fields and names during onboarding, or use the session status endpoint as the recovery path.

10 / USAGE, RECORDINGS AND ONBOARDING

Meter audio, not tokens.

Usage tracking is enabled for measurement; automated customer billing is not enabled. Commercial options are pay-as-you-go usage and capacity planned around concurrency. Rates and qualified capacity are agreed during onboarding; no rate or 250+ concurrent-session result is promised on this page.

When recording is enabled, full session audio continues until the transport stops, even after the detector has committed its judgment. Private recordings are encrypted and retained without automatic expiration. See data handling.

11 / ERRORS AND RECOVERY

Transport errors are not judgments.

A disconnected stream, missing RTP packets or unavailable worker does not mean machine. Treat the result as unavailable until a judgment is committed; use the returned session ID and webhook event ID for recovery and deduplication.