### Install Dependencies and Start Development Server

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/README.md

Install project dependencies and start the development server with hot-reloading. Access the site at http://localhost:3000.

```bash
yarn install
yarn start
```

--------------------------------

### Install Packages and Start Server

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/connect/docs/okta.md

These shell commands are used to install the project dependencies defined in package.json and then start the Node.js server.

```bash
npm install
npm start
```

--------------------------------

### Example GET Request

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/administration/docs/suite-common.mdx

Demonstrates a GET request to retrieve users, including necessary headers and query parameters.

```http
GET https://api.8x8.com/admin-provisioning/users?pageSize=10
x-api-key: your-api-key-here
Accept: application/vnd.users.v1+json
```

--------------------------------

### Setup and Run Virtual Environment

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/streaming/examples/python.mdx

Commands to create, activate, install dependencies within, and run the Python client inside a virtual environment. Includes deactivation.

```bash
# Create and activate
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Run client
python3 pulsar_simple_client.py --tenant YOUR_TENANT --x-api-key YOUR_KEY

# Deactivate when done
deactivate
```

--------------------------------

### Example GET Request

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/administration/docs/suite-common.mdx

An example of a GET request to the users endpoint, demonstrating the required headers and query parameters.

```APIDOC
## Example Request (GET)

### Endpoint
`GET https://api.8x8.com/admin-provisioning/users?pageSize=10`

### Headers
- `x-api-key`: your-api-key-here
- `Accept`: application/vnd.users.v1+json
```

--------------------------------

### Agent GUID Extraction Example

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/streaming/field-reference.mdx

Shows the internal agent GUID format and the extracted agentId. The agentId is derived by splitting the GUID and extracting the component starting with 'ag'. The full GUID is preserved in the agentGUID field.

```json
{
  "agentGUID": "tenant01-agAglVJkg0TU28dok9y9UQKg-e46672cd-660c-46f5-b8f0-856eaf18f65c",
  "agentId": "agAglVJkg0TU28dok9y9UQKg"
}
```

--------------------------------

### Employee Onboarding Workflow Example

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/administration/docs/user-management-api-guide.mdx

Demonstrates a complete workflow for automating employee onboarding using the User Management API. Includes examples for Python, Node.js, and cURL.

```python
from __future__ import annotations

import os
import sys
import uuid

from dotenv import load_dotenv

# Add the parent directory to the Python path
current_dir = os.path.dirname(os.path.abspath(__file__))
parent_dir = os.path.dirname(current_dir)
sys.path.append(parent_dir)

from api.users import UsersClient
from models.user import User, UserStatus

def main() -> None:
    """Main function to demonstrate user creation."""
    load_dotenv()

    # Ensure environment variables are set
    if not all([
        os.getenv("API_HOST"),
        os.getenv("API_KEY"),
        os.getenv("API_SECRET"),
    ]):
        print("Error: API_HOST, API_KEY, and API_SECRET must be set in the .env file.")
        sys.exit(1)

    client = UsersClient()

    # --- Create User --- 
    user_id = str(uuid.uuid4())
    user = User(
        userName=f"testuser.{user_id}",
        name=User.Name(
            first="Test",
            last="User",
        ),
        emails=[User.Email(address=f"testuser.{user_id}@example.com", type=User.Email.Type.BUSINESS)],
        status=UserStatus.ACTIVE,
        sites=[User.Site(id="YOUR_SITE_ID")],
        departments=["IT"],
        jobTitle="Developer",
    )

    try:
        print(f"\nCreating user: {user.userName}")
        operation = client.create_user(user)
        print(f"User creation initiated. Operation ID: {operation.id}")

        # --- Monitor Operation --- 
        print("\nMonitoring operation status...")
        completed_operation = client.wait_for_operation(operation.id)

        if completed_operation.status == "DONE":
            print("User creation successful!")
            # --- Get User --- 
            print(f"\nRetrieving user: {user.userName}")
            retrieved_user = client.get_user(user.userName)
            print(f"Retrieved user: {retrieved_user.userName}")
            print(f"User ID: {retrieved_user.id}")
            print(f"User Status: {retrieved_user.status}")

            # --- Update User --- 
            print(f"\nUpdating user: {retrieved_user.userName}")
            retrieved_user.status = UserStatus.INACTIVE
            update_operation = client.update_user(retrieved_user.userName, retrieved_user)
            print(f"User update initiated. Operation ID: {update_operation.id}")
            client.wait_for_operation(update_operation.id)
            print("User update successful!")

            # --- Delete User --- 
            print(f"\nDeleting user: {retrieved_user.userName}")
            delete_operation = client.delete_user(retrieved_user.userName)
            print(f"User deletion initiated. Operation ID: {delete_operation.id}")
            client.wait_for_operation(delete_operation.id)
            print("User deletion successful!")
        else:
            print(f"User creation failed. Status: {completed_operation.status}")
            print(f"Error: {completed_operation.error}")

    except Exception as e:
        print(f"An error occurred: {e}")


if __name__ == "__main__":
    main()

```

```javascript
import { UsersClient } from "@8x8/api-client";

const client = new UsersClient();

async function main() {
  // --- Create User ---
  const user = {
    userName: `testuser.${Date.now()}`,
    name: {
      first: "Test",
      last: "User",
    },
    emails: [
      {
        address: `testuser.${Date.now()}@example.com`,
        type: "BUSINESS",
      },
    ],
    status: "ACTIVE",
    sites: [{ id: "YOUR_SITE_ID" }],
    departments: ["IT"],
    jobTitle: "Developer",
  };

  try {
    console.log(`\nCreating user: ${user.userName}`);
    let operation = await client.createUser(user);
    console.log(`User creation initiated. Operation ID: ${operation.id}`);

    // --- Monitor Operation ---
    console.log("\nMonitoring operation status...");
    let completedOperation = await client.waitForOperation(operation.id);

    if (completedOperation.status === "DONE") {
      console.log("User creation successful!");

      // --- Get User ---
      console.log(`\nRetrieving user: ${user.userName}`);
      let retrievedUser = await client.getUser(user.userName);
      console.log(`Retrieved user: ${retrievedUser.userName}`);
      console.log(`User ID: ${retrievedUser.id}`);
      console.log(`User Status: ${retrievedUser.status}`);

      // --- Update User ---
      console.log(`\nUpdating user: ${retrievedUser.userName}`);
      retrievedUser.status = "INACTIVE";
      let updateOperation = await client.updateUser(retrievedUser.userName, retrievedUser);
      console.log(`User update initiated. Operation ID: ${updateOperation.id}`);
      await client.waitForOperation(updateOperation.id);
      console.log("User update successful!");

      // --- Delete User ---
      console.log(`\nDeleting user: ${retrievedUser.userName}`);
      let deleteOperation = await client.deleteUser(retrievedUser.userName);
      console.log(`User deletion initiated. Operation ID: ${deleteOperation.id}`);
      await client.waitForOperation(deleteOperation.id);
      console.log("User deletion successful!");
    } else {
      console.error(`User creation failed. Status: ${completedOperation.status}`);
      console.error(`Error: ${completedOperation.error}`);
    }
  } catch (error) {
    console.error("An error occurred:", error);
  }
}

main();

```

```bash
# Replace YOUR_API_KEY, YOUR_API_SECRET, YOUR_API_HOST, and YOUR_SITE_ID with your actual values.
# The user data is provided as a JSON payload.

API_KEY="YOUR_API_KEY"
API_SECRET="YOUR_API_SECRET"
API_HOST="YOUR_API_HOST"
SITE_ID="YOUR_SITE_ID"

USER_DATA=$(cat <<EOF
{
  "userName": "testuser.onboarding",
  "name": {
    "first": "Test",
    "last": "Onboarding"
  },
  "emails": [
    {
      "address": "testuser.onboarding@example.com",
      "type": "BUSINESS"
    }
  ],
  "status": "ACTIVE",
  "sites": [
    {
      "id": "$SITE_ID"
    }
  ],
  "departments": ["IT"],
  "jobTitle": "Developer"
}
EOF
)

# Create User
CREATE_RESPONSE=$(curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Secret: $API_SECRET" \
  -d "$USER_DATA" \
  "$API_HOST/users"
)

OPERATION_ID=$(echo $CREATE_RESPONSE | jq -r .id)

if [ "$OPERATION_ID" = "null" ]; then
  echo "Error creating user:"
  echo $CREATE_RESPONSE | jq .
  exit 1
fi

echo "User creation initiated. Operation ID: $OPERATION_ID"

# Monitor Operation (simplified - in a real scenario, you'd poll until DONE)
# For demonstration, we'll just show the initial response.
# You would typically use the /operations/{id} endpoint to check status.

# Example of how to check status (requires jq):
# STATUS_RESPONSE=$(curl -s -X GET \
#   -H "X-Api-Key: $API_KEY" \
#   -H "X-Api-Secret: $API_SECRET" \
#   "$API_HOST/operations/$OPERATION_ID"
# )
# echo "Operation Status: $(echo $STATUS_RESPONSE | jq -r .status)"

# In a real script, you would loop here checking the status until it's DONE.
# For this example, we assume success after initiation.

echo "User creation process started. Check the 8x8 Admin Console for status."

```

--------------------------------

### Initialize NodeJS App and Install Express

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/jaas/docs/tutorial-using-transcription-chunks.md

Prepares a new NodeJS application and installs the express framework, which is the only required dependency.

```bash
npm init -y

npm install express

```

--------------------------------

### Setup Directory and Fetch Templates

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/connect/docs/guide-creating-whatsapp-template-request.md

Ensures the output directory exists and fetches available templates. If no templates are found, it logs a message and exits.

```javascript
if (!fs.existsSync(OUTPUT_DIR)) {
  fs.mkdirSync(OUTPUT_DIR);
}

const templates = await fetchTemplates();
if (templates.length === 0) {
  console.log('No templates found.');
  return;
}

console.log(`Generating cURL scripts for ${templates.length} templates in ./${OUTPUT_DIR}/`);
```

--------------------------------

### Example Response for Get Queue Metrics

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/analytics/reference/get-queue-metrics.api.mdx

This example shows the structure of a successful response, including call queue details and their associated metrics.

```json
{
  "callQueues": [
    {
      "pbx": "voaroma-niaqe14051",
      "site": "SanJose-Onel",
      "id": "tqteLkZOScyi0Mai9ewUlA",
      "name": "CQ3 (autologin)",
      "extension": 1000,
      "metrics": {
        "ongoingAvgTalkingTime": 0,
        "averageTalkTime": 0,
        "ongoingEligibleAgents": 1,
        "ongoingTotalHandlingTime": 0,
        "ongoingTalkingTime": 0,
        "ongoingOnHoldTime": 0,
        "ongoingEnabledOverflowAgents": 1,
        "ongoingLoggedOutAndDndAgents": 1,
        "averageWaitingTime": 0,
        "forwardedToVoiceMail": 0,
        "ongoingTotalAgents": 1,
        "ongoingWrappingUpAgents": 0,
        "ongoingWaitingCalls": 0,
        "enteredCalls": 0,
        "ongoingOverflowAgents": 1,
        "activeCalls": 0,
        "ongoingLoggedOutAndDndOverflowAgents": 1,
        "transferredToCallQueue": 0,
        "totalWaitingTime": 0,
        "averageHandlingTime": 0,
        "ongoingLongestHandlingTime": 0,
        "ongoingTalkingCalls": 0,
        "ongoingEnabledPrimaryAgents": 0,
        "longestHandlingTime": 0,
        "transferredToExternalNumber": 0,
        "missedCalls": 0,
        "transferredToRingGroup": 0,
        "ongoingEligibleOverflowAgents": 1,
        "abandonedInWaitingCallsPercentage": 0,
        "ongoingOnHoldCalls": 0,
        "ongoingHandlingCalls": 0,
        "totalTalkTime": 0,
        "ongoingWaitingTime": 0,
        "ongoingTotalCalls": 0,
        "averageOnHoldTime": 0,
        "totalOnHoldTime": 0,
        "totalHandlingTime": 0,
        "completedCalls": 0,
        "diverted": 0,
        "divertedCallsPercentage": 0,
        "abandonedInWaitingCalls": 0,
        "missedCallsPercentage": 0,
        "ongoingOverflowWrappingUpAgents": 0,
        "ongoingEligiblePrimaryAgents": 0,
        "ongoingLongestTalkingTime": 0,
        "ongoingLongestWaitingTime": 0,
        "longestOnHoldTime": 0,
        "longestWaitingTime": 0,
        "longestTalkTime": 0,
        "ongoingPrimaryWrappingUpAgents": 0,
        "ongoingAvgWaitingTime": 0,
        "ongoingAvgHandlingTime": 0,
        "ongoingAvailableAgents": 0,
        "acceptedCalls": 0,
        "ongoingLongestOnHoldTime": 0
      }
    },
    {
      "pbx": "voaroma-niaqe14051",
      "site": "SanJose-Onel",
      "id": "ZPSyi0RkSiSISsNSuiYG7w",
      "name": "CQ4",
      "extension": 1013,
      "metrics": {
        "ongoingAvgTalkingTime": 0,
        "averageTalkTime": 0,
        "ongoingEligibleAgents": 1,
        "ongoingTotalHandlingTime": 0,
        "ongoingTalkingTime": 0,
        "ongoingOnHoldTime": 0,
        "ongoingEnabledOverflowAgents": 0,
        "ongoingLoggedOutAndDndAgents": 1,
        "averageWaitingTime": 0,
        "forwardedToVoiceMail": 0,
        "ongoingTotalAgents": 1,
        "ongoingWrappingUpAgents": 0,
        "ongoingWaitingCalls": 0,
        "enteredCalls": 0,
        "ongoingOverflowAgents": 1,
        "activeCalls": 0,
        "ongoingLoggedOutAndDndOverflowAgents": 1,
        "transferredToCallQueue": 0,
        "totalWaitingTime": 0,
        "averageHandlingTime": 0,
        "ongoingLongestHandlingTime": 0,
        "ongoingTalkingCalls": 0,
        "ongoingEnabledPrimaryAgents": 0,
        "longestHandlingTime": 0,
        "transferredToExternalNumber": 0,
        "missedCalls": 0,
        "transferredToRingGroup": 0,
        "diverted": 0,
        "divertedCallsPercentage": 0
      }
    }
  ]
}
```

--------------------------------

### Run Standalone Demo

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docusaurus/static/demos/maestro-sdk/README.md

Navigate to the demo directory and start the local server to run the standalone MaestroSDK demo. Access it via http://localhost:8080.

```bash
cd docusaurus/static/demos/maestro-sdk
npm run serve
# Open http://localhost:8080
```

--------------------------------

### Bulk User Creation Example

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/administration/docs/user-management-api-guide.mdx

Demonstrates how to create users in bulk using Python, Node.js, or cURL. Prepare user data, validate site IDs, and submit in batches for rapid deployment.

```python
from eight_by_eight_python_sdk.api.users import create_users
from eight_by_eight_python_sdk.models.users import UserCreateRequest

# Example: Bulk user creation
# See example_code/administration/users-api/usecase-bulk-create-users/users.json
# See example_code/administration/users-api/usecase-bulk-create-users/users.json
# See example_code/administration/users-api/usecase-bulk-create-users/users.json

# Create a list of UserCreateRequest objects
user_list = [
    UserCreateRequest(email="user1@example.com", first_name="John", last_name="Doe", site_id="site1"),
    UserCreateRequest(email="user2@example.com", first_name="Jane", last_name="Smith", site_id="site1")
]

# Submit the bulk creation request
response = create_users(user_list)

# Process the response (e.g., store operation IDs)
print(response)
```

```javascript
const { UsersApiClient } = require("8x8-typescript-sdk");

const client = new UsersApiClient({
  // ... client options
});

async function bulkCreateUsers() {
  const users = [
    { email: "user1@example.com", first_name: "John", last_name: "Doe", site_id: "site1" },
    { email: "user2@example.com", first_name: "Jane", last_name: "Smith", site_id: "site1" },
  ];

  try {
    const response = await client.bulkCreate(users);
    console.log("Bulk creation initiated:", response);
    // Store operation IDs for tracking
  } catch (error) {
    console.error("Error initiating bulk creation:", error);
  }
}

bulkCreateUsers();
```

```bash
# Example: Bulk user creation
# See example_code/administration/users-api/usecase-bulk-create-users/users.json

curl -X POST \
  https://api.8x8.com/users/v1/bulk \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d @users.json
```

--------------------------------

### Example WebSocket URL with Query Parameters

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/streaming/connection.md

This example shows how to construct a WebSocket URL for the Reader API, including authentication and specifying the starting message position.

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

--------------------------------

### Get Events Response Example

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/tech-partner/docs/partner-sdk-integration-guide.mdx

Example of the JSON response structure when querying for allowed events using `partnerSDK.system.getEvents()`. It shows event names and their supported schema versions.

```json
{
  "type": "response",
  "message": {
    "namespace": "system",
    "request": "getEvents",
    "value": {
      "aw-interaction-hold-v1": ["1.0.0"],
      "aw-interaction-mute-v1": ["1.0.0"],
      "aw-interaction-focus-v1": ["1.0.0"]
    }
  }
}
```

--------------------------------

### Get Interaction Transcription

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/analytics/reference/interaction-transcription.api.mdx

Retrieves available transcriptions for a specific interaction using its GUID.

```APIDOC
## Get Interaction Transcription

### Description
Retrieves available transcriptions for the selected interaction.

### Method
GET

### Endpoint
/interactions/{interactionGuid}/transcriptions

### Parameters
#### Path Parameters
- **interactionGuid** (string) - Required - The unique identifier of the interaction.
```

--------------------------------

### Get Flow Response Example

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/connect/docs/whatsapp/whatsapp-flows-api.md

Example JSON response when retrieving details of a specific Flow. This includes the Flow's ID, name, status, categories, validation errors, and the Flow JSON definition.

```json
{
  "id": "1234567890123456",
  "name": "Appointment Booking Flow",
  "status": "PUBLISHED",
  "categories": ["APPOINTMENT_BOOKING"],
  "validation_errors": [],
  "flowJson": "{\"version\":\"7.3\",\"screens\":[...]}"
}
```

--------------------------------

### Create Your First Ring Group

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/administration/docs/ring-group-management-api-guide.mdx

This example demonstrates the basic steps to create a ring group with essential properties. Ensure you have a valid Site ID.

```bash
curl -X POST https://api.8x8.com/admin-provisioning/v1/ring-groups \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d 
'{ 
  "name": "Sales Team Ring Group", 
  "extensionNumber": 8001, 
  "ringPattern": "ROUND_ROBIN", 
  "ringTimeout": 20, 
  "site": { 
    "id": "0012J00000NkZQIQA3" 
  } 
}'
```

--------------------------------

### Agent Statistics with Summary

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/analytics/docs/cc-realtime-statistics.md

Response example when the 'summary=true' parameter is used to get a summarized view of agent data.

```json
[
    {
        "id": "ag0IWAMsLuSsijCkitWX76Ng",
        "name": "Agent 1",
        "groupId": "735",
        "groupName": "Nicu Group"
    },
    {
        "id": "ag0OlQp4skQ5mOQsPvPRXDYw",
        "name": "Admin 1",
        "groupId": "100",
        "groupName": "ungroup"
    },
    {
        "id": "ag10000",
        "name": "Admin 2",
        "groupId": "131",
        "groupName": "adi_group"
    }
]
```

--------------------------------

### Running npm Start Script

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/streaming/examples/nodejs.mdx

Execute the npm start script, passing necessary arguments for tenant and API key.

```bash
npm start -- --tenant YOUR_TENANT --x-api-key YOUR_KEY
```

--------------------------------

### Get Next Available Weekday Start Time

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/connect/docs/tutorial-building-a-whatsapp-google-calendar-chat-bot.md

Calculates the start time for the next available weekday, considering current time and business hours (9 AM to 6 PM). It adjusts for weekends and times outside business hours.

```python
def get_next_weekday(now_singapore):
    # Check if it's a weekday and within the 9 AM to 6 PM time range
    if is_weekday(now_singapore) and now_singapore.hour < 9:
        # If today is a weekday and within the specified time range, use the current time
        start_singapore = now_singapore.replace(hour=9, minute=0, second=0, microsecond=0)
    elif is_weekday(now_singapore) and now_singapore.hour >=18:
        # Determine the number of days to add to get to the next weekday
        if now_singapore.weekday() in [0, 1, 2, 3]:
            next_weekday = now_singapore + datetime.timedelta(days=1)
        else:
            next_weekday = now_singapore + datetime.timedelta(days=3)

        # Set the start and end times for the next weekday
        start_singapore = next_weekday.replace(hour=9, minute=0, second=0, microsecond=0)
    elif is_weekday(now_singapore) and 9 <= now_singapore.hour < 18:
        #Pick the next timeslot at least an hour away
        next_weekday = now_singapore + datetime.timedelta(hours=1) #This needs to be one hour or the logic for retrieve events will break 
        start_singapore = next_weekday.replace(minute=0, second=0, microsecond=0)
    else:
        if now_singapore.weekday() == 5:
            next_weekday = now_singapore + datetime.timedelta(days=2)
        else:
            next_weekday = now_singapore + datetime.timedelta(days=1)
        start_singapore = next_weekday.replace(hour=9, minute=0, second=0, microsecond=0)
    return start_singapore
```

--------------------------------

### Start Node.js Service

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/connect/docs/okta-bring-your-own-telephony-byot-via-voice-otp.md

Use this command to start your backend server for the Okta integration.

```bash
npm start
```

--------------------------------

### Build and Serve Production Documentation

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/technical-notes/known-issues.md

Use these commands to build the production version of the documentation and serve it locally. This is the recommended way to test anchor link functionality as the issue does not occur in production builds.

```bash
yarn build
yarn serve
```

--------------------------------

### Regions Response Example

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/analytics/docs/cloud-storage-service-bulk-download.md

This JSON output represents the response from the Get Regions request, listing the available storage regions.

```json
[
    "us-east",
    "uk"
]
```

--------------------------------

### Add a New Validation Rule: Require Frontmatter

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/technical-notes/content-validation.md

Example of adding a new validation rule to ensure all documentation files start with frontmatter containing a title.

```javascript
{
  name: 'Must have title frontmatter',
  pattern: /^(?!---\ntitle:)/m,
  message: 'All documentation files must start with frontmatter containing a title.',
}
```

--------------------------------

### Installing and Running Globally

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/streaming/examples/nodejs.mdx

Install the client script globally using npm for access from any directory. This allows running the script directly by its name.

```bash
npm install -g .

# Run from anywhere
pulsar-simple-client --tenant YOUR_TENANT --x-api-key YOUR_KEY
```

--------------------------------

### Example Response for Get Recording Information

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/connect/docs/voice/number-masking/number-masking-call-recordings.md

This JSON response provides details about a call recording, including recordingId, sessionId, subAccountId, status, externalFileUrl, and startRecordingTime.

```json
{
    "recordings": [
        {
            "recordingId": "eef54fc2-065a-11ec-bce9-ed1000154345",
            "sessionId": "e35e3d0e-065a-11ec-b119-676cb2bc33ef",
            "subAccountId": "yourSubAccountId",
            "status": "CALLBACK_COMPLETED",
            "externalFileUrl": "https://yourRecordingsEndpoint.com/e35e3d0e-065a-11ec-b119-676cb2bc33ef/eef54fc2-065a-11ec-bce9-ed1000154345_2021-08-26T10%3A46%3A56.535Z.mp3",
            "startRecordingTime": "1969-12-31T23:59:59.999Z"
        }
    ],
    "statusCode": 0,
    "statusMessage": "ok"
}
```

--------------------------------

### Serve Production Build Locally

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/README.md

Serve the production build of the documentation site locally for testing.

```bash
yarn serve
```

--------------------------------

### HTTP Request: Check Address Usage

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/administration/docs/site-management-api-guide.mdx

Example HTTP GET request to retrieve details of an address, including its usage counts across different resources.

```http
GET /addresses/{addressId} HTTP/1.1
Host: api.8x8.com/admin-provisioning
x-api-key: your-api-key-here
Accept: application/vnd.addresses.v1+json
```

--------------------------------

### Quick Start: Start Campaign Action

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/technical-notes/specs/2026-04-22-cc-campaigns-api-docs-design.md

Send a PATCH request to start a campaign after it has been built. This command requires the campaign ID and appropriate authentication headers.

```curl
curl -X PATCH \
  'https://api.8x8.com/cc/{customer-site}/campaigns/v1/{campaignId}' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-8x8-Tenant: YOUR_TENANT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"action":"START"}'
```

--------------------------------

### Run Basic Python Client

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/streaming/examples/python.mdx

Execute the Python client script with essential tenant and API key arguments.

```bash
python3 pulsar_simple_client.py \
  --tenant YOUR_TENANT \
  --x-api-key YOUR_API_KEY
```

--------------------------------

### Combined Build and Start Campaign

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/cc-campaigns/endpoints/modify-campaign.md

Initiate a campaign build and start it simultaneously. This is useful for deploying and running a campaign in one step.

```bash
curl --request PATCH \
  'https://api.8x8.com/cc/US1/campaigns/v1/123e4567-e89b-12d3-a456-426614174000' \
  --header 'X-API-Key: eght_your_admin_console_key' \
  --header 'X-8x8-Tenant: my-tenant' \
  --header 'Content-Type: application/vnd.campaigns.v1+json' \
  --data '{"action":"START","buildOnStart":true}'
```

--------------------------------

### Complete Pulsar WebSocket Client Example in Go

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/streaming/examples/golang.md

This comprehensive example shows how to connect to Pulsar using WebSockets, receive messages, decode their payloads, and send acknowledgments. It includes necessary structs and helper functions for message handling and URL construction. Ensure you have the 'github.com/gorilla/websocket' package installed.

```Go
package main

import (
    "encoding/base64"
    "encoding/json"
    "flag"
    "fmt"
    "log"
    "net/http"
    "net/url"
    "time"

    "github.com/gorilla/websocket"
)

// PulsarMessage represents a message received from Pulsar WebSocket
type PulsarMessage struct {
    // Data message fields
    MessageID       string            `json:"messageId"`
    Payload         string            `json:"payload"` // Base64 encoded
    Properties      map[string]string `json:"properties,omitempty"`
    PublishTime     string            `json:"publishTime,omitempty"`
    RedeliveryCount int               `json:"redeliveryCount,omitempty"`
    // Control message fields
    Type       string `json:"type,omitempty"`       // e.g., "isEndOfTopic"
    EndOfTopic string `json:"endOfTopic,omitempty"` // "true" or "false"
}

// IsControlMessage returns true if this is a control message (should not be acknowledged)
func (m *PulsarMessage) IsControlMessage() bool {
    return m.Type != "" || m.EndOfTopic != ""
}

// DecodePayload decodes the base64 payload
func (m *PulsarMessage) DecodePayload() ([]byte, error) {
    return base64.StdEncoding.DecodeString(m.Payload)
}

// extractPulsarPayload parses a Pulsar message and extracts the decoded payload
func extractPulsarPayload(data []byte) (*PulsarMessage, []byte, error) {
    var msg PulsarMessage
    if err := json.Unmarshal(data, &msg); err != nil {
        return nil, nil, fmt.Errorf("failed to parse Pulsar message: %w", err)
    }

    payload, err := msg.DecodePayload()
    if err != nil {
        return &msg, nil, fmt.Errorf("failed to decode payload: %w", err)
    }

    return &msg, payload, nil
}

// sendAck sends an acknowledgment message for a received message
// This is REQUIRED for WebSocket readers to prevent backlog buildup and message delivery stoppage
func sendAck(conn *websocket.Conn, messageID string) error {
    ackMsg := map[string]string{"messageId": messageID}
    ackJSON, err := json.Marshal(ackMsg)
    if err != nil {
        return fmt.Errorf("failed to marshal ack message: %w", err)
    }

    err = conn.WriteMessage(websocket.TextMessage, ackJSON)
    if err != nil {
        return fmt.Errorf("failed to send ack: %w", err)
    }

    return nil
}

// buildURL constructs the Pulsar WebSocket URL
func buildURL(host string, port int, tenant, namespace, topic, xAPIKey string) (string, error) {
    baseURL := fmt.Sprintf("wss://%s:%d/ws/v2/reader/persistent/%s/%s/%s", host, port, tenant, namespace, topic)

    u, err := url.Parse(baseURL)
    if err != nil {
        return "", fmt.Errorf("invalid URL: %w", err)
    }

    // URL query parameter values MUST be URL-encoded. url.Values.Encode() handles
    // this for you -- do NOT build query strings with fmt.Sprintf/concatenation.
    // Pulsar message IDs in particular contain '+', '/' and '=' characters that
    // have special meaning in a URL and will silently break a naive query string.
    if xAPIKey != "" {
        q := u.Query()
        q.Set("x-api-key", xAPIKey)
        u.RawQuery = q.Encode()
    }

    return u.String(), nil
}

// ConnectAndReceive connects to a WebSocket URL and receives messages
func ConnectAndReceive(wsURL string, xAPIKey string) error {
    // Set up HTTP headers for authentication
    headers := http.Header{}

    // Add X-API-Key header if provided
    if xAPIKey != "" {
        headers.Set("X-API-Key", xAPIKey)
    }

    // Configure WebSocket dialer
    dialer := websocket.Dialer{
        HandshakeTimeout: 45 * time.Second,
    }

    // Connect to WebSocket
    log.Printf("Connecting to WebSocket...")
    conn, resp, err := dialer.Dial(wsURL, headers)
    if err != nil {
        if resp != nil {
            return fmt.Errorf("failed to connect to WebSocket (status: %d): %w", resp.StatusCode, err)
        }
        return fmt.Errorf("failed to connect to WebSocket: %w", err)
    }
    defer conn.Close()

    log.Printf("Successfully connected")

    // Read messages continuously
    for {
        messageType, message, err := conn.ReadMessage()
        if err != nil {
            log.Printf("Error reading message: %v", err)
            return err
        }

        switch messageType {
        case websocket.TextMessage, websocket.BinaryMessage:
            // Extract and decode Pulsar message payload
            pulsarMsg, payload, err := extractPulsarPayload(message)
            if err != nil {
                log.Printf("Error extracting payload: %v", err)
                continue
            }

            // Check if this is a control message (don't print or ack these)
            if pulsarMsg.IsControlMessage() {
                continue
            }

            // Print only the payload
            fmt.Println(string(payload))

            // Send acknowledgment (required for WebSocket flow control)
            if err := sendAck(conn, pulsarMsg.MessageID); err != nil {

```

--------------------------------

### Install websockets library (From requirements.txt)

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/streaming/examples/python.mdx

Installs the websockets library using a requirements.txt file, ensuring version compatibility.

```text
websockets>=12.0,<14.0
```

```bash
pip install -r requirements.txt
```

--------------------------------

### Complete Python Pulsar WebSocket Client Example

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/actions-events/docs/streaming/examples/python.mdx

This script implements a simplified WebSocket client for Apache Pulsar. It connects to a specified Pulsar endpoint, receives messages, decodes their payloads, prints the decoded content, and sends acknowledgments. Ensure you have the 'websockets' library installed (`pip install websockets`).

```python
#!/usr/bin/env python3
"""
Pulsar Simple Client - A simplified WebSocket client for Apache Pulsar
"""

import argparse
import asyncio
import base64
import json
import logging
import sys
import traceback
from urllib.parse import urlencode, urlparse

import websockets


class PulsarSimpleClient:
    """Simple WebSocket client for Apache Pulsar reader endpoints"""

    def __init__(self, host, port, tenant, namespace, topic, x_api_key=None):
        self.host = host
        self.port = port
        self.tenant = tenant
        self.namespace = namespace
        self.topic = topic
        self.x_api_key = x_api_key

    def build_url(self):
        """Build the Pulsar WebSocket URL"""
        base_url = f"wss://{self.host}:{self.port}/ws/v2/reader/persistent/{self.tenant}/{self.namespace}/{self.topic}"

        # URL query parameter values MUST be URL-encoded. urlencode() handles this
        # for you -- do NOT build query strings with f-strings/string concatenation.
        # Pulsar message IDs in particular contain '+', '/' and '=' characters that
        # have special meaning in a URL and will silently break a naive query string.
        if self.x_api_key:
            query_params = {"x-api-key": self.x_api_key}
            base_url = f"{base_url}?{urlencode(query_params)}"

        return base_url

    def get_headers(self):
        """Build HTTP headers for authentication"""
        headers = {}

        # Add X-API-Key header if provided
        if self.x_api_key:
            headers["X-API-Key"] = self.x_api_key

        return headers

    def is_control_message(self, msg):
        """Check if message is a control message (should not be acknowledged)"""
        return msg.get("type") or msg.get("endOfTopic")

    def extract_pulsar_payload(self, data):
        """Parse Pulsar message and extract decoded payload"""
        try:
            msg = json.loads(data)
            payload_b64 = msg.get("payload", "")

            # Decode base64 payload
            payload_bytes = base64.b64decode(payload_b64)
            payload = payload_bytes.decode("utf-8")

            return msg, payload
        except (json.JSONDecodeError, KeyError, base64.binascii.Error) as e:
            logging.error(f"Error extracting payload: {e}")
            return None, None

    async def send_ack(self, websocket, message_id):
        """
        Send an acknowledgment message for a received message.
        This is REQUIRED for WebSocket readers to prevent backlog buildup and message delivery stoppage.
        """
        try:
            ack_msg = {"messageId": message_id}
            await websocket.send(json.dumps(ack_msg))
        except Exception as e:
            logging.warning(f"Failed to send ack: {e}")

    async def connect_and_receive(self):
        """Connect to WebSocket and receive messages"""
        ws_url = self.build_url()
        headers = self.get_headers()

        logging.info(f"Connecting to {ws_url}...")

        try:
            async with websockets.connect(
                ws_url,
                extra_headers=headers,
                ssl=True,  # Use default SSL verification
                ping_interval=20,
                ping_timeout=10
            ) as websocket:
                logging.info("Successfully connected")

                # Read messages continuously
                async for message in websocket:
                    msg, payload = self.extract_pulsar_payload(message)
                    if msg and payload:
                        # Check if this is a control message (don't print or ack these)
                        if self.is_control_message(msg):
                            continue

                        # Print only the payload (suitable for piping)
                        print(payload, flush=True)

                        # Send acknowledgment (required for WebSocket flow control)
                        await self.send_ack(websocket, msg.get("messageId"))

        except websockets.exceptions.WebSocketException as e:
            logging.error(f"WebSocket error: {type(e).__name__}: {e}")
            logging.error(traceback.format_exc())
            sys.exit(1)
        except Exception as e:
            logging.error(f"Error: {type(e).__name__}: {e}")
            logging.error(traceback.format_exc())
            sys.exit(1)


def main():
    """Main entry point"""
    parser = argparse.ArgumentParser(
        description="Simplified WebSocket client for Apache Pulsar"
    )

    # Connection parameters
    # Example uses euw2 region. For other regions, see developer.8x8.com
    parser.add_argument(
        "--host",
        default="pulsar-ws-euw2.8x8.com",
        help="Pulsar broker hostname (default: pulsar-ws-euw2.8x8.com)"
    )
    parser.add_argument(
        "--port",
        type=int,
        default=443,
        help="Pulsar broker port (default: 443)"
    )
    parser.add_argument(
        "--tenant",
        required=True,

```

--------------------------------

### Get Workflow Instance Status

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/connect/reference/get-instance-status.api.mdx

Fetches the status and details of a specific workflow instance by its ID. This includes the overall status, start and end times, and payload information.

```APIDOC
## GET /workflow-instances/{workflowInstanceId}

### Description
Retrieves the status and details of a specific workflow instance.

### Method
GET

### Endpoint
/workflow-instances/{workflowInstanceId}

### Parameters
#### Path Parameters
- **workflowInstanceId** (string) - Required - The unique identifier of the workflow instance.

### Response
#### Success Response (200)
- **workflowId** (string) - The ID of the workflow.
- **data** (object) - The data associated with the workflow instance.
  - **payload** (object) - The payload of the workflow instance.
  - **accountId** (string) - The account ID.
  - **subAccountId** (string) - The sub-account ID.
  - **triggeredAt** (string) - The timestamp when the workflow was triggered.
- **definitionId** (string) - The ID of the workflow definition.
- **version** (integer) - The version of the workflow definition.
- **status** (string) - The current status of the workflow instance (e.g., Running, Complete, Failed, Cancelled).
- **startedAt** (string) - The timestamp when the workflow instance started.
- **completedAt** (string) - The timestamp when the workflow instance completed.

### Response Example
```json
{
  "workflowId": "60dbe307fe55d99fc083db61",
  "data": {
    "payload": {
      "umid": "9e09ac86-bd74-5465-851d-1eb5a5fdbb9a",
      "user": {
        "channelUserId": "test_user_id",
        "name": "test_user_name"
      },
      "content": {
        "text": "Hello, world!"
      }
    },
    "accountId": "test_account_id",
    "subAccountId": "test_subaccount_id",
    "triggeredAt": "2021-06-30T03:20:39.3857479Z"
  },
  "definitionId": "5870442f-3ddd-4657-b74c-6e17308f5230",
  "version": 1,
  "status": "Complete",
  "startedAt": "2021-06-30T03:20:39.49Z",
  "completedAt": "2021-06-30T03:21:25.83Z"
}
```

#### Error Response (400)
- **code** (integer) - Error code.
- **message** (string) - Description of the error.
- **errorId** (string) - Unique error id.
- **timestamp** (string) - Timestamp when the error occurred.

#### Error Response Example (400)
```json
{
  "code": 1000,
  "message": "Invalid definition id.",
  "errorId": "2558ff83-c8db-4890-805e-ad64001857a1",
  "timestamp": "2021-07-13T01:28:37.66Z"
}
```

#### Error Response (404)
- **code** (integer) - Error code.
- **message** (string) - Description of the error.
- **errorId** (string) - Unique error id.
- **timestamp** (string) - Timestamp when the error occurred.

#### Error Response Example (404)
```json
{
  "code": 1300,
  "message": "Definition 2aa9465e-dec7-4c3e-8fa6-bd168af9eaca not found.",
  "errorId": "2558ff83-c8db-4890-805e-ad64001857a1",
  "timestamp": "2021-07-13T01:28:37.66Z"
}
```
```

--------------------------------

### Install Partner SDK via npm

Source: https://github.com/8x8cloud/public-developer-docs/blob/master/docs/tech-partner/docs/partner-sdk-integration-guide.mdx

Install the SDK using npm or yarn. This is optional, but required for communication features.

```bash
npm install @8x8/pui-partner-comm
# or
yarn add @8x8/pui-partner-comm
```