M2M Code Samples

This page collects working patterns you can adapt for production integrations. Use these examples as templates, not as copy-paste production code without review. In production, add proper secret handling, retries, timeouts, and structured logging.

Shared environment variables

Use environment variables so the same examples can run in local, staging, and production environments.

export UPPZY_BASE_URL="https://api.uppzy.com/api/v1"
export UPPZY_API_KEY="<YOUR_API_KEY>"
export UPPZY_TENANT_ID="<YOUR_TENANT_ID>"
export UPPZY_SITE_ID="<YOUR_SITE_ID>"

1. Connectivity check with tenant limits

Start every new integration with a simple authenticated read call.

curl --silent --show-error \
  --request GET \
  --url "$UPPZY_BASE_URL/m2m/tenants/$UPPZY_TENANT_ID/limits" \
  --header "X-API-Key: $UPPZY_API_KEY"

Use this request to verify:

The API key is valid
The environment configuration is correct
Your deployment can reach the API

2. Upload a file document

Use file upload when you already have approved content in PDF, Word, or text format.

curl --silent --show-error \
  --request POST \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/documents" \
  --header "X-API-Key: $UPPZY_API_KEY" \
  --form "file=@./docs/return-policy.pdf"

If your integration tracks content versions, log the returned document identifier so you can activate, update, or audit it later.

3. Create a text document

Use text documents when your source content already exists as application-managed text.

curl --silent --show-error \
  --request POST \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/documents/text" \
  --header "X-API-Key: $UPPZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Support Hours",
    "content": "Support is available Monday to Friday between 09:00 and 18:00.",
    "category": "support"
  }'

4. Create a Q&A document

Use Q&A documents for short, deterministic answers to repeated questions.

curl --silent --show-error \
  --request POST \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/documents/qa" \
  --header "X-API-Key: $UPPZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Delivery FAQ",
    "question": "Do you offer same-day delivery?",
    "answer": "Availability depends on location and order timing.",
    "category": "faq"
  }'

5. Send a sync chat request

Use sync chat when the caller expects the answer in the same request cycle.

curl --silent --show-error \
  --request POST \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/chat" \
  --header "X-API-Key: $UPPZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "session_id": "web-user-1001",
    "email": "user@example.com",
    "message": "How does the return process work?",
    "ui_locale": "en",
    "response_language": "en"
  }'

Typical response shape:

{
  "session_id": "web-user-1001",
  "request_id": "req_abc123",
  "answer": "Returns are accepted within the published return window.",
  "confidence_score": 92,
  "confidence_level": "high"
}

6. Send an async chat request and poll for completion

Use async chat when you want non-blocking request handling.

REQUEST_ID=$(curl --silent --show-error \
  --request POST \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/chat/async" \
  --header "X-API-Key: $UPPZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "session_id": "job-user-2001",
    "message": "Can you summarize your refund policy?"
  }' | jq -r '.request_id')

curl --silent --show-error \
  --request GET \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/chat/requests/$REQUEST_ID" \
  --header "X-API-Key: $UPPZY_API_KEY"

Production polling guidance:

Poll on a fixed short interval such as 2-3 seconds
Stop when status becomes completed or failed
Apply an overall timeout so jobs do not poll forever

7. Submit feedback for a response

Use feedback to send a quality signal after a completed response. Accepted feedback values are good and bad.

curl --silent --show-error \
  --request POST \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/chat/feedback" \
  --header "X-API-Key: $UPPZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "session_id": "web-user-1001",
    "request_id": "req_abc123",
    "feedback": "good"
  }'

Send feedback only after the response is completed and only once per evaluation event in your application workflow.

8. Close a session explicitly

Close a session when the business flow is complete and you do not want the conversation to remain open indefinitely.

curl --silent --show-error \
  --request POST \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/chat/session/close" \
  --header "X-API-Key: $UPPZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "session_id": "web-user-1001"
  }'

9. Read site statistics

Use site statistics to monitor how your integration performs after rollout.

curl --silent --show-error \
  --request GET \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/statistics" \
  --header "X-API-Key: $UPPZY_API_KEY"

10. Read sessions

Use sessions when you need operational visibility into conversation activity.

curl --silent --show-error \
  --request GET \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/sessions" \
  --header "X-API-Key: $UPPZY_API_KEY"

11. Minimal JavaScript client

Use a shared helper for request headers, JSON parsing, and error handling.

const BASE_URL = process.env.UPPZY_BASE_URL || "https://api.uppzy.com/api/v1";
const API_KEY = process.env.UPPZY_API_KEY;

async function uppzy(path, { method = "GET", headers = {}, body } = {}) {
  const response = await fetch(`${BASE_URL}${path}`, {
    method,
    headers: {
      "X-API-Key": API_KEY,
      ...headers,
    },
    body,
  });

  const text = await response.text();
  const data = text ? JSON.parse(text) : null;

  if (!response.ok) {
    const error = new Error(`HTTP ${response.status}`);
    error.status = response.status;
    error.data = data;
    throw error;
  }

  return data;
}

export async function sendSyncChat(siteId, payload) {
  return uppzy(`/m2m/sites/${siteId}/chat`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
}

export async function sendAsyncChat(siteId, payload) {
  return uppzy(`/m2m/sites/${siteId}/chat/async`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
}

export async function getAsyncChatStatus(siteId, requestId) {
  return uppzy(`/m2m/sites/${siteId}/chat/requests/${requestId}`);
}

export async function submitChatFeedback(siteId, payload) {
  return uppzy(`/m2m/sites/${siteId}/chat/feedback`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
}

12. Async polling helper in JavaScript

export async function waitForChat(siteId, requestId, {
  intervalMs = 2500,
  timeoutMs = 30000,
} = {}) {
  const startedAt = Date.now();

  while (true) {
    const result = await getAsyncChatStatus(siteId, requestId);

    if (result.status === "completed") {
      return result;
    }

    if (result.status === "failed") {
      throw new Error(result.error || "Async chat failed");
    }

    if (Date.now() - startedAt > timeoutMs) {
      throw new Error("Async chat polling timed out");
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
}

13. Minimal Python client

import os
import time
import requests

BASE_URL = os.getenv("UPPZY_BASE_URL", "https://api.uppzy.com/api/v1")
API_KEY = os.environ["UPPZY_API_KEY"]


def uppzy(path: str, method: str = "GET", json_body=None, files=None, timeout: int = 30):
    response = requests.request(
        method,
        f"{BASE_URL}{path}",
        headers={"X-API-Key": API_KEY},
        json=json_body,
        files=files,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json() if response.text else None


def send_sync_chat(site_id: str, payload: dict):
    return uppzy(f"/m2m/sites/{site_id}/chat", method="POST", json_body=payload)


def send_async_chat(site_id: str, payload: dict):
    return uppzy(f"/m2m/sites/{site_id}/chat/async", method="POST", json_body=payload)


def get_async_status(site_id: str, request_id: str):
    return uppzy(f"/m2m/sites/{site_id}/chat/requests/{request_id}")


def wait_for_chat(site_id: str, request_id: str, interval_seconds: float = 2.5, timeout_seconds: int = 30):
    started = time.time()
    while True:
      result = get_async_status(site_id, request_id)
      if result["status"] == "completed":
          return result
      if result["status"] == "failed":
          raise RuntimeError(result.get("error") or "Async chat failed")
      if time.time() - started > timeout_seconds:
          raise TimeoutError("Async chat polling timed out")
      time.sleep(interval_seconds)

14. End-to-end smoke script idea

A minimal smoke flow should:

Validate tenant limits
Upload one small document
Send one sync chat request
Send one async chat request and poll for completion
Submit feedback for a completed request
Read site statistics

Use this as a deploy-time or post-deploy verification sequence in staging before promoting to production.

Start Here

Code Samples

Integration Playbooks

Reliability

API Reference

Shared environment variables

1. Connectivity check with tenant limits

2. Upload a file document

3. Create a text document

4. Create a Q&A document

5. Send a sync chat request

6. Send an async chat request and poll for completion

7. Submit feedback for a response

8. Close a session explicitly

9. Read site statistics

10. Read sessions

11. Minimal JavaScript client

12. Async polling helper in JavaScript

13. Minimal Python client

14. End-to-end smoke script idea

​Shared environment variables

​1. Connectivity check with tenant limits

​2. Upload a file document

​3. Create a text document

​4. Create a Q&A document

​5. Send a sync chat request

​6. Send an async chat request and poll for completion

​7. Submit feedback for a response

​8. Close a session explicitly

​9. Read site statistics

​10. Read sessions

​11. Minimal JavaScript client

​12. Async polling helper in JavaScript

​13. Minimal Python client

​14. End-to-end smoke script idea

Shared environment variables

1. Connectivity check with tenant limits

2. Upload a file document

3. Create a text document

4. Create a Q&A document

5. Send a sync chat request

6. Send an async chat request and poll for completion

7. Submit feedback for a response

8. Close a session explicitly

9. Read site statistics

10. Read sessions

11. Minimal JavaScript client

12. Async polling helper in JavaScript

13. Minimal Python client

14. End-to-end smoke script idea