REST API

Every request goes to https://api.inboxy.chat with an API key in the Authorization header. The key decides the company: there is no company id in any request.

Two layers: the public v1 contract (/api/v1/public/*, read-only, versioned) and the dashboard routes a key may call with the right scope. Both are in the live reference.

1. Sign in to Inboxy as a company admin and open Developers → API keys in the dashboard (/developer-center/keys).
2. Choose "Create an API key" and give the key a name you will recognise (for example "Claude on my laptop").
3. Tick only the scopes you need. There is no default set: a key without scopes cannot be created. The read tools need the ":read" scopes (contacts:read, orders:read, ...).
4. Pick an expiry: 30, 90 (default), 180 or 365 days, or never. The default is 90 days.
5. Copy the key when it is shown. It starts with "inboxy_". Store it in a secret manager or the OS keychain, never in a repository.

Send the key

Send it as a Bearer token. HTTPS only.

curl https://api.inboxy.chat/api/v1/public/company \
  -H "Authorization: Bearer $INBOXY_API_KEY"

import { InboxyClient } from '@inboxychat/sdk';

const inboxy = new InboxyClient({ apiKey: process.env.INBOXY_API_KEY! });
const { data } = await inboxy.getCompany();

inboxy auth login   # approve in the browser once
inboxy whoami

Authorization: Bearer inboxy_YOUR_KEY

Good to know

• Only a company admin can create keys. A key acts for its company only: no request takes a company id.
• A company can hold up to 10 live keys. Revoke a key from the same page.
• A key runs as the admin who created it. It stops working when it expires, is revoked, the company is paused, or its creator is no longer an admin.
• Every request a key makes is listed on the Developers → Request logs page.

Check the key, then read the five newest orders. Replace the key with yours (keep it in an environment variable).

export INBOXY_API_KEY="inboxy_YOUR_KEY"
curl -s https://api.inboxy.chat/api/v1/public/company \
  -H "Authorization: Bearer $INBOXY_API_KEY"

curl -s "https://api.inboxy.chat/api/v1/public/orders?limit=5" \
  -H "Authorization: Bearer $INBOXY_API_KEY"

{
  "success": true,
  "data": [ { "id": "...", "orderNumber": "..." } ],
  "meta": { "limit": 5, "hasMore": true, "nextCursor": "..." }
}

Page through a list

Lists use cursors. Pass limit (1-100, default 20); while meta.hasMore is true, send meta.nextCursor back as cursor.

curl -s "https://api.inboxy.chat/api/v1/public/contacts?limit=100&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $INBOXY_API_KEY"

Send a WhatsApp text

Needs messages:send and a connected WhatsApp number. A free-form text only goes out inside the 24-hour customer service window; outside it, send an approved template.

curl -s -X POST https://api.inboxy.chat/api/v1/whatsapp/messages/text \
  -H "Authorization: Bearer $INBOXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "966500000000", "body": "Your order has shipped." }'

Reply in a conversation

Works on any connected channel. Needs messages:send.

curl -s -X POST https://api.inboxy.chat/api/v1/inbox/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer $INBOXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "text", "content": "Thanks, we are on it." }'

Receive webhooks and verify them

Register an HTTPS endpoint (webhooks:write) with the events you want; the event list is at https://api.inboxy.chat/api/v1/webhooks/catalog. Every delivery carries X-Inboxy-Timestamp and X-Inboxy-Signature: sha256=HMAC-SHA256(secret, "<timestamp>.<raw body>"). Reject deliveries older than 300 seconds.

curl -s -X POST https://api.inboxy.chat/api/v1/webhooks \
  -H "Authorization: Bearer $INBOXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Order sync", "url": "https://example.com/webhooks/inboxy", "events": ["ecommerce.order.*"] }'

import crypto from 'node:crypto';

export function verifyInboxy(rawBody, headers, secret) {
  const ts = headers['x-inboxy-timestamp'];
  const sig = headers['x-inboxy-signature'] || '';
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Public v1 (read-only)

All paths are under https://api.inboxy.chat/api/v1/public.

Key-callable dashboard routes (examples)

The full list, with bodies and query parameters, is in the live reference and the OpenAPI document.

• 60 requests per minute per key, plus one budget per minute shared by all keys of a company. GET /api/v1/public/company returns both numbers.
• Over a limit you get 429 with a Retry-After header; wait that many seconds.
• Plan limits apply to keys exactly as they apply in the dashboard.
• Give each integration its own key with the fewest scopes and an expiry. Never put a key in browser code or a public repository.

Errors use one envelope: { "success": false, "error": { "code", "message", "details" } }. The CLI command inboxy doctor checks a key end to end.