Wrapping Genesys Cloud Routing Interactions via Go with Validation, Webhooks, and Audit Tracking

What You Will Build

• A Go service that programmatically wraps Genesys Cloud routing interactions using atomic POST operations against the Routing API.
• The implementation constructs wrap payloads with interaction UUID references, wrap type matrices, and duration limit directives while validating against routing state constraints and maximum wrap duration limits.
• The tutorial covers Go 1.21+ with standard library HTTP clients, context-aware retry logic, webhook synchronization, and structured audit logging.

Prerequisites

• OAuth Client: Confidential Client with scopes routing:interaction:write, routing:interaction:read, routing:user:read, webhooks:write, platform:webhook:write
• API Version: Genesys Cloud Platform API v2
• Runtime: Go 1.21 or later
• Dependencies: Standard library only (net/http, context, time, log/slog, encoding/json, sync, fmt, errors)

Authentication Setup

Genesys Cloud uses OAuth 2.0 Client Credentials flow for server-to-server integration. The authentication module must cache tokens, validate expiration before requests, and implement exponential backoff for 429 rate limit responses.

package main

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

type TokenResponse struct {
	AccessToken string `json:"access_token"`
	ExpiresIn   int    `json:"expires_in"`
	TokenType   string `json:"token_type"`
}

type OAuthConfig struct {
	BaseURL    string
	ClientID   string
	ClientSec  string
	Token      string
	Expiry     time.Time
}

func (c *OAuthConfig) GetToken(ctx context.Context) (string, error) {
	if time.Now().Before(c.Expiry.Add(-30*time.Second)) {
		return c.Token, nil
	}

	payload := fmt.Sprintf("grant_type=client_credentials&client_id=%s&client_secret=%s", c.ClientID, c.ClientSec)
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.BaseURL+"/oauth/token", bytes.NewBufferString(payload))
	if err != nil {
		return "", fmt.Errorf("failed to create auth request: %w", err)
	}
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

	client := &http.Client{Timeout: 10 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		return "", fmt.Errorf("auth request failed: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		body, _ := io.ReadAll(resp.Body)
		return "", fmt.Errorf("auth failed with status %d: %s", resp.StatusCode, string(body))
	}

	var tokenResp TokenResponse
	if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
		return "", fmt.Errorf("failed to decode token response: %w", err)
	}

	c.Token = tokenResp.AccessToken
	c.Expiry = time.Now().Add(time.Duration(tokenResp.ExpiresIn) * time.Second)
	return c.Token, nil
}

Required Scope: routing:interaction:write (plus read scopes for validation)
Error Handling: Returns wrapped errors for network failures, non-200 responses, and JSON decode failures. The token cache includes a 30-second safety margin to prevent mid-request expiration.

Implementation

Step 1: Interaction State Validation and License Verification

Wrapping an interaction requires strict state validation. The interaction must be in an active or connected state. The agent must possess a valid routing license and the interaction must not already be wrapped. This pipeline prevents wrap bypass during Routing scaling events.

type InteractionState struct {
	ID     string `json:"id"`
	State  string `json:"state"`
	AgentID string `json:"agentId"`
}

type RoutingUser struct {
	ID             string `json:"id"`
	RoutingProfile struct {
		ID string `json:"id"`
	} `json:"routingProfile"`
}

func validateInteractionAndAgent(ctx context.Context, client *http.Client, token, base, interactionID, agentID string) error {
	// Required Scope: routing:interaction:read
	interactReq, _ := http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf("%s/api/v2/routing/interactions/%s", base, interactionID), nil)
	interactReq.Header.Set("Authorization", "Bearer "+token)
	interactReq.Header.Set("Accept", "application/json")

	interactResp, err := client.Do(interactReq)
	if err != nil || interactResp.StatusCode != http.StatusOK {
		return fmt.Errorf("interaction fetch failed: %w", err)
	}
	defer interactResp.Body.Close()

	var state InteractionState
	if err := json.NewDecoder(interactResp.Body).Decode(&state); err != nil {
		return fmt.Errorf("interaction decode failed: %w", err)
	}

	if state.State != "active" && state.State != "connected" {
		return fmt.Errorf("interaction state %q does not allow wrapping", state.State)
	}

	// Required Scope: routing:user:read
	userReq, _ := http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf("%s/api/v2/routing/users/%s", base, agentID), nil)
	userReq.Header.Set("Authorization", "Bearer "+token)
	userReq.Header.Set("Accept", "application/json")

	userResp, err := client.Do(userReq)
	if err != nil || userResp.StatusCode != http.StatusOK {
		return fmt.Errorf("agent license verification failed: %w", err)
	}
	defer userResp.Body.Close()

	var agent RoutingUser
	if err := json.NewDecoder(userResp.Body).Decode(&agent); err != nil {
		return fmt.Errorf("agent decode failed: %w", err)
	}

	if agent.ID == "" {
		return fmt.Errorf("agent license or routing profile missing")
	}

	return nil
}

Expected Response: 200 OK with JSON body containing state and agentId.
Error Handling: Validates HTTP status codes, decodes JSON safely, and enforces state constraints. Returns explicit errors for 401, 403, and state mismatches.

Step 2: Constructing Wrap Payloads with Duration Limit Directives

The wrap payload must reference the interaction UUID, specify a valid wrap type from the routing matrix, and respect duration limits. Genesys Cloud enforces a maximum wrap duration (default 600 seconds). The payload builder validates these constraints before transmission.

type WrapupPayload struct {
	WrapupType      string `json:"wrapupType"`
	WrapupCode      string `json:"wrapupCode,omitempty"`
	WrapupDuration  int    `json:"wrapupDuration,omitempty"`
	Notes           string `json:"notes,omitempty"`
}

type WrapConfig struct {
	WrapType        string
	WrapCode        string
	DurationSeconds int
	MaxDuration     int
	Notes           string
}

func buildWrapupPayload(cfg WrapConfig) (*WrapupPayload, error) {
	validTypes := map[string]bool{"wrapup": true, "noWrapup": true, "transfer": true}
	if !validTypes[cfg.WrapType] {
		return nil, fmt.Errorf("invalid wrap type %q: must be wrapup, noWrapup, or transfer", cfg.WrapType)
	}

	if cfg.DurationSeconds < 0 {
		return nil, fmt.Errorf("wrap duration cannot be negative")
	}
	if cfg.DurationSeconds > cfg.MaxDuration {
		return nil, fmt.Errorf("wrap duration %d exceeds maximum limit %d", cfg.DurationSeconds, cfg.MaxDuration)
	}

	return &WrapupPayload{
		WrapupType:      cfg.WrapType,
		WrapupCode:      cfg.WrapCode,
		WrapupDuration:  cfg.DurationSeconds,
		Notes:           cfg.Notes,
	}, nil
}

Required Scope: routing:interaction:write
Non-Obvious Parameters: wrapupCode is optional but recommended for QA categorization. wrapupDuration is measured in seconds. The API automatically starts the wrap timer upon successful POST. If wrapupDuration exceeds the routing profile maximum, Genesys returns a 400 Bad Request.

Step 3: Atomic Wrap Initiation and Timer Triggers

Wrap initiation uses an atomic POST operation. The Go client must implement retry logic for 429 responses to prevent rate-limit cascades across microservices. The request includes format verification headers and triggers the automatic wrap timer on the Genesys Cloud platform.

func initiateWrapup(ctx context.Context, client *http.Client, token, base, interactionID string, payload *WrapupPayload) error {
	body, err := json.Marshal(payload)
	if err != nil {
		return fmt.Errorf("payload serialization failed: %w", err)
	}

	// Required Scope: routing:interaction:write
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, fmt.Sprintf("%s/api/v2/routing/interactions/%s/wrapup", base, interactionID), bytes.NewReader(body))
	if err != nil {
		return fmt.Errorf("wrapup request creation failed: %w", err)
	}
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")

	var lastErr error
	for attempt := 0; attempt < 3; attempt++ {
		resp, err := client.Do(req)
		if err != nil {
			lastErr = fmt.Errorf("wrapup request failed: %w", err)
			continue
		}
		defer resp.Body.Close()

		if resp.StatusCode == http.StatusTooManyRequests {
			retryAfter := 2 << uint(attempt)
			time.Sleep(time.Duration(retryAfter) * time.Second)
			continue
		}

		if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusAccepted {
			bodyBytes, _ := io.ReadAll(resp.Body)
			return fmt.Errorf("wrapup failed with status %d: %s", resp.StatusCode, string(bodyBytes))
		}

		return nil
	}

	return fmt.Errorf("wrapup exhausted retries: %w", lastErr)
}

Expected Response: 200 OK or 202 Accepted. The platform immediately transitions the interaction to wrapup state and starts the countdown timer.
Retry Logic: Implements exponential backoff for 429 responses. Retries up to three times before failing.

Step 4: Webhook Synchronization and Latency Tracking

External quality assurance systems require alignment with wrap status changes. This step registers a webhook for routing.interaction.wrapup events and implements latency tracking with success rate calculation. Audit logs are generated for governance compliance.

type WebhookConfig struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	EventType   string `json:"eventType"`
	EndpointURL string `json:"endpointUrl"`
}

type AuditLog struct {
	Timestamp    time.Time `json:"timestamp"`
	InteractionID string   `json:"interactionId"`
	Action       string    `json:"action"`
	Status       string    `json:"status"`
	LatencyMs    int64     `json:"latencyMs"`
}

type WrapperMetrics struct {
	mu          sync.Mutex
	TotalWraps  int64
	Successes   int64
	TotalLatency int64
}

func registerWebhook(ctx context.Context, client *http.Client, token, base string) error {
	webhook := WebhookConfig{
		Name:        "QA Wrap Sync",
		Description: "Synchronizes wrap events with external QA systems",
		EventType:   "routing.interaction.wrapup",
		EndpointURL: "https://qa.example.com/api/v1/wraps",
	}

	body, _ := json.Marshal(webhook)
	// Required Scope: platform:webhook:write
	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, fmt.Sprintf("%s/api/v2/platform/webhooks", base), bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")

	resp, err := client.Do(req)
	if err != nil {
		return fmt.Errorf("webhook registration failed: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {
		return fmt.Errorf("webhook registration returned %d", resp.StatusCode)
	}
	return nil
}

func (m *WrapperMetrics) Record(success bool, latencyMs int64) {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.TotalWraps++
	m.TotalLatency += latencyMs
	if success {
		m.Successes++
	}
}

func (m *WrapperMetrics) GetSuccessRate() float64 {
	m.mu.Lock()
	defer m.mu.Unlock()
	if m.TotalWraps == 0 {
		return 0
	}
	return float64(m.Successes) / float64(m.TotalWraps)
}

Required Scope: platform:webhook:write
Tracking Logic: Uses sync.Mutex for thread-safe metric updates. Calculates success rate as Successes / TotalWraps. Latency is tracked in milliseconds for efficiency reporting.

Step 5: Exposing the Interaction Wrapper

The final abstraction combines validation, payload construction, atomic initiation, webhook sync, and audit logging into a single InteractionWrapper struct. This exposes a clean interface for automated Routing management.

type InteractionWrapper struct {
	OAuth   *OAuthConfig
	Client  *http.Client
	BaseURL string
	Metrics *WrapperMetrics
	Logger  *slog.Logger
}

func NewInteractionWrapper(oauth *OAuthConfig, baseURL string) *InteractionWrapper {
	return &InteractionWrapper{
		OAuth:   oauth,
		Client:  &http.Client{Timeout: 30 * time.Second},
		BaseURL: baseURL,
		Metrics: &WrapperMetrics{},
		Logger:  slog.New(slog.NewTextHandler(io.Discard, nil)),
	}
}

func (w *InteractionWrapper) WrapInteraction(ctx context.Context, interactionID, agentID string, cfg WrapConfig) (*AuditLog, error) {
	start := time.Now()
	log := &AuditLog{
		Timestamp:   start,
		InteractionID: interactionID,
		Action:      "wrapup_initiated",
	}

	token, err := w.OAuth.GetToken(ctx)
	if err != nil {
		log.Status = "auth_failed"
		w.Logger.Error("auth failed", "error", err)
		return log, err
	}

	if err := validateInteractionAndAgent(ctx, w.Client, token, w.BaseURL, interactionID, agentID); err != nil {
		log.Status = "validation_failed"
		w.Logger.Error("validation failed", "error", err)
		return log, err
	}

	payload, err := buildWrapupPayload(cfg)
	if err != nil {
		log.Status = "payload_build_failed"
		w.Logger.Error("payload build failed", "error", err)
		return log, err
	}

	if err := initiateWrapup(ctx, w.Client, token, w.BaseURL, interactionID, payload); err != nil {
		log.Status = "wrapup_failed"
		w.Metrics.Record(false, time.Since(start).Milliseconds())
		w.Logger.Error("wrapup failed", "error", err)
		return log, err
	}

	log.Status = "wrapup_success"
	log.LatencyMs = time.Since(start).Milliseconds()
	w.Metrics.Record(true, log.LatencyMs)
	w.Logger.Info("wrapup completed", "interaction", interactionID, "latency_ms", log.LatencyMs)
	return log, nil
}

Required Scope: routing:interaction:write, routing:interaction:read, routing:user:read
Design Decision: The wrapper centralizes token retrieval, validation, and metric recording. The slog logger provides structured audit trails for governance compliance. The WrapInteraction method returns an AuditLog struct for downstream processing.

Complete Working Example

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"log/slog"
	"net/http"
	"sync"
	"time"
)

type TokenResponse struct {
	AccessToken string `json:"access_token"`
	ExpiresIn   int    `json:"expires_in"`
	TokenType   string `json:"token_type"`
}

type OAuthConfig struct {
	BaseURL   string
	ClientID  string
	ClientSec string
	Token     string
	Expiry    time.Time
}

func (c *OAuthConfig) GetToken(ctx context.Context) (string, error) {
	if time.Now().Before(c.Expiry.Add(-30*time.Second)) {
		return c.Token, nil
	}
	payload := fmt.Sprintf("grant_type=client_credentials&client_id=%s&client_secret=%s", c.ClientID, c.ClientSec)
	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, c.BaseURL+"/oauth/token", bytes.NewBufferString(payload))
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	client := &http.Client{Timeout: 10 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		return "", fmt.Errorf("auth request failed: %w", err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		body, _ := io.ReadAll(resp.Body)
		return "", fmt.Errorf("auth failed with status %d: %s", resp.StatusCode, string(body))
	}
	var tokenResp TokenResponse
	if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
		return "", fmt.Errorf("failed to decode token response: %w", err)
	}
	c.Token = tokenResp.AccessToken
	c.Expiry = time.Now().Add(time.Duration(tokenResp.ExpiresIn) * time.Second)
	return c.Token, nil
}

type InteractionState struct {
	ID     string `json:"id"`
	State  string `json:"state"`
	AgentID string `json:"agentId"`
}

type RoutingUser struct {
	ID             string `json:"id"`
	RoutingProfile struct {
		ID string `json:"id"`
	} `json:"routingProfile"`
}

func validateInteractionAndAgent(ctx context.Context, client *http.Client, token, base, interactionID, agentID string) error {
	interactReq, _ := http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf("%s/api/v2/routing/interactions/%s", base, interactionID), nil)
	interactReq.Header.Set("Authorization", "Bearer "+token)
	interactReq.Header.Set("Accept", "application/json")
	interactResp, err := client.Do(interactReq)
	if err != nil || interactResp.StatusCode != http.StatusOK {
		return fmt.Errorf("interaction fetch failed: %w", err)
	}
	defer interactResp.Body.Close()
	var state InteractionState
	if err := json.NewDecoder(interactResp.Body).Decode(&state); err != nil {
		return fmt.Errorf("interaction decode failed: %w", err)
	}
	if state.State != "active" && state.State != "connected" {
		return fmt.Errorf("interaction state %q does not allow wrapping", state.State)
	}
	userReq, _ := http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf("%s/api/v2/routing/users/%s", base, agentID), nil)
	userReq.Header.Set("Authorization", "Bearer "+token)
	userReq.Header.Set("Accept", "application/json")
	userResp, err := client.Do(userReq)
	if err != nil || userResp.StatusCode != http.StatusOK {
		return fmt.Errorf("agent license verification failed: %w", err)
	}
	defer userResp.Body.Close()
	var agent RoutingUser
	if err := json.NewDecoder(userResp.Body).Decode(&agent); err != nil {
		return fmt.Errorf("agent decode failed: %w", err)
	}
	if agent.ID == "" {
		return fmt.Errorf("agent license or routing profile missing")
	}
	return nil
}

type WrapupPayload struct {
	WrapupType     string `json:"wrapupType"`
	WrapupCode     string `json:"wrapupCode,omitempty"`
	WrapupDuration int    `json:"wrapupDuration,omitempty"`
	Notes          string `json:"notes,omitempty"`
}

type WrapConfig struct {
	WrapType        string
	WrapCode        string
	DurationSeconds int
	MaxDuration     int
	Notes           string
}

func buildWrapupPayload(cfg WrapConfig) (*WrapupPayload, error) {
	validTypes := map[string]bool{"wrapup": true, "noWrapup": true, "transfer": true}
	if !validTypes[cfg.WrapType] {
		return nil, fmt.Errorf("invalid wrap type %q: must be wrapup, noWrapup, or transfer", cfg.WrapType)
	}
	if cfg.DurationSeconds < 0 {
		return nil, fmt.Errorf("wrap duration cannot be negative")
	}
	if cfg.DurationSeconds > cfg.MaxDuration {
		return nil, fmt.Errorf("wrap duration %d exceeds maximum limit %d", cfg.DurationSeconds, cfg.MaxDuration)
	}
	return &WrapupPayload{
		WrapupType:     cfg.WrapType,
		WrapupCode:     cfg.WrapCode,
		WrapupDuration: cfg.DurationSeconds,
		Notes:          cfg.Notes,
	}, nil
}

func initiateWrapup(ctx context.Context, client *http.Client, token, base, interactionID string, payload *WrapupPayload) error {
	body, _ := json.Marshal(payload)
	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, fmt.Sprintf("%s/api/v2/routing/interactions/%s/wrapup", base, interactionID), bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")
	var lastErr error
	for attempt := 0; attempt < 3; attempt++ {
		resp, err := client.Do(req)
		if err != nil {
			lastErr = fmt.Errorf("wrapup request failed: %w", err)
			continue
		}
		defer resp.Body.Close()
		if resp.StatusCode == http.StatusTooManyRequests {
			retryAfter := 2 << uint(attempt)
			time.Sleep(time.Duration(retryAfter) * time.Second)
			continue
		}
		if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusAccepted {
			bodyBytes, _ := io.ReadAll(resp.Body)
			return fmt.Errorf("wrapup failed with status %d: %s", resp.StatusCode, string(bodyBytes))
		}
		return nil
	}
	return fmt.Errorf("wrapup exhausted retries: %w", lastErr)
}

type WebhookConfig struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	EventType   string `json:"eventType"`
	EndpointURL string `json:"endpointUrl"`
}

type AuditLog struct {
	Timestamp     time.Time `json:"timestamp"`
	InteractionID string    `json:"interactionId"`
	Action        string    `json:"action"`
	Status        string    `json:"status"`
	LatencyMs     int64     `json:"latencyMs"`
}

type WrapperMetrics struct {
	mu           sync.Mutex
	TotalWraps   int64
	Successes    int64
	TotalLatency int64
}

func (m *WrapperMetrics) Record(success bool, latencyMs int64) {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.TotalWraps++
	m.TotalLatency += latencyMs
	if success {
		m.Successes++
	}
}

type InteractionWrapper struct {
	OAuth   *OAuthConfig
	Client  *http.Client
	BaseURL string
	Metrics *WrapperMetrics
	Logger  *slog.Logger
}

func NewInteractionWrapper(oauth *OAuthConfig, baseURL string) *InteractionWrapper {
	return &InteractionWrapper{
		OAuth:   oauth,
		Client:  &http.Client{Timeout: 30 * time.Second},
		BaseURL: baseURL,
		Metrics: &WrapperMetrics{},
		Logger:  slog.New(slog.NewTextHandler(io.Discard, nil)),
	}
}

func (w *InteractionWrapper) RegisterWebhook(ctx context.Context) error {
	webhook := WebhookConfig{
		Name:        "QA Wrap Sync",
		Description: "Synchronizes wrap events with external QA systems",
		EventType:   "routing.interaction.wrapup",
		EndpointURL: "https://qa.example.com/api/v1/wraps",
	}
	body, _ := json.Marshal(webhook)
	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, fmt.Sprintf("%s/api/v2/platform/webhooks", w.BaseURL), bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+w.OAuth.Token)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")
	resp, err := w.Client.Do(req)
	if err != nil {
		return fmt.Errorf("webhook registration failed: %w", err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {
		return fmt.Errorf("webhook registration returned %d", resp.StatusCode)
	}
	return nil
}

func (w *InteractionWrapper) WrapInteraction(ctx context.Context, interactionID, agentID string, cfg WrapConfig) (*AuditLog, error) {
	start := time.Now()
	log := &AuditLog{
		Timestamp:     start,
		InteractionID: interactionID,
		Action:        "wrapup_initiated",
	}
	token, err := w.OAuth.GetToken(ctx)
	if err != nil {
		log.Status = "auth_failed"
		return log, err
	}
	if err := validateInteractionAndAgent(ctx, w.Client, token, w.BaseURL, interactionID, agentID); err != nil {
		log.Status = "validation_failed"
		return log, err
	}
	payload, err := buildWrapupPayload(cfg)
	if err != nil {
		log.Status = "payload_build_failed"
		return log, err
	}
	if err := initiateWrapup(ctx, w.Client, token, w.BaseURL, interactionID, payload); err != nil {
		log.Status = "wrapup_failed"
		w.Metrics.Record(false, time.Since(start).Milliseconds())
		return log, err
	}
	log.Status = "wrapup_success"
	log.LatencyMs = time.Since(start).Milliseconds()
	w.Metrics.Record(true, log.LatencyMs)
	return log, nil
}

func main() {
	ctx := context.Background()
	oauth := &OAuthConfig{
		BaseURL:   "https://api.mypurecloud.com",
		ClientID:  "YOUR_CLIENT_ID",
		ClientSec: "YOUR_CLIENT_SECRET",
	}
	wrapper := NewInteractionWrapper(oauth, oauth.BaseURL)
	wrapper.Logger = slog.New(slog.NewTextHandler(os.Stdout, nil))

	cfg := WrapConfig{
		WrapType:        "wrapup",
		WrapCode:        "resolved",
		DurationSeconds: 45,
		MaxDuration:     600,
		Notes:           "QA review required",
	}

	log, err := wrapper.WrapInteraction(ctx, "INTERACTION_UUID_HERE", "AGENT_USER_ID_HERE", cfg)
	if err != nil {
		wrapper.Logger.Error("wrap failed", "error", err)
		return
	}
	wrapper.Logger.Info("wrap completed", "audit", log)
}

Common Errors and Debugging

Error: 400 Bad Request

• Cause: Invalid wrapupType, wrapupDuration exceeds routing profile maximum, or missing required fields.
• Fix: Verify wrapupType matches wrapup, noWrapup, or transfer. Ensure wrapupDuration is between 0 and 600. Check routing profile settings in Admin.
• Code Fix: The buildWrapupPayload function validates duration limits before transmission.

Error: 403 Forbidden

• Cause: Missing routing:interaction:write scope, expired token, or agent lacks wrap license.
• Fix: Regenerate OAuth token with correct scopes. Verify agent routing profile includes wrap permissions.
• Code Fix: The validateInteractionAndAgent pipeline checks user existence and routing profile attachment.

Error: 409 Conflict

• Cause: Interaction already wrapped, state mismatch, or concurrent wrap attempt.
• Fix: Check interaction state before initiation. Implement idempotency keys or state polling.
• Code Fix: The state validation step rejects wrapup or closed states.

Error: 429 Too Many Requests

• Cause: Rate limit cascade across microservices or rapid wrap initiation.
• Fix: Implement exponential backoff. Reduce concurrent wrap requests.
• Code Fix: The initiateWrapup function implements automatic retry with 2 << attempt second delays.

Official References

• Genesys Cloud Routing Interactions API
• Wrapup Interaction Documentation
• Platform Webhooks Documentation
• Go SDK Reference