Uno Answers documentation

Uno Answers is the parent app and client registry for the platform. It receives all Instagram webhooks from Meta, works out which client each event belongs to, and forwards the event to that client's app.

Meta (Instagram) ──► POST /api/instagram/webhook  (signature verified)
                          │
                          ├─ entry.id ─► clients.instagram_account_id ─► client
                          ├─ log ─► webhook_logs
                          └─ shared mode ─► POST https://{subdomain}.askuno.com/api/internal/process-webhook
                                            (signed with the client's webhook secret)

Shared mode clients use the Uno Answers Meta app (App ID 1634590611674345). Own mode clients use their own Meta app and receive webhooks from Meta directly.

API reference

All request and response bodies are JSON. Errors have the shape {"error": "message", "details": [...]}. Admin endpoints require the X-API-Key header. API routes are rate-limited to 100 requests per 15 minutes per IP; Meta callbacks are exempt.

Public

Client apps

Admin

Create a client

curl -X POST https://unoanswers.com/api/admin/clients \
  -H "X-API-Key: $INTERNAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HDFC Bank",
    "subdomain": "hdfc",
    "email": "marketing@hdfc.example",
    "mode": "shared",
    "instagram_account_id": "17841400000000000"
  }'

Response 201:

{
  "client": { "id": "4d3c…", "name": "HDFC Bank", "subdomain": "hdfc", "mode": "shared",
              "url": "https://hdfc.askuno.com", "is_active": true, … },
  "credentials": {
    "webhook_secret": "9f2c…",     // verifies forwards from Uno Answers
    "internal_api_key": "51ab…"    // X-Client-Key for calls to the registry
  },
  "warning": "Store these credentials now. They cannot be retrieved again, only regenerated."
}

Webhook events

Subscribe the Meta app's Instagram webhook to https://unoanswers.com/api/instagram/webhook with verify token ASK_UNO_VERIFY_TOKEN. Supported fields:

Other fields are logged and not forwarded. Example comments payload from Meta:

{
  "object": "instagram",
  "entry": [{
    "id": "17841400000000000",           // the client's Instagram account
    "time": 1726650000,
    "changes": [{
      "field": "comments",
      "value": {
        "id": "18012345678901234",
        "text": "DEALS please!",
        "from": { "id": "5566778899", "username": "aarav.k" },
        "media": { "id": "17999999999999999", "media_product_type": "FEED" }
      }
    }]
  }]
}

Forwarding to clients

Each supported event is forwarded individually, in the same Meta envelope, to POST https://{subdomain}.askuno.com/api/internal/process-webhook with these headers:

Client apps must verify the signature and reject timestamps more than 5 minutes old. Failed forwards (network errors, 429, 5xx) are retried 3 times with exponential backoff. Data-deletion and deauthorize notices are forwarded to /api/internal/data-deletion and /api/internal/deauthorize with the same signing.

// Client app (Express) — verify a forward from Uno Answers
import crypto from 'node:crypto';

function verifyUno(req, secret) {
  const ts = req.get('X-Uno-Timestamp');
  if (!ts || Math.abs(Date.now() - Number(ts)) > 5 * 60 * 1000) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(ts + '.' + req.rawBody).digest('hex');
  const given = req.get('X-Uno-Signature') || '';
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Database schemas

The registry runs on Supabase Postgres. The full migration is in database/migrations/001-init.sql.

Row Level Security is enabled on every table with no public policies, so only the service role (this server) can read or write.

Deployment guide

1. Run database/migrations/001-init.sql in the Supabase SQL editor (or psql "$DATABASE_URL" -f …).
2. Generate secrets:

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"     # INTERNAL_API_KEY
   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"  # ENCRYPTION_KEY

3. Add every variable in .env.example to Vercel (vercel env add NAME production).
4. Deploy with vercel deploy --prod and check GET /health.
5. In the Meta app dashboard, set the webhook callback URL to /api/instagram/webhook, the Deauthorize callback to /api/auth/deauthorize and the Data Deletion callback to /api/auth/data-deletion. Subscribe to comments, live_comments and messages.

Privacy & GDPR

When a user asks Meta to delete their data, Uno Answers:

1. verifies the signed_request with the app secret,
2. deletes every webhook log the user triggered from the registry,
3. notifies every active shared-mode client app so it can delete campaign data,
4. returns a confirmation code and a status page URL (/data-deletion-status?code=…) to Meta.

Once every client has confirmed, the Instagram user ID is removed from the deletion record.

FAQ