M2M Chat Request Status

Overview

This endpoint returns the current status of an async chat request. Use it to poll until the answer is ready. The endpoint is read-only and safe to call frequently. Typical completion time is 5-30 seconds; most requests complete within the first 10 seconds.

Authentication

Requires API key in the X-API-Key header:

X-API-Key: <YOUR_API_KEY>

Path parameters

string

required

The site ID.

string

required

The request ID from the async chat submission response.

Request example

curl --request GET \
  --url "https://api.uppzy.com/api/v1/m2m/sites/<SITE_ID>/chat/requests/<REQUEST_ID>" \
  --header "X-API-Key: <YOUR_API_KEY>"

const response = await fetch(
  `https://api.uppzy.com/api/v1/m2m/sites/${siteId}/chat/requests/${requestId}`,
  {
    headers: {
      "X-API-Key": process.env.UPPZY_API_KEY,
    },
  }
);

const data = await response.json();
console.log(`Status: ${data.status}`);

import requests
import os

response = requests.get(
    f"https://api.uppzy.com/api/v1/m2m/sites/{site_id}/chat/requests/{request_id}",
    headers={"X-API-Key": os.environ["UPPZY_API_KEY"]},
)

response.raise_for_status()
data = response.json()
print(f"Status: {data['status']}")

Response schema

string

The session identifier for this conversation.

string

The request ID.

string

One of: pending, completed, failed.

pending: The request is still processing.
completed: The answer is ready (see answer field).
failed: The request failed (see error field).

string

The assistant’s response. Only present when status is completed.

string

Error description if the request failed. Only present when status is failed.Examples: "failed to call rag service", "site not found".

Response examples

Pending

{
  "session_id": "user-123-web",
  "request_id": "req_550e8400e29b41d4a716446655440000",
  "status": "pending"
}

Completed

{
  "session_id": "user-123-web",
  "request_id": "req_550e8400e29b41d4a716446655440000",
  "status": "completed",
  "answer": "We offer standard shipping (5-7 business days) and express shipping (2-3 business days). International shipping is available to most countries."
}

Failed

{
  "session_id": "user-123-web",
  "request_id": "req_550e8400e29b41d4a716446655440000",
  "status": "failed",
  "error": "failed to call rag service"
}

Error responses

400 Bad Request

Invalid path parameters (e.g., malformed request ID).

{
  "error": "site id and request id are required"
}

401 Unauthorized

API key is missing, invalid, expired, or revoked.

{
  "error": "invalid_api_key"
}

403 Forbidden

The API key’s plan does not include M2M API access.

{
  "error": "api_access_not_available_on_plan"
}

404 Not Found

The site or request does not exist.

{
  "error": "request not found"
}

Common causes:

Wrong site ID
Wrong request ID
Request has expired or been deleted
Request belongs to a different site

500 Internal Server Error

An unexpected error occurred.

Implementation tips

Polling loop pattern

async function waitForChatCompletion(siteId, requestId, timeoutSeconds = 300) {
  const startTime = Date.now();
  const timeoutMs = timeoutSeconds * 1000;

  while (Date.now() - startTime < timeoutMs) {
    const response = await fetch(
      `https://api.uppzy.com/api/v1/m2m/sites/${siteId}/chat/requests/${requestId}`,
      {
        headers: {
          "X-API-Key": process.env.UPPZY_API_KEY,
        },
      }
    );

    if (!response.ok) {
      // Handle auth or server errors
      throw new Error(`Status check failed: ${response.status}`);
    }

    const data = await response.json();

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

    if (data.status === "failed") {
      throw new Error(`Chat failed: ${data.error}`);
    }

    // Still pending, wait before next poll
    await new Promise((r) => setTimeout(r, 1000));
  }

  throw new Error("Chat request timed out");
}

Optimal polling interval

First poll: Wait 1-2 seconds (processing takes time)
Subsequent polls: 1-2 second intervals
Max attempts: 120-300 (2-5 minutes)

Most requests complete in 5-30 seconds. Waiting longer helps avoid thundering herd and reduces API load.

Handling partial failures

If the status endpoint returns 5xx errors, implement exponential backoff:

async function pollWithBackoff(siteId, requestId) {
  let backoffMs = 1000;
  const maxBackoff = 10000;

  while (true) {
    const response = await fetch(
      `https://api.uppzy.com/api/v1/m2m/sites/${siteId}/chat/requests/${requestId}`,
      {
        headers: { "X-API-Key": process.env.UPPZY_API_KEY },
      }
    );

    if (response.ok) {
      const data = await response.json();
      if (data.status !== "pending") {
        return data;
      }
      backoffMs = 1000; // Reset backoff on success
    } else if (response.status >= 500) {
      // Server error, back off
      backoffMs = Math.min(backoffMs * 1.5, maxBackoff);
    } else if (response.status === 404) {
      // Request not found, stop polling
      throw new Error("Request expired or not found");
    } else {
      // Other client errors
      throw new Error(`Poll failed: ${response.status}`);
    }

    await new Promise((r) => setTimeout(r, backoffMs));
  }
}

Tracking in a database

Store the request ID and check status later:

-- Example: store request info for later polling
INSERT INTO pending_chat_requests (
  request_id,
  site_id,
  user_id,
  submitted_at,
  status
) VALUES (
  'req_...',
  'site_...',
  'user_...',
  NOW(),
  'pending'
);

-- Later: update when complete
UPDATE pending_chat_requests
SET status = 'completed', answer = '...', completed_at = NOW()
WHERE request_id = 'req_...';

M2M Chat (Async) — Submit a request
M2M Chat (Sync) — Immediate answer
M2M Chat Feedback — Rate the answer

Start Here

Code Samples

Integration Playbooks

Reliability

API Reference

Overview

Authentication

Path parameters

Request example

Response schema

Response examples

Pending

Completed

Failed

Error responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Implementation tips

Polling loop pattern

Optimal polling interval

Handling partial failures

Tracking in a database

​Overview

​Authentication

​Path parameters

​Request example

​Response schema

​Response examples

​Pending

​Completed

​Failed

​Error responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Implementation tips

​Polling loop pattern

​Optimal polling interval

​Handling partial failures

​Tracking in a database

​Related endpoints

Overview

Authentication

Path parameters

Request example

Response schema

Response examples

Pending

Completed

Failed

Error responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Implementation tips

Polling loop pattern

Optimal polling interval

Handling partial failures

Tracking in a database

Related endpoints