API reference

PhoneGateway gives the Android phone your business already owns a JSON API. You queue a text, the phone sends it from its own SIM, and the result comes back to you by polling or webhook. Replies land in the same place.

Overview

Base URL: https://api.phonegateway.app. All requests and responses are JSON (Content-Type: application/json). Times are Unix seconds. Phone numbers are E.164 (+19165550142); a bare 10-digit number is read as US.

Three kinds of caller use the API:

• Your account, with an API key made in the dashboard. It acts on your account only.
• The phone app, with a device key it gets when you scan a pair code. You never handle this one.
• A platform (software that offers PhoneGateway to its own customers), with a platform key. See Platforms.

Authentication

Send your key in the X-API-Key header. Keys look like ptl_<id>_<secret>, are shown once when created, and are stored hashed. Make and revoke them under API keys in the dashboard, or with the keys endpoints.

curl https://api.phonegateway.app/v1/account \
  -H "X-API-Key: ptl_your_key"

{ "account": { "id": "acc_…", "name": "Bright Coat Painting", "email": "owner@…", "status": "active" } }

Quick start

1. Install the PhoneGateway app on an Android phone with a SIM.
2. In the dashboard, open Phones, add a phone and scan the code with it.
3. Under API keys, create a key.
4. Send a text:

curl https://api.phonegateway.app/v1/messages \
  -H "X-API-Key: ptl_your_key" \
  -H "Content-Type: application/json" \
  -d '{"to": "+19165550142", "body": "Hi Maria, your estimate is ready."}'

The response is 202 Accepted with the message in status queued. The phone picks it up within a few seconds and the status moves to sent, then delivered. Add a webhook to hear about each step, and about replies.

Send a text

HTTP/1.1 202 Accepted
{ "message": { "id": "msg_8f2c…", "status": "queued", "contact": "+19165550142", "segments": 1, … },
  "deduped": false }

A send can be refused before it's queued. Each refusal has an error sentence and a code:

The message object

One message by id.

History

Newest first, 50 at a time (limit up to 200). Filters: contact, ref, direction (inbound/outbound), status. Page with before=<next_before> from the previous response.

GET /v1/messages?contact=%2B19165550142&limit=100
{ "messages": [ … ], "next_before": 1731020000 }

Conversations

One row per person, newest activity first, with that person's latest message. This is the inbox view. Fetch a thread with GET /v1/messages?contact=….

{ "conversations": [ { "contact": "+19165550142", "last": { "direction": "inbound", "body": "Great, can you come Thursday?", … } } ] }

Phones

A phone (device) is an Android phone running the app, connected to your account by a one-time pair link. Up to ten per account.

{ "devices": [ { "id": "dev_…", "label": "Front desk", "phone_number": "+19165550199", "status": "active",
    "paired": true, "carrier": "T-Mobile", "battery_level": 82, "charging": true, "last_seen_at": 1731024170, "seconds_since_seen": 4 } ] }

Status is active, offline (no check-in for three minutes), paused (by you, or automatically after three STOPs in a day; see paused_reason) or error.

Add a phone. Body: {"label": "Front desk"}. Returns the device plus a pair_page URL to show as a QR code, a pair_link (phonegateway://…) and pair_expires_at. The link works once and expires in 24 hours. The dashboard does this for you.

A fresh pair link for a replaced or lost phone. The old phone's key stops working the moment this is called.

{"label": "…"} and/or {"status": "paused"} or "active". A paused phone keeps checking in but sends nothing; queued texts wait for it or another active phone.

Disconnects the phone. Its unsent texts fail with phone removed; history stays.

STOP list

When someone texts STOP (or STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT) to your phone, they go on your account's STOP list, get your opt-out confirmation, and every later send to them is refused with opted_out. START (or UNSTOP, YES) takes them off. HELP or INFO gets your help text. The list is per account: a STOP to you doesn't affect anyone else using PhoneGateway.

{"phone_number": "+1…", "reason": "asked by phone"} adds someone yourself.

Removes a number. Do this only when the person asked you to text them again.

Settings

PATCH /v1/settings
{ "max_per_hour": 20, "quiet_hours_start": 20, "help_message": "Bright Coat Painting. Call (916) 555-0199 or reply STOP to opt out." }

API keys

Each key's id, label, last use and revocation time. Never the secret.

{"label": "Zapier"}. Returns api_key once. Up to ten live keys.

Revokes a key. Requests with it fail from the next one.

Stats

{ "last_24h": { "sent": 3, "delivered": 41, "failed": 1, "received": 18, "queued": 0 },
  "devices": { "active": 1 }, "opt_outs": 2 }

Webhooks

A webhook is an https URL on your server that we POST to when something happens. Each event is tried right away and retried with backoff for about a day (8 tries) until your server answers with a 2xx. Up to ten webhooks per account.

POST /v1/webhooks
{ "url": "https://yourapp.com/hooks/texts", "events": ["message.received", "message.failed"] }   // or "events": "*"

201 { "webhook": { "id": "wh_…", … }, "secret": "whsec_…" }   // the secret is shown once

Change url, events or active; or remove it with its delivery log.

The last 50 deliveries with status, attempts, your server's last HTTP status and the next retry time.

Events

Every delivery is a POST with a JSON body: { "id": "evt_…", "type": "…", "created": <unix>, "account_id": "acc_…", "data": { … } }. One event fans out to every webhook that wants it with the same id, so you can de-duplicate on it.

Headers on every delivery: X-PTL-Event (the type), X-PTL-Delivery (whd_…, unique per webhook per event) and X-PTL-Signature.

Verifying signatures

X-PTL-Signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>.<raw body>" with your webhook's secret. Check it on the raw request body, before parsing JSON, and reject timestamps older than five minutes.

// Node (Express with express.raw({ type: "application/json" }))
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(req, secret) {
  const sig = Object.fromEntries(req.get("X-PTL-Signature").split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${sig.t}.`).update(req.body).digest("hex");
  return expected.length === sig.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}

# Python
import hmac, hashlib, time

def verify(headers, raw_body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in headers["X-PTL-Signature"].split(","))
    if abs(time.time() - int(parts["t"])) > 300: return False
    expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Answer 2xx quickly and do the work afterwards. A slow reply (over 8 seconds) counts as a failure and is retried.

AI agents (MCP server)

PhoneGateway is also an MCP server, so an AI agent can text from your phone through the same account, with the same limits and STOP list as the API. It speaks MCP over Streamable HTTP with no sessions and no sign-in flow: the agent sends your API key.

# Claude Code
claude mcp add --transport http phonegateway https://api.phonegateway.app/mcp \
  --header "X-API-Key: ptl_your_key"

# Codex, Cursor, ChatGPT and other MCP clients: Streamable HTTP at that URL,
# authenticated with X-API-Key or Authorization: Bearer ptl_your_key

The server's instructions tell the agent to send only what the owner asked for, keep texts short, read the thread before replying and never text a number that asked to stop. A refused send (STOP list, quiet hours, a limit) comes back as a tool error carrying the API's error and code, so the agent can tell you why.

Errors

Errors are JSON: { "error": "a sentence you can show a person", "code": "optional_machine_code" }.

Limits

• Texts: up to 1,600 characters; GSM text splits into 153-character segments, emoji into 67-character segments. Caps count segments.
• Per account: 10 phones, 10 live API keys, 10 webhooks.
• Default per phone: 30 segments an hour, 150 a day, 10 seconds apart, quiet 9 pm to 8 am local to the recipient. All adjustable in settings, within the ranges shown there.
• A text queued longer than six hours (default) fails rather than going out stale.
• A phone that gets three STOPs in a day from its own sends is paused until you resume it.

These exist to keep your number from looking like a bulk sender to the carrier. PhoneGateway is for one-to-one business texting, not marketing blasts; see the terms.

Platforms

If your software serves many businesses, a platform key lets you create an account per customer and act for it. Send the platform key as X-API-Key and name the account with X-Account-Id. Platform keys are issued by hand; email us.

{ "name": "Joe's Plumbing", "email": "joe@example.com", "external_ref": "yourapp:joes-plumbing" }
201 { "account": { "id": "acc_…", … } }      // the same external_ref returns the same account, with "existing": true

Then every other endpoint works with X-Account-Id: acc_… added: make the customer's pair link, send for them, read their inbox. If the account has an email, that person can also sign in to the dashboard at phonegateway.app and see the same account.