8x8 Contact Center Data Augmentation API

Overview

The Data Augmentation API allows you to enrich interaction data with custom variables collected from web forms, IVR systems, CRM data, or any external system. This enriched data serves two primary purposes:

🎯 Key Use Cases

1. Smart Routing: Use custom variables with the existing Test Variable node in IVR scripts to make intelligent routing decisions
2. Agent Context: Display valuable customer information in the Agent Workspace when offering interactions

Authentication

Method: HTTP Basic Authentication

• Username: Your tenant ID
• Password: Action Request Token (found in Configuration Manager → Integration → API Token)

Authorization: Basic {base64encode(tenantId:actionToken)}

Base URL

https://{cluster}.8x8.com/api/v1/interaction/data

API Endpoints

Set Interaction Variables

POST /api/v1/interaction/data/{identifier}

Add or update custom variables for a specific interaction.

Request Body

{
  "variables": [
    {
      "name": "_customerId",
      "value": "CUST-123456",
      "display": true,
      "displayName": "Customer ID"
    }
  ]
}

Variable Properties

Success Response (200 OK)

{
  "status": "success",
  "message": "Variables successfully set",
  "interactionId": "int-1628bb9dbf7-ABC123",
  "variablesSet": 3
}

Get Interaction Data

GET /api/v1/interaction/data/{identifier}

Retrieve all context data and variables for a specific interaction.

Success Response (200 OK)

{
  "interactionId": "int-1628bb9dbf7-ABC123",
  "channel": "18005551234",
  "createTime": "2024-01-15T10:30:00Z",
  "ani": "16175551234",
  "callerName": "John Doe",
  "variables": [
    {
      "name": "_customerId",
      "value": "CUST-123456",
      "display": true,
      "displayName": "Customer ID"
    }
  ]
}

Use Case 1: Smart Routing with Test Variable Node

Custom variables can be used with the existing Test Variable node in IVR scripts for intelligent routing decisions.

How It Works:

1. Set custom variables via API during the interaction
2. Use the Test Variable node in your IVR script
3. Test the variable against specific values
4. Route based on the result (True/False exit points)

Example: VIP Customer Routing

# Set VIP status via API
curl -X POST \
  'https://vcc-na12.8x8.com/api/v1/interaction/data/int-123456' \
  -H 'Authorization: Basic {credentials}' \
  -H 'Content-Type: application/json' \
  -d '{
    "variables": [
      {
        "name": "_customerTier",
        "value": "VIP",
        "ivr": true
      }
    ]
  }'

In IVR Script:

• Add Test Variable node
• Variable: _customerTier
• Test Condition: equals "VIP"
• True exit: Route to priority queue
• False exit: Route to standard queue

Example: Account Balance Routing

{
  "variables": [
    {
      "name": "_accountBalance",
      "value": "1250.75",
      "ivr": true,
      "dataType": "currency"
    },
    {
      "name": "_paymentDue",
      "value": "true",
      "ivr": true
    }
  ]
}

Test Variable Scenarios:

• Test _paymentDue equals "true" → Route to billing department
• Test _accountBalance less than "0" → Route to collections
• Test _accountBalance greater than "10000" → Route to VIP support

Use Case 2: Agent Context Display

Variables with display: true appear in the Agent Workspace, providing valuable customer context when interactions are offered.

Example: Customer Information Display

{
  "variables": [
    {
      "name": "_customerId",
      "value": "CUST-123456",
      "display": true,
      "displayName": "Customer ID"
    },
    {
      "name": "_membershipLevel",
      "value": "Gold",
      "display": true,
      "displayName": "Membership Level"
    },
    {
      "name": "_lastContactReason",
      "value": "Billing Inquiry",
      "display": true,
      "displayName": "Last Contact Reason"
    },
    {
      "name": "_accountBalance",
      "value": "$1,250.75",
      "display": true,
      "displayName": "Account Balance",
      "dataType": "currency"
    }
  ]
}

Agent Workspace Display:

┌─────────────────────────────────────┐
│ Customer Information                │
├─────────────────────────────────────┤
│ Customer ID: CUST-123456           │
│ Membership Level: Gold              │
│ Last Contact Reason: Billing Inquiry│
│ Account Balance: $1,250.75          │
└─────────────────────────────────────┘

Best Practices for Agent Display:

• Use clear, business-friendly displayName values
• Limit to 5-7 key variables to avoid information overload
• Use appropriate dataType for proper formatting
• Mark sensitive data with privacy: true

Complete Example: E-commerce Order Support

curl -X POST \
  'https://vcc-na12.8x8.com/api/v1/interaction/data/int-987654' \
  -H 'Authorization: Basic {credentials}' \
  -H 'Content-Type: application/json' \
  -d '{
    "variables": [
      {
        "name": "_orderStatus",
        "value": "shipped",
        "ivr": true,
        "display": true,
        "displayName": "Order Status"
      },
      {
        "name": "_orderValue",
        "value": "299.99",
        "display": true,
        "displayName": "Order Value",
        "dataType": "currency"
      },
      {
        "name": "_customerTier",
        "value": "Premium",
        "ivr": true,
        "display": true,
        "displayName": "Customer Tier"
      },
      {
        "name": "_shippingDate",
        "value": "2024-07-10",
        "display": true,
        "displayName": "Shipping Date",
        "dataType": "date"
      }
    ]
  }'

Routing Logic:

• Test _orderStatus equals "cancelled" → Route to order management
• Test _customerTier equals "Premium" → Route to priority support
• Test _orderValue greater than "500" → Route to specialized support

Agent Display:

• Order Status: shipped
• Order Value: $299.99
• Customer Tier: Premium
• Shipping Date: July 10, 2024

Error Responses

API Limits

Security & Best Practices

Security

• HTTPS Required: All requests must use HTTPS
• Privacy Protection: Use privacy: true for sensitive data
• Authentication: Secure your action tokens

Best Practices

• Variable Naming: Always start with underscore (_customerId)
• Data Types: Use appropriate dataType for formatting
• Agent Display: Limit to essential information for better UX
• Error Handling: Implement retry logic for 429/500 errors
• Testing: Use sandbox environment for development

Variable Naming Rules

✅ Good: _customerId, _accountBalance, _orderStatus
❌ Bad: customerId, account-balance, order status

Quick Reference

Common Variable Examples

{
  "variables": [
    {"name": "_customerId", "value": "CUST-123", "display": true, "displayName": "Customer ID"},
    {"name": "_accountBalance", "value": "1250.75", "display": true, "displayName": "Balance", "dataType": "currency"},
    {"name": "_membershipLevel", "value": "Gold", "ivr": true, "display": true, "displayName": "Membership"},
    {"name": "_lastContactDate", "value": "2024-07-10", "display": true, "displayName": "Last Contact", "dataType": "date"},
    {"name": "_accountPin", "value": "1234", "privacy": true, "ivr": true}
  ]
}

Test Variable Node Integration

1. Set variables via API with "ivr": true
2. In IVR script, add Test Variable node
3. Select your custom variable (e.g., _customerTier)
4. Set test condition (equals, greater than, etc.)
5. Connect True/False exits to appropriate routing logic

Support Resources

• 8x8 Developer Portal: https://developer.8x8.com
• Support Center: https://support.8x8.com
• Status Page: https://status.8x8.com
• Platform URL Guide: https://support.8x8.com/cloud-contact-center/8x8-contact-center/platform-cluster-url