AI Gateway API

Use AiServiceFactory to obtain the service API instance and to build request payloads: 

import com.oracle.occas.ags.AIGatewayServiceFactory;
import com.oracle.occas.ags.api.AIGatewayService;

AIGatewayServiceFactory factory = AIGatewayServiceFactory.getInstance();
AIGatewayService api = factory.createAIGatewayService();
The AI Gateway API supports the following operations:
  • Create an STT session: createSTTSession(CreateAISessionRequest req)

    Returns the session ID, UDP port, egress IP, and session state.

  • Update an STT session: updateSTTSession(String id, ModifyAISessionRequest req)
  • Delete an STT session: deleteSTTSesssion(String id)
  • Get WebSocket URL: getWebSocketUrl(String callId, String participantId)

Get or create a WebSocket URL

getWebSocketUrl(String callId, String participantId)

Sets up the result stream — the channel over which AGS sends transcription results back to your app. Returns a wss:// URL scoped to that specific call and participant. If a WebSocket already exists for that combination it returns the existing one, otherwise creates a new one. After calling getWebSocketUrl, pass the result as the externalEndpoint parameter when you call createSTTSession.

Building a Create Request

createSTTSession(CreateAISessionRequest req)

Provisions a new STT session on the IAC. AGS selects the connector based on the provider field. Returns the session ID, session state, and AISessionDetails containing the udpPort and incomingMediaIP needed to route the RTP audio stream.

A typical create request includes:

  • callId – SIP Call-ID used to correlate the STT session with the originating call.
  • participantId – Identifier of the participant whose audio is being transcribed.
  • provider – The AI provider to route to (for example, oci).
  • headerSize – RTP/packet header size in bytes.
  • participantName – Human-readable display name for the participant.
  • externalEndpoint – WebSocket URL for result streaming. Obtain this from getWebSocketUrl() before building the request.

Use the AIGatewayServiceFactory builders to construct the request: 

String wsUrl = api.getWebSocketUrl(callId, participantId);

CreateAISessionRequest req = factory.createAISessionRequestBuilder()
    .callId(callId)
    .participantId(participantId)
    .participantName(participantName)
    .provider("oci")
    .headerSize(appConfig.getHeaderSize())
	.metaData(metaData)
    .build();

req.setExternalEndpoint(wsUrl);

AISessionResponse createResp = api.createSTTSession(req);

Table 18-13 Parameters for Create

Field Required Description
CallId Yes SIP Call-ID; used to correlate the STT session with the originating call.
participantId Yes Identifier of the participant whose audio stream is being transcribed.
provider Yes AI provider to route to. Supported values: oci, GCP.
externalEndpoint No WebSocket URL (wss://) for streaming transcription results back to the app. Obtain from getWebSocketUrl().
headerSize No RTP/packet header size in bytes. Typically 12 for standard RTP.
participantName No Human-readable display name for the participant.
metaData No Provider-specific configuration. See the Metadata Reference page. It needs to be a Map

Building a Modify Media Request 

updateSTTSession(String id, ModifyAISessionRequest req)

Modifies an existing session without tearing it down. Only the fields set on the request are applied — unset fields retain their current values. Typically used on re-INVITE when call parameters change mid-call.

A typical modify request includes the fields to update. Only fields that are set are applied — unset fields retain their current values. 

ModifyAISessionRequest modReq = factory.modifyAISessionRequestBuilder()
    .headerSize(146)
    .metaData(metaDataUpdate)
    .build();

AISessionResponse modResp = api.updateSTTSession(sessionId, modReq);

Table 18-14 Parameters for Modify

Field Required Description
provider No Switch to a different AI provider.
headerSize No Update the RTP/packet header size in bytes.
metaData No Replace provider-specific configuration. See the Metadata Reference page.

Building a Delete Request

deleteSTTSession(String id)

Tears down the session and releases all resources — the UDP receiver, STT connection, and WebSocket. The session ID is permanently invalid after this call. Always call this on BYE or any error path to avoid resource leaks on the AGS side.

A delete call requires only the session ID. There is no separate request object. 

AISessionResponse response = api.deleteSTTSession(sessionId);

Table 18-15 Parameters for Delete

Field Required Description
id Yes The session ID to delete. Obtained from a prior createSTTSession response. Once deleted, this ID is permanently invalid.

Updating Application State

createSTTSession, updateSTTSession, and deleteSTTSession all return an AISessionResponse. This response tells you:
  • The AI session identifier (getAiSessionId())
  • The current session state such as CREATED, INITIALIZING, ACTIVE, COMPLETING, ERROR, TERMINATED
  • The AISessionDetails which includes the udpPort and incomingMediaIP — the egress destination for the RTP audio stream

Always validate udpPort and incomingMediaIP from AISessionDetails before routing audio. If either is null, trigger cleanup and do not proceed.