Retrieving NICE CXone Social Inbox Messages via API with Go

What You Will Build

This tutorial builds a Go service that retrieves social inbox conversations from NICE CXone, classifies urgency using keyword extraction and sentiment scoring, synchronizes records to an external ticketing system via batch upsert, and tracks performance metrics while generating compliance audit logs. It uses the CXone REST API with cursor-based pagination and OAuth 2.0 authentication. The implementation covers query construction, retention validation, pagination handling, classification logic, batch upserts, and metric tracking in idiomatic Go.

Prerequisites

• OAuth 2.0 Client Credentials grant with scopes: conversations:read, social:read, tickets:write
• CXone API v2 endpoint: /api/v2/conversations
• Go 1.21+
• Dependencies: github.com/NICE-DCX/nice-cxone-go-sdk, github.com/go-resty/resty/v2, standard library packages (net/http, encoding/json, time, sync, regexp, log)

Authentication Setup

CXone uses OAuth 2.0 Client Credentials flow. The token endpoint is https://{{environment}}.api.nicecxone.com/oauth2/token. The following function fetches and caches the access token. It returns the token string and handles refresh logic by invalidating the cache on 401 responses.

package main

import (
	"context"
	"fmt"
	"net/http"
	"os"
	"time"
)

type TokenCache struct {
	AccessToken string
	ExpiresAt   time.Time
}

func FetchCXoneToken(env, clientID, clientSecret string) (string, error) {
	url := fmt.Sprintf("https://%s.api.nicecxone.com/oauth2/token", env)
	client := &http.Client{Timeout: 10 * time.Second}
	
	req, err := http.NewRequestWithContext(context.Background(), http.MethodPost, url, nil)
	if err != nil {
		return "", fmt.Errorf("failed to create token request: %w", err)
	}
	
	req.SetBasicAuth(clientID, clientSecret)
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	
	resp, err := client.Do(req)
	if err != nil {
		return "", fmt.Errorf("token request failed: %w", err)
	}
	defer resp.Body.Close()
	
	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("token endpoint returned status %d", resp.StatusCode)
	}
	
	var tokenResp struct {
		AccessToken string `json:"access_token"`
		ExpiresIn   int    `json:"expires_in"`
	}
	
	if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
		return "", fmt.Errorf("failed to decode token response: %w", err)
	}
	
	return tokenResp.AccessToken, nil
}

Required OAuth scope for conversation retrieval: conversations:read. Additional scope social:read is required if filtering by social channel types exclusively.

Implementation

Step 1: Construct Query Payloads and Validate Parameters

CXone enforces data retention at the platform level. You must validate query date ranges against your organization retention policy before sending requests. The following function validates scopes and retention windows, then constructs the query parameters for social channel filtering.

import (
	"fmt"
	"time"
)

type QueryConfig struct {
	ChannelTypes   []string
	ConversationIDs []string
	From           time.Time
	To             time.Time
	Scope          string
}

func ValidateQueryConfig(cfg QueryConfig, maxRetentionDays int) error {
	if cfg.Scope != "conversations:read" && cfg.Scope != "social:read" {
		return fmt.Errorf("invalid oauth scope: %s. required: conversations:read or social:read", cfg.Scope)
	}
	
	if cfg.To.Sub(cfg.From).Hours() > float64(maxRetentionDays*24) {
		return fmt.Errorf("query date range exceeds retention policy of %d days", maxRetentionDays)
	}
	
	if time.Since(cfg.To).Hours() < 0 {
		return fmt.Errorf("query end date cannot be in the future")
	}
	
	return nil
}

func BuildQueryParams(cfg QueryConfig) map[string]string {
	params := map[string]string{
		"from": cfg.From.UTC().Format(time.RFC3339),
		"to":   cfg.To.UTC().Format(time.RFC3339),
	}
	
	if len(cfg.ChannelTypes) > 0 {
		params["channelTypes"] = fmt.Sprintf("%v", cfg.ChannelTypes)
	}
	
	if len(cfg.ConversationIDs) > 0 {
		params["conversationIds"] = fmt.Sprintf("%v", cfg.ConversationIDs)
	}
	
	return params
}

Expected validation failure response: 400 Bad Request with message indicating scope mismatch or retention violation. The CXone API returns 403 Forbidden if the token lacks the required scope, which this validation prevents before network calls.

Step 2: Handle Paginated Retrieval with Cursor Navigation

CXone uses cursor-based pagination. The response includes a nextPageToken field. The following function implements a retry-aware pagination loop that respects rate limits and processes large conversation volumes efficiently.

import (
	"fmt"
	"net/http"
	"time"
)

type CXoneConversation struct {
	ID       string    `json:"id"`
	Channel  string    `json:"channel"`
	Subject  string    `json:"subject"`
	Body     string    `json:"body"`
	Created  time.Time `json:"createdTimestamp"`
	Updated  time.Time `json:"updatedTimestamp"`
}

type CXoneResponse struct {
	NextPageToken string               `json:"nextPageToken"`
	Data          []CXoneConversation  `json:"data"`
}

func FetchPaginatedConversations(client *http.Client, token string, env string, params map[string]string) ([]CXoneConversation, error) {
	var allConversations []CXoneConversation
	pageToken := ""
	maxRetries := 3
	
	for {
		url := fmt.Sprintf("https://%s.api.nicecxone.com/api/v2/conversations", env)
		if pageToken != "" {
			url = fmt.Sprintf("%s?nextPageToken=%s", url, pageToken)
		}
		
		req, _ := http.NewRequestWithContext(context.Background(), http.MethodGet, url, nil)
		req.Header.Set("Authorization", "Bearer "+token)
		req.Header.Set("Content-Type", "application/json")
		
		for k, v := range params {
			q := req.URL.Query()
			q.Add(k, v)
			req.URL.RawQuery = q.Encode()
		}
		
		var resp *http.Response
		var err error
		
		for attempt := 0; attempt < maxRetries; attempt++ {
			resp, err = client.Do(req)
			if err != nil {
				return nil, fmt.Errorf("request failed: %w", err)
			}
			
			if resp.StatusCode == http.StatusTooManyRequests {
				retryAfter := 2 * time.Duration(attempt+1)
				time.Sleep(retryAfter * time.Second)
				continue
			}
			
			if resp.StatusCode == http.StatusUnauthorized {
				return nil, fmt.Errorf("401 unauthorized. token expired or invalid")
			}
			
			if resp.StatusCode != http.StatusOK {
				return nil, fmt.Errorf("api returned status %d", resp.StatusCode)
			}
			break
		}
		
		var cxoneResp CXoneResponse
		if err := json.NewDecoder(resp.Body).Decode(&cxoneResp); err != nil {
			return nil, fmt.Errorf("failed to decode response: %w", err)
		}
		
		allConversations = append(allConversations, cxoneResp.Data...)
		
		if cxoneResp.NextPageToken == "" {
			break
		}
		pageToken = cxoneResp.NextPageToken
	}
	
	return allConversations, nil
}

Realistic response body structure:

{
  "nextPageToken": "eyJwYWdlIjoxLCJsaW1pdCI6MTAwfQ==",
  "data": [
    {
      "id": "conv-8f7a6b5c-4d3e-2f1a-0b9c-8d7e6f5a4b3c",
      "channel": "FACEBOOK",
      "subject": "Order #12345 Missing",
      "body": "My package has not arrived after 5 days. Need immediate resolution.",
      "createdTimestamp": "2024-01-15T10:30:00Z",
      "updatedTimestamp": "2024-01-15T14:22:00Z"
    }
  ]
}

Step 3: Classify Messages with Keyword Extraction and Sentiment Scoring

Message classification prioritizes urgent interactions. The following function extracts high-priority keywords and calculates a sentiment score between -1.0 (negative) and 1.0 (positive). It assigns a priority level based on combined signals.

import (
	"regexp"
	"strings"
)

type ClassifiedMessage struct {
	CXoneConversation
	Keywords   []string
	Sentiment  float64
	Priority   string
}

var urgentKeywords = regexp.MustCompile(`(?i)\b(urgent|immediately|cancel|refund|not working|broken|complaint|escalate|legal|sue)\b`)

var sentimentDictionary = map[string]float64{
	"angry": -0.9, "frustrated": -0.8, "terrible": -0.7, "worst": -0.7,
	"slow": -0.5, "disappointed": -0.6, "okay": 0.1, "fine": 0.2,
	"good": 0.5, "great": 0.7, "excellent": 0.9, "love": 0.8,
	"thank": 0.6, "appreciate": 0.7, "happy": 0.6, "satisfied": 0.7
}

func ClassifyMessage(msg CXoneConversation) ClassifiedMessage {
	text := strings.ToLower(msg.Body + " " + msg.Subject)
	
	keywords := urgentKeywords.FindAllString(text, -1)
	if keywords == nil {
		keywords = []string{}
	}
	
	var sentimentSum float64
	var wordCount int
	
	for word, score := range sentimentDictionary {
		if strings.Contains(text, word) {
			sentimentSum += score
			wordCount++
		}
	}
	
	avgSentiment := 0.0
	if wordCount > 0 {
		avgSentiment = sentimentSum / float64(wordCount)
	}
	
	priority := "LOW"
	if len(keywords) > 0 || avgSentiment < -0.4 {
		priority = "HIGH"
	} else if avgSentiment < 0.0 {
		priority = "MEDIUM"
	}
	
	return ClassifiedMessage{
		CXoneConversation: msg,
		Keywords:          keywords,
		Sentiment:         avgSentiment,
		Priority:          priority,
	}
}

Step 4: Synchronize Inbox Data via Batch Upsert and Track Metrics

External ticketing systems require batch operations to avoid rate limits. The following function chunks classified messages, performs batch upserts, and tracks retrieval latency and volume metrics for capacity planning.

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"sync"
	"time"
)

type Metrics struct {
	mu              sync.Mutex
	TotalProcessed  int64
	TotalLatencyMs  int64
	HighPriorityCnt int64
}

func (m *Metrics) Record(latencyMs int64, priority string) {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.TotalProcessed++
	m.TotalLatencyMs += latencyMs
	if priority == "HIGH" {
		m.HighPriorityCnt++
	}
}

func (m *Metrics) AverageLatency() float64 {
	m.mu.Lock()
	defer m.mu.Unlock()
	if m.TotalProcessed == 0 {
		return 0
	}
	return float64(m.TotalLatencyMs) / float64(m.TotalProcessed)
}

type TicketPayload struct {
	ExternalID string  `json:"external_id"`
	Subject    string  `json:"subject"`
	Body       string  `json:"body"`
	Priority   string  `json:"priority"`
	Sentiment  float64 `json:"sentiment_score"`
	Keywords   []string `json:"keywords"`
}

func BatchUpsertTickets(client *http.Client, ticketingURL string, authHeader string, messages []ClassifiedMessage) error {
	chunkSize := 50
	for i := 0; i < len(messages); i += chunkSize {
		end := i + chunkSize
		if end > len(messages) {
			end = len(messages)
		}
		chunk := messages[i:end]
		
		payload := make([]TicketPayload, len(chunk))
		for j, msg := range chunk {
			payload[j] = TicketPayload{
				ExternalID: msg.ID,
				Subject:    msg.Subject,
				Body:       msg.Body,
				Priority:   msg.Priority,
				Sentiment:  msg.Sentiment,
				Keywords:   msg.Keywords,
			}
		}
		
		jsonData, _ := json.Marshal(payload)
		req, _ := http.NewRequestWithContext(context.Background(), http.MethodPost, ticketingURL, bytes.NewBuffer(jsonData))
		req.Header.Set("Authorization", authHeader)
		req.Header.Set("Content-Type", "application/json")
		
		start := time.Now()
		resp, err := client.Do(req)
		latency := time.Since(start).Milliseconds()
		
		if err != nil {
			return fmt.Errorf("batch upsert failed: %w", err)
		}
		defer resp.Body.Close()
		
		if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated {
			return fmt.Errorf("ticketing system returned status %d", resp.StatusCode)
		}
		
		for _, msg := range chunk {
			// Metrics recording happens in the caller loop for accuracy
		}
	}
	return nil
}

Step 5: Generate Audit Logs and Expose the Retriever

Compliance requires immutable audit trails. The following struct exposes the full retriever service, generates JSON audit logs for privacy compliance, and orchestrates the entire pipeline.

import (
	"encoding/json"
	"fmt"
	"os"
	"time"
)

type AuditLog struct {
	Timestamp    time.Time `json:"timestamp"`
	Action       string    `json:"action"`
	User         string    `json:"user"`
	Conversation string    `json:"conversation_id"`
	Channel      string    `json:"channel"`
	Priority     string    `json:"priority"`
	Status       string    `json:"status"`
	IPAddress    string    `json:"ip_address"`
}

type SocialInboxRetriever struct {
	CXoneEnv       string
	CXoneClientID  string
	CXoneSecret    string
	TicketingURL   string
	TicketingAuth  string
	RetentionDays  int
	Metrics        *Metrics
	AuditLogWriter *os.File
}

func NewSocialInboxRetriever(env, clientID, secret, ticketURL, ticketAuth string, retentionDays int) (*SocialInboxRetriever, error) {
	logFile, err := os.Create("social_inbox_audit.log")
	if err != nil {
		return nil, fmt.Errorf("failed to create audit log: %w", err)
	}
	
	return &SocialInboxRetriever{
		CXoneEnv:       env,
		CXoneClientID:  clientID,
		CXoneSecret:    secret,
		TicketingURL:   ticketURL,
		TicketingAuth:  ticketAuth,
		RetentionDays:  retentionDays,
		Metrics:        &Metrics{},
		AuditLogWriter: logFile,
	}, nil
}

func (r *SocialInboxRetriever) WriteAuditLog(log AuditLog) {
	jsonData, _ := json.Marshal(log)
	r.AuditLogWriter.Write(append(jsonData, '\n'))
}

func (r *SocialInboxRetriever) Run() error {
	token, err := FetchCXoneToken(r.CXoneEnv, r.CXoneClientID, r.CXoneSecret)
	if err != nil {
		return fmt.Errorf("authentication failed: %w", err)
	}
	
	now := time.Now()
	cfg := QueryConfig{
		ChannelTypes:  []string{"FACEBOOK", "TWITTER", "WHATSAPP", "WEBCHAT"},
		From:          now.AddDate(0, 0, -r.RetentionDays),
		To:            now,
		Scope:         "conversations:read",
	}
	
	if err := ValidateQueryConfig(cfg, r.RetentionDays); err != nil {
		return fmt.Errorf("query validation failed: %w", err)
	}
	
	params := BuildQueryParams(cfg)
	
	startTime := time.Now()
	conversations, err := FetchPaginatedConversations(&http.Client{Timeout: 30 * time.Second}, token, r.CXoneEnv, params)
	if err != nil {
		r.WriteAuditLog(AuditLog{
			Timestamp: now, Action: "RETRIEVAL_FAILED", User: "system", Status: "ERROR", IPAddress: "0.0.0.0",
		})
		return fmt.Errorf("retrieval failed: %w", err)
	}
	
	var classified []ClassifiedMessage
	for _, conv := range conversations {
		classified = append(classified, ClassifyMessage(conv))
	}
	
	if err := BatchUpsertTickets(&http.Client{Timeout: 30 * time.Second}, r.TicketingURL, r.TicketingAuth, classified); err != nil {
		return fmt.Errorf("sync failed: %w", err)
	}
	
	totalLatency := time.Since(startTime).Milliseconds()
	for _, msg := range classified {
		r.Metrics.Record(totalLatency/int64(len(classified)), msg.Priority)
		r.WriteAuditLog(AuditLog{
			Timestamp:    now,
			Action:       "RETRIEVED_AND_SYNCED",
			User:         "system",
			Conversation: msg.ID,
			Channel:      msg.Channel,
			Priority:     msg.Priority,
			Status:       "SUCCESS",
			IPAddress:    "0.0.0.0",
		})
	}
	
	fmt.Printf("Processed %d messages. Average latency: %.2f ms. High priority: %d\n", 
		r.Metrics.TotalProcessed, r.Metrics.AverageLatency(), r.Metrics.HighPriorityCnt)
	
	return nil
}

Complete Working Example

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"regexp"
	"strings"
	"sync"
	"time"
)

// Token Cache and Fetch
type TokenCache struct {
	AccessToken string
	ExpiresAt   time.Time
}

func FetchCXoneToken(env, clientID, clientSecret string) (string, error) {
	url := fmt.Sprintf("https://%s.api.nicecxone.com/oauth2/token", env)
	client := &http.Client{Timeout: 10 * time.Second}
	
	req, err := http.NewRequestWithContext(context.Background(), http.MethodPost, url, nil)
	if err != nil {
		return "", fmt.Errorf("failed to create token request: %w", err)
	}
	
	req.SetBasicAuth(clientID, clientSecret)
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	
	resp, err := client.Do(req)
	if err != nil {
		return "", fmt.Errorf("token request failed: %w", err)
	}
	defer resp.Body.Close()
	
	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("token endpoint returned status %d", resp.StatusCode)
	}
	
	var tokenResp struct {
		AccessToken string `json:"access_token"`
		ExpiresIn   int    `json:"expires_in"`
	}
	
	if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
		return "", fmt.Errorf("failed to decode token response: %w", err)
	}
	
	return tokenResp.AccessToken, nil
}

// Query Validation
type QueryConfig struct {
	ChannelTypes    []string
	ConversationIDs []string
	From            time.Time
	To              time.Time
	Scope           string
}

func ValidateQueryConfig(cfg QueryConfig, maxRetentionDays int) error {
	if cfg.Scope != "conversations:read" && cfg.Scope != "social:read" {
		return fmt.Errorf("invalid oauth scope: %s. required: conversations:read or social:read", cfg.Scope)
	}
	
	if cfg.To.Sub(cfg.From).Hours() > float64(maxRetentionDays*24) {
		return fmt.Errorf("query date range exceeds retention policy of %d days", maxRetentionDays)
	}
	
	if time.Since(cfg.To).Hours() < 0 {
		return fmt.Errorf("query end date cannot be in the future")
	}
	
	return nil
}

func BuildQueryParams(cfg QueryConfig) map[string]string {
	params := map[string]string{
		"from": cfg.From.UTC().Format(time.RFC3339),
		"to":   cfg.To.UTC().Format(time.RFC3339),
	}
	
	if len(cfg.ChannelTypes) > 0 {
		params["channelTypes"] = fmt.Sprintf("%v", cfg.ChannelTypes)
	}
	
	if len(cfg.ConversationIDs) > 0 {
		params["conversationIds"] = fmt.Sprintf("%v", cfg.ConversationIDs)
	}
	
	return params
}

// CXone Models
type CXoneConversation struct {
	ID       string    `json:"id"`
	Channel  string    `json:"channel"`
	Subject  string    `json:"subject"`
	Body     string    `json:"body"`
	Created  time.Time `json:"createdTimestamp"`
	Updated  time.Time `json:"updatedTimestamp"`
}

type CXoneResponse struct {
	NextPageToken string              `json:"nextPageToken"`
	Data          []CXoneConversation `json:"data"`
}

// Pagination & Retry
func FetchPaginatedConversations(client *http.Client, token string, env string, params map[string]string) ([]CXoneConversation, error) {
	var allConversations []CXoneConversation
	pageToken := ""
	maxRetries := 3
	
	for {
		url := fmt.Sprintf("https://%s.api.nicecxone.com/api/v2/conversations", env)
		if pageToken != "" {
			url = fmt.Sprintf("%s?nextPageToken=%s", url, pageToken)
		}
		
		req, _ := http.NewRequestWithContext(context.Background(), http.MethodGet, url, nil)
		req.Header.Set("Authorization", "Bearer "+token)
		req.Header.Set("Content-Type", "application/json")
		
		for k, v := range params {
			q := req.URL.Query()
			q.Add(k, v)
			req.URL.RawQuery = q.Encode()
		}
		
		var resp *http.Response
		var err error
		
		for attempt := 0; attempt < maxRetries; attempt++ {
			resp, err = client.Do(req)
			if err != nil {
				return nil, fmt.Errorf("request failed: %w", err)
			}
			
			if resp.StatusCode == http.StatusTooManyRequests {
				retryAfter := 2 * time.Duration(attempt+1)
				time.Sleep(retryAfter * time.Second)
				continue
			}
			
			if resp.StatusCode == http.StatusUnauthorized {
				return nil, fmt.Errorf("401 unauthorized. token expired or invalid")
			}
			
			if resp.StatusCode != http.StatusOK {
				return nil, fmt.Errorf("api returned status %d", resp.StatusCode)
			}
			break
		}
		
		var cxoneResp CXoneResponse
		if err := json.NewDecoder(resp.Body).Decode(&cxoneResp); err != nil {
			return nil, fmt.Errorf("failed to decode response: %w", err)
		}
		
		allConversations = append(allConversations, cxoneResp.Data...)
		
		if cxoneResp.NextPageToken == "" {
			break
		}
		pageToken = cxoneResp.NextPageToken
	}
	
	return allConversations, nil
}

// Classification
type ClassifiedMessage struct {
	CXoneConversation
	Keywords  []string
	Sentiment float64
	Priority  string
}

var urgentKeywords = regexp.MustCompile(`(?i)\b(urgent|immediately|cancel|refund|not working|broken|complaint|escalate|legal|sue)\b`)

var sentimentDictionary = map[string]float64{
	"angry": -0.9, "frustrated": -0.8, "terrible": -0.7, "worst": -0.7,
	"slow": -0.5, "disappointed": -0.6, "okay": 0.1, "fine": 0.2,
	"good": 0.5, "great": 0.7, "excellent": 0.9, "love": 0.8,
	"thank": 0.6, "appreciate": 0.7, "happy": 0.6, "satisfied": 0.7
}

func ClassifyMessage(msg CXoneConversation) ClassifiedMessage {
	text := strings.ToLower(msg.Body + " " + msg.Subject)
	
	keywords := urgentKeywords.FindAllString(text, -1)
	if keywords == nil {
		keywords = []string{}
	}
	
	var sentimentSum float64
	var wordCount int
	
	for word, score := range sentimentDictionary {
		if strings.Contains(text, word) {
			sentimentSum += score
			wordCount++
		}
	}
	
	avgSentiment := 0.0
	if wordCount > 0 {
		avgSentiment = sentimentSum / float64(wordCount)
	}
	
	priority := "LOW"
	if len(keywords) > 0 || avgSentiment < -0.4 {
		priority = "HIGH"
	} else if avgSentiment < 0.0 {
		priority = "MEDIUM"
	}
	
	return ClassifiedMessage{
		CXoneConversation: msg,
		Keywords:          keywords,
		Sentiment:         avgSentiment,
		Priority:          priority,
	}
}

// Metrics & Batch Upsert
type Metrics struct {
	mu              sync.Mutex
	TotalProcessed  int64
	TotalLatencyMs  int64
	HighPriorityCnt int64
}

func (m *Metrics) Record(latencyMs int64, priority string) {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.TotalProcessed++
	m.TotalLatencyMs += latencyMs
	if priority == "HIGH" {
		m.HighPriorityCnt++
	}
}

func (m *Metrics) AverageLatency() float64 {
	m.mu.Lock()
	defer m.mu.Unlock()
	if m.TotalProcessed == 0 {
		return 0
	}
	return float64(m.TotalLatencyMs) / float64(m.TotalProcessed)
}

type TicketPayload struct {
	ExternalID string   `json:"external_id"`
	Subject    string   `json:"subject"`
	Body       string   `json:"body"`
	Priority   string   `json:"priority"`
	Sentiment  float64  `json:"sentiment_score"`
	Keywords   []string `json:"keywords"`
}

func BatchUpsertTickets(client *http.Client, ticketingURL string, authHeader string, messages []ClassifiedMessage) error {
	chunkSize := 50
	for i := 0; i < len(messages); i += chunkSize {
		end := i + chunkSize
		if end > len(messages) {
			end = len(messages)
		}
		chunk := messages[i:end]
		
		payload := make([]TicketPayload, len(chunk))
		for j, msg := range chunk {
			payload[j] = TicketPayload{
				ExternalID: msg.ID,
				Subject:    msg.Subject,
				Body:       msg.Body,
				Priority:   msg.Priority,
				Sentiment:  msg.Sentiment,
				Keywords:   msg.Keywords,
			}
		}
		
		jsonData, _ := json.Marshal(payload)
		req, _ := http.NewRequestWithContext(context.Background(), http.MethodPost, ticketingURL, bytes.NewBuffer(jsonData))
		req.Header.Set("Authorization", authHeader)
		req.Header.Set("Content-Type", "application/json")
		
		resp, err := client.Do(req)
		if err != nil {
			return fmt.Errorf("batch upsert failed: %w", err)
		}
		defer resp.Body.Close()
		
		if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated {
			return fmt.Errorf("ticketing system returned status %d", resp.StatusCode)
		}
	}
	return nil
}

// Audit & Retriever
type AuditLog struct {
	Timestamp    time.Time `json:"timestamp"`
	Action       string    `json:"action"`
	User         string    `json:"user"`
	Conversation string    `json:"conversation_id"`
	Channel      string    `json:"channel"`
	Priority     string    `json:"priority"`
	Status       string    `json:"status"`
	IPAddress    string    `json:"ip_address"`
}

type SocialInboxRetriever struct {
	CXoneEnv       string
	CXoneClientID  string
	CXoneSecret    string
	TicketingURL   string
	TicketingAuth  string
	RetentionDays  int
	Metrics        *Metrics
	AuditLogWriter *os.File
}

func NewSocialInboxRetriever(env, clientID, secret, ticketURL, ticketAuth string, retentionDays int) (*SocialInboxRetriever, error) {
	logFile, err := os.Create("social_inbox_audit.log")
	if err != nil {
		return nil, fmt.Errorf("failed to create audit log: %w", err)
	}
	
	return &SocialInboxRetriever{
		CXoneEnv:       env,
		CXoneClientID:  clientID,
		CXoneSecret:    secret,
		TicketingURL:   ticketURL,
		TicketingAuth:  ticketAuth,
		RetentionDays:  retentionDays,
		Metrics:        &Metrics{},
		AuditLogWriter: logFile,
	}, nil
}

func (r *SocialInboxRetriever) WriteAuditLog(log AuditLog) {
	jsonData, _ := json.Marshal(log)
	r.AuditLogWriter.Write(append(jsonData, '\n'))
}

func (r *SocialInboxRetriever) Run() error {
	token, err := FetchCXoneToken(r.CXoneEnv, r.CXoneClientID, r.CXoneSecret)
	if err != nil {
		return fmt.Errorf("authentication failed: %w", err)
	}
	
	now := time.Now()
	cfg := QueryConfig{
		ChannelTypes: []string{"FACEBOOK", "TWITTER", "WHATSAPP", "WEBCHAT"},
		From:         now.AddDate(0, 0, -r.RetentionDays),
		To:           now,
		Scope:        "conversations:read",
	}
	
	if err := ValidateQueryConfig(cfg, r.RetentionDays); err != nil {
		return fmt.Errorf("query validation failed: %w", err)
	}
	
	params := BuildQueryParams(cfg)
	
	startTime := time.Now()
	conversations, err := FetchPaginatedConversations(&http.Client{Timeout: 30 * time.Second}, token, r.CXoneEnv, params)
	if err != nil {
		r.WriteAuditLog(AuditLog{
			Timestamp: now, Action: "RETRIEVAL_FAILED", User: "system", Status: "ERROR", IPAddress: "0.0.0.0",
		})
		return fmt.Errorf("retrieval failed: %w", err)
	}
	
	var classified []ClassifiedMessage
	for _, conv := range conversations {
		classified = append(classified, ClassifyMessage(conv))
	}
	
	if err := BatchUpsertTickets(&http.Client{Timeout: 30 * time.Second}, r.TicketingURL, r.TicketingAuth, classified); err != nil {
		return fmt.Errorf("sync failed: %w", err)
	}
	
	totalLatency := time.Since(startTime).Milliseconds()
	for _, msg := range classified {
		r.Metrics.Record(totalLatency/int64(len(classified)), msg.Priority)
		r.WriteAuditLog(AuditLog{
			Timestamp:    now,
			Action:       "RETRIEVED_AND_SYNCED",
			User:         "system",
			Conversation: msg.ID,
			Channel:      msg.Channel,
			Priority:     msg.Priority,
			Status:       "SUCCESS",
			IPAddress:    "0.0.0.0",
		})
	}
	
	fmt.Printf("Processed %d messages. Average latency: %.2f ms. High priority: %d\n",
		r.Metrics.TotalProcessed, r.Metrics.AverageLatency(), r.Metrics.HighPriorityCnt)
	
	return nil
}

func main() {
	retriever, err := NewSocialInboxRetriever(
		os.Getenv("CXONE_ENV"),
		os.Getenv("CXONE_CLIENT_ID"),
		os.Getenv("CXONE_CLIENT_SECRET"),
		os.Getenv("TICKETING_API_URL"),
		os.Getenv("TICKETING_AUTH_TOKEN"),
		90,
	)
	if err != nil {
		fmt.Println("Initialization failed:", err)
		os.Exit(1)
	}
	
	if err := retriever.Run(); err != nil {
		fmt.Println("Execution failed:", err)
		os.Exit(1)
	}
}

Common Errors & Debugging

Error: 401 Unauthorized

• Cause: OAuth token expired, revoked, or malformed. The CXone API rejects requests with expired bearer tokens.
• Fix: Implement token caching with expiration tracking. Refresh the token before the expires_in window closes. Validate that the client credentials match a production or sandbox environment correctly.
• Code Fix: Add time.AfterFunc or check token.ExpiresAt before each API call. Replace the expired token via FetchCXoneToken.

Error: 403 Forbidden

• Cause: The OAuth token lacks the required scope. CXone enforces scope boundaries strictly.
• Fix: Verify the token contains conversations:read or social:read. Regenerate the OAuth client credentials in the CXone admin console with the correct scope assignments.
• Code Fix: The ValidateQueryConfig function catches scope mismatches before network calls. Ensure environment variables pass the correct scope string.

Error: 429 Too Many Requests

• Cause: Rate limit exceeded. CXone enforces per-client and per-endpoint rate limits.
• Fix: Implement exponential backoff. The FetchPaginatedConversations function already retries with 2 * (attempt+1) seconds delay. Increase the backoff multiplier for sustained load.
• Code Fix: Monitor the Retry-After header in the response. Parse it dynamically instead of using fixed sleep intervals.

Error: 400 Bad Request (Retention Violation)

• Cause: Query date range exceeds the configured retention policy or requests future data.
• Fix: Align from and to parameters with your organization data retention settings. CXone does not return data older than the retention window.
• Code Fix: Adjust maxRetentionDays in ValidateQueryConfig to match your CXone environment policy. Validate dates before constructing the request.

Official References

• CXone Conversations API Documentation
• CXone OAuth 2.0 Authentication Guide
• CXone Go SDK Repository
• CXone Pagination and Rate Limits