Skip to main content
This page describes the operating rules that keep an Uppzy M2M integration maintainable in production. Use it together with:

​
1. Key lifecycle

Treat API keys as production credentials. Recommended rules:
  • One key per environment
  • Prefer one key per integration when practical
  • Store only in secret managers or protected runtime configuration
  • Rotate on a schedule and after any suspected exposure
  • Revoke old keys after rollout confirmation
Avoid shared long-lived keys across unrelated services.

​
2. Configuration discipline

Keep these values explicit in environment configuration:
  • Base URL
  • API key
  • Tenant ID
  • Site ID
  • Timeout settings
  • Retry settings
Do not hardcode tenant or site identifiers in scattered application code. Put them in a clearly owned configuration layer.

​
3. HTTP client baseline

Every client should define:
  • Connection timeout
  • Read timeout
  • Sensible total request timeout
  • Retry policy limited to retryable failures
  • Structured error logging
For JSON requests, centralize:
  • Common headers
  • Error parsing
  • Non-2xx response handling
This avoids duplicate transport logic across chat, document, and monitoring flows.

​
4. Retry policy

Do not use one retry policy for every endpoint and error type. Recommended handling:
  • 400, 401, 403, 404: fix the request, config, or access problem; do not blind-retry
  • 429: retry with backoff and jitter
  • 5xx: bounded retries with backoff
  • network timeout or connect failure: bounded retries if the operation is idempotent or safely repeatable
For async chat polling, use a fixed short interval and an overall timeout budget.

​
5. Session design

Define your session_id strategy before the first production deployment. Good strategies are:
  • One session per visitor
  • One session per authenticated user
  • One session per business thread or ticket
  • One session per messaging channel identity
Your goal is continuity without creating never-ending idle sessions. Close sessions explicitly when the flow ends, especially in ticket-like or workflow-based applications.

​
6. Content rollout strategy

Do not bulk-load large amounts of content before you have validated answer quality. Recommended rollout:
  1. Start with a small approved document set
  2. Cover the highest-frequency support or sales questions first
  3. Add Q&A entries for direct repeated questions
  4. Expand only after chat quality is acceptable
Before pushing new content live:
  • Check that wording is current
  • Remove conflicting guidance
  • Separate public guidance from team-only notes
  • Verify that sensitive customer data is not present

​
7. Sync vs async usage

Use sync chat when the caller can wait and the user experience needs an immediate answer. Use async chat when:
  • You already have a queue or job architecture
  • The caller should not block on completion
  • You need stronger control over polling or orchestration
Do not mix sync and async usage randomly in the same user flow. Choose intentionally per use case.

​
8. Feedback collection

Feedback is one of the most valuable quality signals in production. Good practice:
  • Submit feedback only for completed responses
  • Keep the feedback decision close to the user interaction point
  • Store request_id with the surrounding business event so the rating can be tied back to the exact answer
If your product has its own rating UI, map it cleanly to Uppzy feedback values and avoid duplicate submissions.

​
9. Monitoring and observability

Track at minimum:
  • Request volume by endpoint
  • Success and failure rate by endpoint
  • P50, P95, and timeout trends
  • 429 frequency
  • 5xx frequency
  • Async completion latency
  • Feedback trend
Useful dimensions:
  • Environment
  • Integration name
  • Tenant ID
  • Site ID
Use alerts for sustained auth failures, retry storms, and sudden latency spikes.

​
10. Logging rules

Logs should help debug production issues without leaking credentials or unnecessary personal data. Recommended logging:
  • Request path
  • Tenant ID and site ID
  • Session ID
  • Request ID
  • Response status
  • Latency
  • Retry count
Do not log:
  • API keys
  • Full secret configuration
  • Raw document contents unless explicitly required for a controlled debug environment
If chat messages are logged for debugging, define a retention and access policy.

​
11. Change management

Before promoting integration changes to production:
  1. Run a staging smoke flow
  2. Validate auth
  3. Validate at least one document operation
  4. Validate sync chat
  5. Validate async chat if used
  6. Validate feedback submission if used
  7. Validate statistics read access
Keep a short changelog of:
  • Key rotations
  • Environment configuration changes
  • New document rollout batches
  • Endpoint behavior changes in your client

​
12. Incident handling

Prepare for these common incident classes:
  • Auth failures after rotation
  • Wrong tenant or site targeting
  • Empty or poor answer quality after document changes
  • Async polling never completing within the expected window
  • High 429 or 5xx rate
Your runbook should include:
  • Where credentials are stored
  • Who can rotate or revoke keys
  • How to run a connectivity test quickly
  • How to disable or pause upstream traffic if needed
  • How to confirm recovery

​
13. Production checklist

  • Correct key for the correct environment
  • Correct tenant ID and site ID
  • Stable session ID strategy
  • Small validated document set
  • Retries only on retryable failures
  • Async polling timeout defined
  • Feedback wiring reviewed
  • Endpoint metrics and alerts in place
  • Staging smoke test passed before production rollout