Connection Guide

Connect to the 8x8 Event Streaming service using WebSocket.

WebSocket URL Format

The WebSocket connection URL follows this structure:

wss://{host}/ws/v2/reader/persistent/{tenant}/{namespace}/{topic}

URL Components

Component	Description	Example
host	WebSocket proxy server hostname (see Regional Endpoints)	pulsar-ws-euw2.8x8.com
tenant	Your 8x8 tenant name	my-tenant
namespace	Pulsar namespace (typically event-v1)	event-v1
topic	Topic name (typically all for all events)	all

Example URL

wss://pulsar-ws-euw2.8x8.com/ws/v2/reader/persistent/my-tenant/event-v1/all

Regional Endpoints

The 8x8 Event Streaming service is available in multiple AWS regions. Connect to the endpoint that corresponds to your 8x8 Contact Center deployment region.

Find Your Endpoint

Your Contact Center cluster is the vcc-<cluster>.8x8.com host you see when accessing Configuration Manager. Select it below to get the WebSocket hostname for your region.

Your CC cluster:

Search for a cluster, e.g. EU4 or vcc-eu4

Available Regions

8x8 Region	CC Cluster	Hostname	Availability
UK3	EU4, EU5, EU6, EU7, EU8, EU9, EU10, EU11, EU12, EU13, EU14	pulsar-ws-euw2.8x8.com	Available
US1	NA1, NA2, NA3, NA4, NA5, NA6, NA11, NA12, NA13, NA14, NA15, NA16, SB1	pulsar-ws-use1.8x8.com	Available
US2	NA7, NA8, NA9, NA10, NA17, NA18, NA19, NA20, NA27, NA28, NA29, NA30, NA37, NA38, NA39	pulsar-ws-usw2.8x8.com	Available
HK1	AP1	N/A	Pending
HK2	AP21	N/A	Pending
LH1	EU21	N/A	Pending
ON1	BC1, BC2, BC3	N/A	Pending
PA1	EU31	N/A	Pending
SK1	CA1, CA2	N/A	Pending
SY1	AU1, AU2	N/A	Pending

📘 Finding Your Region

Your region is determined by your Contact Center deployment location. If you're unsure which region to use, contact 8x8 Support or check your Admin Console settings.

Note: Regions marked Pending are being deployed progressively and have no endpoint yet. This table will be updated as each region becomes available.

Using Regional Endpoints

Use the hostname from the table above for your region:

wss://pulsar-ws-euw2.8x8.com/ws/v2/reader/persistent/{tenant}/{namespace}/{topic}

Available Topics

The 8x8 Event Streaming service publishes events to multiple topics based on event type and agent. Subscribe to topics based on your requirements:

All Events Topic

Receive all events for your tenant:

persistent/{tenant}/event-v1/all

Use case: Monitoring all activity, building comprehensive dashboards, or logging all events.

Example:

wss://pulsar-ws-euw2.8x8.com/ws/v2/reader/persistent/my-tenant/event-v1/all

Event Type Topics

Receive only events of a specific type:

persistent/{tenant}/event-v1/{eventType}

Available event types include:

• InteractionCreated - New interactions
• InteractionQueued - Interactions waiting in queue
• InteractionAccepted - Agent accepted an interaction
• InteractionDeleted - Interaction completed or deleted
• AgentStatusChange - Agent status changes
• AgentProvChange - Agent provisioning changes
• See Event Reference for complete list

Use case: Applications that only need specific event types, reducing bandwidth and processing overhead.

Example:

wss://pulsar-ws-euw2.8x8.com/ws/v2/reader/persistent/my-tenant/event-v1/InteractionCreated

Agent-Specific Topics

Receive events for a specific agent:

persistent/{tenant}/agent-v1/{agentId}

Use case: Agent-specific dashboards, personal productivity tracking, or agent desktop integrations.

Example:

wss://pulsar-ws-euw2.8x8.com/ws/v2/reader/persistent/my-tenant/agent-v1/agAglVJkg0TU28dok9y9UQKg

Note: Agent IDs are in the format shown in events (e.g., agAglVJkg0TU28dok9y9UQKg), not the full GUID.

Topic Naming Convention

Topics follow a versioned namespace pattern (event-v1, agent-v1) to allow for future compatibility and changes without breaking existing integrations.

Reader vs Consumer API

The 8x8 Event Streaming service supports both Pulsar's Reader API and Consumer API via WebSocket. The examples in this documentation use the Reader API.

Reader API

The Reader API provides a lightweight interface for reading events:

• Simpler interface: No subscription management required
• No acknowledgements: Messages don't need to be acknowledged
• Position control: You specify where to start reading (earliest, latest, or specific message)
• No cursor tracking: Pulsar doesn't track your reading position
• Stateless: Each connection is independent

Ideal for:

• Event streaming and monitoring
• Building real-time dashboards
• Simple message consumption without delivery guarantees
• Development and debugging

WebSocket endpoint: /ws/v2/reader/persistent/{tenant}/{namespace}/{topic}

Consumer API

The Consumer API provides more advanced features for production applications:

• Subscription management: Durable subscriptions with cursor tracking
• Message acknowledgements: Confirm message processing
• Multiple subscription types: Exclusive, Shared, Failover, Key_Shared
• Load balancing: Distribute messages across multiple consumers
• Dead letter queues: Handle failed messages

Ideal for:

• Production applications requiring guaranteed delivery
• Load-balanced message processing
• Applications requiring message replay and acknowledgement

WebSocket endpoint: /ws/v2/consumer/persistent/{tenant}/{namespace}/{topic}/{subscription}

For more information, see:

• Apache Pulsar Reader documentation
• Apache Pulsar Consumer documentation

Query Parameters

You can append query parameters to the WebSocket URL to configure the reader:

Parameter	Description	Values	Default
x-api-key	API key for authentication	Your API key	-
messageId	Starting position for reading messages	earliest, latest, or message ID	latest
readerName	Optional identifier for this reader	Any string	-
receiverQueueSize	Size of the internal receiver queue	Integer > 0	1000

Example with Query Parameters

wss://pulsar-ws-euw2.8x8.com/ws/v2/reader/persistent/my-company/event-v1/all?x-api-key=YOUR_KEY&messageId=earliest

URL-encoding (important)

Query parameter values must be URL-encoded. Use your language's URL builder (urllib.parse.urlencode in Python, URLSearchParams in JavaScript, URLEncoder.encode in Java, url.Values.Encode() in Go) rather than building the query string with f-strings, template literals or string concatenation.

This matters most for messageId. A specific Pulsar message ID is a base64-ish string that frequently contains +, / and = — all of which have special meaning in a URL query string. The tutorial-style latest and earliest values won't trigger the bug, so it tends to surface only once your code starts using a real message ID returned by a previous message.

Bad — interpolating a raw messageId will silently break when it contains a +:

message_id = "CAEQAw+="   # value from a previous message
url = f"wss://{host}/ws/v2/reader/persistent/{tenant}/event-v1/all?messageId={message_id}"
# The server sees `messageId=CAEQAw =` (a literal space) and the read position is wrong.

Good — let the URL builder encode it:

from urllib.parse import urlencode

message_id = "CAEQAw+="
query = urlencode({"messageId": message_id, "receiverQueueSize": 200})
url = f"wss://{host}/ws/v2/reader/persistent/{tenant}/event-v1/all?{query}"
# messageId=CAEQAw%2B%3D — round-trips correctly.

Authentication

Authentication is provided via the X-API-Key HTTP header or x-api-key query parameter. See the Authentication Guide for complete details on credential types, obtaining keys, and implementation.

Message Reading Position

When you connect, you can specify where to start reading messages:

Latest (Default)

Start reading from the most recent message. You'll only receive new events that occur after your connection is established.

?messageId=latest

Earliest

Start reading from the beginning of the available message history.

?messageId=earliest

Specific Message ID

Start reading from a specific message (useful for resuming from a known position).

?messageId=CAEQAQ==

Connection Timeout

Configure an appropriate connection timeout (recommended: 45 seconds) to handle network latency and server processing time.

Keepalive and Heartbeat

WebSocket connections support ping/pong frames for keepalive:

• The server may send ping frames to check connection health
• Your client should respond with pong frames
• Most WebSocket libraries handle this automatically

Graceful Disconnection

To close the connection cleanly:

1. Stop reading messages
2. Send a WebSocket close frame
3. Wait for the server's close acknowledgement
4. Close the underlying TCP connection
5. Most WebSocket libraries handle this automatically

Next Steps

• Authentication Guide - Learn about authentication methods
• Message Format - Understand the message structure
• Code Examples - See complete working implementations