Quo

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.

Preflight

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

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).

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.

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):

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:

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
});

Create the subscription (un-prefixed host, version header required):

curl -X POST https://api.quo.com/webhooks \
  -H "Authorization: $QUO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-quo-api-version: 2026-03-30" \
  -d '{"url":"https://YOUR_HOST/webhooks/quo","events":["message.received","message.delivered","call.completed"]}'
# Save data.key (whsec_…) into QUO_WEBHOOK_KEY — it is shown only once.

Prove your verifier works without any traffic: node scripts/verify-webhook.js --selftest.

API surface

All REST paths are under https://api.quo.com/v1. Beta webhooks live at https://api.quo.com/webhooks (no /v1).

Where to go next

Each reference is self-contained and source-cited (https://www.quo.com/docs/mdx/...):

Scripts

Common mistakes

Resources

• API reference: https://www.quo.com/docs/mdx/api-reference/introduction
• Doc index (machine-readable): https://www.quo.com/docs/llms.txt
• OpenAPI spec: https://openphone-public-api-prod.s3.us-west-2.amazonaws.com/public/openphone-public-api-v1-prod.json
• LLM-ready docs bundle: https://openphone-public-api-prod.s3.us-west-2.amazonaws.com/public/openphone-public-api-llm-ready-docs-prod.zip
• Building with AI/LLMs guide: https://www.quo.com/docs/mdx/guides/building-with-ai-llms