anchorBefore you begin

Prepare a Webex Contact Center organization with a Full Admin who can authorize a Service App and an administrator who can edit, validate, and publish a flow. Implement a publicly reachable gRPC endpoint and secure it with TLS using a currently valid, publicly issued server certificate for the registered hostname. Optionally, add mutual TLS (mTLS) for transport-level client authentication. Require a client certificate and validate its issuer, validity window, and tenant-documented Webex CCAI identity. Do not use mTLS instead of runtime JSON Web Signature (JWS) validation.

Use the Media Forking sample code as a protocol reference, and adapt it to your processing and operational requirements. Its current Java validator retrieves keys before checking the issuer allowlist and tests every returned key; do not reuse that authentication path unchanged.

anchorImplement the gRPC endpoint

Webex Contact Center acts as the gRPC client. Your partner-hosted service acts as the server and implements this bidirectional streaming RPC:

service ConversationAudio {
  rpc StreamConversationAudio(stream ConversationAudioForkingRequest)
      returns (stream ConversationAudioForkingResponse);
}

For each request:

1. Read conversation_id and customer_org_id to associate the message with the correct conversation and customer organization.
2. Read audio.audio_data, audio.encoding, audio.sample_rate_hertz, and audio.audio_timestamp instead of assuming fixed audio properties.
3. Read audio.role and audio.role_id to identify the media leg.
4. Use (conversation_id, role, role_id) as the processing key so that individual media legs remain separate.
5. Make downstream writes idempotent or deduplicate re-established streams by conversation_id and role_id.
6. Use ConversationAudioForkingResponse.status_message and error_code for application status and processing errors. Terminate the RPC with an appropriate gRPC status for authentication, transport, or unrecoverable stream failures.
7. Complete the response stream after Webex completes its request stream and your endpoint finishes processing.

Media Forking sends variable-sized raw mono audio frames, not a WAV container, at 8 kHz or 16 kHz. The protobuf defines LINEAR16, MULAW, and ALAW. The canonical Java sample logs the encoding and can append raw audio bytes to files; it does not decode or transcode them. Decode or transcode the audio as required by your downstream processor. The sample sends one SUCCESS acknowledgment after Webex completes its request stream, so do not expect a response for every audio frame.

The sample's file capture is a development aid. Before storing call audio in production, apply access controls, retention limits, and encryption at rest.

Implement Check on the separate com.cisco.wcc.ccai.v1.Health service defined in the sample's health contract, exposed at /v1/ping under the service endpoint. Return SERVING while the media service is ready to receive streams and NOT_SERVING when it is not ready.

Important: The customer is responsible for keeping the receiving service healthy and able to receive and process streamed data. Webex Contact Center does not maintain back pressure. Keep the gRPC receive callback non-blocking; buffer briefly within fixed bounds or shed load explicitly. If the receiver cannot receive or process the stream, any resulting data loss is permanent and cannot be recovered.

anchorCreate and authorize a Service App

1. Create a Service App in Webex for Developers.
2. Select the Media Forking schema shown when you set up the Service App.
3. Enter a data exchange domain owned by the Service App owner that contains the gRPC endpoint. Do not include a port.
4. Request the spark-admin:datasource_read and spark-admin:datasource_write scopes.
5. Make the Service App visible to the target organization. Request admin authorization for the developer's own organization; for a non-affiliated customer organization, submit the app to Webex App Hub for review.
6. Ask a Full Admin of the customer organization to review and authorize the Service App in Control Hub.
7. Obtain the organization-specific Service App access and refresh tokens.
8. Store the app credentials and tokens securely.

Do not use a schema identifier copied from another integration. Use the Media Forking schema selected when you set up this integration.

anchorRegister the data source

Use the Data Sources API with the organization-specific Service App access token.

1. Register the endpoint for the customer organization.
2. Follow the current API request schema. In schemaId, supply the Media Forking schema selected for the Service App; also supply the endpoint URL, audience, subject, nonce, and a supported token lifetime.
3. Confirm that the endpoint URL satisfies the Service App's data exchange domain rule.
4. Record the returned data source identifier.
5. Before the current JWS token expires, update the registered data source with the complete required payload, including its current status and a new nonce. The configured token lifetime can be at most 1440 minutes (24 hours).

Use OAuth tokens only to manage the data source through the API. For each media RPC, extract the JWS from the gRPC authorization metadata and validate all of the following:

• The issuer against an allowlist of Webex issuers before retrieving verification keys.
• The RS256 algorithm and RSA signature, using the Cisco public key identified by the JWS header's kid from ${iss}/oauth2/v2/keys/verificationjwk/.
• The expiration time.
• The audience and subject claims against the values registered for the data source, and the presence of the JWT ID.
• The com.cisco.datasource.url claim against the registered endpoint URL.
• The com.cisco.datasource.schema.uuid claim against the selected Media Forking schema.
• For a multi-tenant endpoint, the signed com.cisco.org.uuid claim against the request's customer_org_id.

Reject a missing or invalid JWS with UNAUTHENTICATED. Keep JWS validation enabled even when you use mTLS.

anchorCreate the Media Forking configuration

1. In Control Hub, go to Contact Center > Integrations > Features.
2. Create a Media Forking configuration that selects the authorized Service App and registered data source.

anchorConfigure the flow

1. Open the target flow in Flow Designer.
2. Add the Media Forking activity to the agent-call flow at the point where media streaming should begin.
3. Select the Media Forking configuration in the activity.
4. Validate the flow.
5. Resolve any validation errors.
6. Publish the flow.
7. Map an entry point to the published flow unless an existing entry point already invokes it.

anchorVerify the integration

1. Confirm that the health Check RPC reports SERVING when the receiver is ready and NOT_SERVING when it is not ready.
2. Confirm that the endpoint rejects an audio RPC that does not contain a valid JWS.
3. Place a test call through the configured flow.
4. Have an agent answer the call.
5. Confirm that the Media Forking activity opens a stream to the registered endpoint.
6. Confirm receipt of messages for both CALLER and AGENT roles.
7. Verify that the endpoint preserves conversation and role identifiers.
8. Verify that the endpoint handles the declared encoding and sample rate.
9. End the call and confirm that both sides close the stream cleanly.
10. Check server logs for expired tokens, URL or schema claim mismatches, stream failures, and successful completion.