quo

Files (15)

• SKILL.md
• evals.json · evals/
• ai-cost-and-registration.md · references/
• api-basics.md · references/
• calls.md · references/
• contacts.md · references/
• conversations-and-tasks.md · references/
• messages-and-numbers.md · references/
• webhooks-v1-and-users.md · references/
• webhooks.md · references/
• quo-client.mjs · scripts/
• quo-preflight.sh · scripts/
• scaffold-quo.mjs · scripts/
• verify-webhook.js · scripts/
• verify_webhook.py · scripts/

SKILL.md (first lines)

# Quo (formerly OpenPhone) — REST API & Webhooks Integration

Add programmatic phone communications to a site or app: **send and receive
SMS/text messages**, pull **call** history with AI **summaries / transcripts /
recordings / voicemails**, manage **contacts** (and custom fields),
**conversations**, **tasks**, **users**, and **phone numbers**, and react to
events in real time via **webhooks**. Quo is the rebrand of OpenPhone; the two
share one API.

> **Naming:** the product is now **Quo** (`quo.com`), but the REST API, the
> OpenAPI spec, and most existing integrations are unchanged from OpenPhone. The
> canonical host is `https://api.quo.com/v1`; `https://api.openphone.com/v1` is a
> live, byte-identical legacy alias (both verified). Pick one and keep it in a
> single configurable constant.

## Facts that prevent broken work

Read this table first — each row is a real failure integrators hit.

| Fact | Consequence |
|---|---|
| **Auth is the RAW API key** in the `Authorization` header. The docs say verbatim *"The Quo API does not use a Bearer token."* | `Authorization: Bearer <key>` → `401 Unauthorized`. Send the key value alone: `Authorization: <key>`. |
| **Base URL** is `https://api.quo.com/v1` (OpenAPI `servers`); `https://api.openphone.com/v1` is an identical alias | Hardcoding one host is fine, but don't mix `/v1` REST with the **un-prefixed** beta webhook host (`https://api.quo.com/webhooks`, no `/v1`). |
| **Sending SMS to US numbers requires A2P 10DLC carrier registration** | Without it, `POST /v1/messages` returns **`400` code `0206400` "A2P Registration Not Approved"** — a 400 here is NOT a malformed body. |
| **Send is async and returns `202`**, not `200` | Treat `202` as *queued*. `to` must be **exactly one** E.164 recipient (`maxItems: 1` — no fan-out per call); `content` is 1–1600 non-whitespace chars; **MMS is not supported**. |
| `from` is an **E.164 number OR a `PN…` phoneNumberId** | The legacy top-level `phoneNumberId` body field is deprecated — use `from`. `GET /v1/phone-numbers` gives you valid senders. |
| **Rate limit: 10 requests/second per API key** → `429` | The docs document **no** `Retry-After` / `RateLimit-*` headers — implement your own exponential backoff (the bundled client already does). |
| **Pagination:** `maxResults` (required, max 100) + `pageToken` → response `nextPageToken` | `totalItems` is **documented as inaccurate** — loop until `nextPageToken` is `null`; never page on `totalItems`. |
| **List messages/calls are scoped, not global** | `GET /v1/messages` and `/v1/calls` require `phoneNumberId` **and** `participants` **and** `maxResults` together. There is no "list everything" call. |
| **Beta webhooks are signed; legacy v1 webhooks are not** | For verifiable authenticity use the **beta** webhook API: HMAC-SHA256 (base64) over `{webhook-id}.{webhook-timestamp}.{raw-body}` with a `whsec_…` secret. Verify the **raw** body before parsing. |
| **Webhook idempotency key is the `webhook-id` HEADER** | Not the envelope `id`. Deliveries retry (8 attempts over ~27h) and arrive out of order — dedupe on `webhook-id`, retain ≥28h, make handlers order-independent. |
| **AI features are plan-gated** | Call **summaries** and **transcripts** (and their webhooks) require a **business or scale** plan; lower plans get `403`/absent. They're also async — poll `processingStatus` until `completed`. |
| **Error envelope is inconsistent** | The live gateway returns `{ "error": { "message", "key", "trace" } }`; the OpenAPI documents `{ "message", "code", "status", "errors": [] }`. Parse defensively: `body.error?.message ?? body.message`. |
| **ID prefixes are load-bearing** | `AC…` activity/message/call · `PN…` phone number · `US…` user · `CN…` conversation · `CT…` contact · `VM…` voicemail. Endpoints validate them by regex. |

## Preflight

Confirm tooling + key before writing code, so the first failure points at config:

```bash
bash scripts/quo-preflight.sh            # node/curl + QUO_API_KEY + Bearer-mistake checks
bash scripts/quo-preflight.sh --probe    # also calls GET /v1/phone-numbers live (real 401 vs 200)
```

It accepts `QUO_API_KEY` (or the legacy `OPENPHONE_API_KEY`), flags a stray
`Bearer ` prefix, and validates key **presence** — a live `200`/`401` from
`--probe` is what proves the key actually works.

## Build an integration in one command (scaffold)

The fastest path to a working integration is to **generate** it, then customize.
`scripts/scaffold-quo.mjs` writes a complete, runnable full-stack app — an
Express backend (API client + send-SMS route + a **signature-verified** beta
webhook receiver) and a frontend — with the client + webhook verifier **inlined**
(the generated project has zero dependency on this skill).

```bash
node scripts/scaffold-quo.mjs --out ./quo-app                 # vanilla JS frontend
node scripts/scaffold-quo.mjs --out ./quo-app --frontend react
node scripts/scaffold-quo.mjs --help                          # flags; --dry-run previews
```

Then: `cd quo-app && npm install && cp .env.example .env` (fill in `QUO_API_KEY`),
`npm start`. Customize the emitted code with the references below — the scaffold
is a correct skeleton, not a black box.

## Quick start by hand — send an SMS

The shortest path to "text from my app": one server-side call with the raw-key
header. Use the bundled client so the auth/202/E.164 rules are handled for you.

```ts
import { createQuoClient } from "./scripts/quo-client.mjs";

const quo = createQuoClient({ apiKey: process.env.QUO_API_KEY }); // raw key, no Bearer

const msg = await quo.sendMessage({
  from: "+15555550100",          // one of YOUR Quo numbers (E.164) or its PN… id
  to: "+15555550111",            // exactly ONE E.164 recipient
  content: "Hello from Quo 👋",  // 1–1600 chars
});
// 202 Accepted → queued. Final delivery arrives as a `message.delivered` webhook,
// or poll GET /v1/messages/{id} (status: queued|sent|delivered|undelivered).
```

Raw HTTP equivalent (note the header — **no `Bearer`**):

```bash
curl -X POST https://api.quo.com/v1/messages \
  -H "Authorization: $QUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"+15555550100","to":["+15555550111"],"content":"Hello from Quo"}'
```

For the CLI: `node scripts/quo-client.mjs send --from +1… --to +1… --text "Hi"`.

## Quick start by hand — receive a verified webhook

Use the **beta** webhook API (it's signed). Create a subscription, save the
`whsec_…` secret, and verify every delivery against the **raw** body:

```ts
import express from "express";
import { verifyQuoWebhook } from "./scripts/verify-webhook.js";

// express.raw — the signature is over the raw bytes; a JSON parser first breaks it.
app.post("/webhooks/quo", express.raw({ type: "*/*" }), (req, res) => {
  if (!verifyQuoWebhook(req.headers, req.body, process.env.QUO_WEBHOOK_KEY)) {
    return res.status(400).send("bad signature");
  }
  const id = req.headers["webhook-id"];       // idempotency key (NOT envelope.id)
  // ...dedupe on `id` (retain ≥28h), then handle:
  const event = JSON.parse(req.body.toString());
  if (event.type === "message.received") {
    console.log("inbound:", event.data.resource.text);
  }
  res.status(200).json({ ok: true });          // ack fast; do slow work async
});
```

From kryptobaseddev/awesome-skills, MIT.

More from kryptobaseddev/awesome-skills