The Plow Chat API

• An HTTP client — to send; curl is fine
• jq — to read the token out of the redeem response
• Optionally, a WebSocket client — to receive
• Outbound HTTPS to api.plow.co
• iMessage or SMS: text one activation code from any iMessage client or phone. The only hands-on step (a group chat adds one more text, sent in the group thread itself).

Nothing is installed or self-hosted. Plow Chat is a hosted API at https://api.plow.co. Two credentials appear as you go:

The Hermes plow_chat gateway is one consumer of this API: it wires a Hermes agent to a Plow line so you can text the agent. To set that up, see Give your Hermes agent a phone number. The authoritative wire spec is the live openapi.json.

Ask Plow to provision a line and a chat in one call: this is the solo, one-to-one path, and the walkthrough rides it end to end. The response gives you a display_code to text, the number to text it to (send_to), and the single-use activation_secret. Group chats ride the same activation — see Group chats once you hold the token.

$ curl -sS -X POST https://api.plow.co/v1/auth/activate \
     -H 'content-type: application/json' \
     -d '{"provision_chat": true}'
# → { "display_code": "ABCDE", "send_to": "+1XXXXXXXXXX",
#     "activation_secret": "…", "line_id": "ln_…" }

From the exact phone or iMessage identity you want connected, text this to the send_to number from the last step:

Plow Activate: ABCDE
# text exactly this to the send_to number (+1XXXXXXXXXX)

This binds that messaging identity to the line. It proves you hold the phone, which is why it can’t be automated. It is also the identity Plow recognizes later when you start a group chat.

With the code texted, poll redeem with the activation_secret until status flips to verified. The verified response returns your Bearer token and, because you asked for a chat, the chat.uid. Poll a few seconds apart.

$ RESP=$(curl -sS -X POST https://api.plow.co/v1/auth/activate/redeem \
     -H 'content-type: application/json' \
     -d '{"activation_secret": "…"}'); jq -r .status <<<"$RESP"
# pending  → keep polling, a few seconds apart
# verified → $RESP now holds the token and chat.uid (printing it would log the token)

When it flips to verified, pull both values out of the captured response — Steps 5 and 6 read them as $TOKEN and $CHAT_UID — and keep a durable copy of the token at mode 600. Extracted this way, the token is never typed, so it never lands in your shell history:

$ export TOKEN=$(jq -r .token <<<"$RESP") CHAT_UID=$(jq -r .chat.uid <<<"$RESP")
$ (umask 177; printf '%s\n' "$TOKEN" > ~/.plow-token)

Post the message body to the chat. Any 2xx means it was accepted; the live API returns 201.

$ curl -sS -X POST https://api.plow.co/v1/chats/$CHAT_UID/messages \
     -H "authorization: Bearer $TOKEN" \
     -H 'content-type: application/json' \
     -d '{"body": "hello from the Plow API"}'
# 201 Created → sent.   409 chat_not_ready → the chat isn’t active, retry shortly.

Markdown

body is markdown. Plow converts it at the edge, so bold, italic, strikethrough, headings and lists arrive as real iMessage styling — as do :shake[…]-style animation directives.

$ curl -sS -X POST https://api.plow.co/v1/chats/$CHAT_UID/messages \
     -H "authorization: Bearer $TOKEN" \
     -H 'content-type: application/json' \
     -d '{"body": "**Deploy done** — *3 min*, :shake[zero] errors"}'
# → styled on iMessage. SMS and RCS recipients see it plain.

Reads speak markdown too: GET /v1/chats/{uid}/messages and the message_received frame hand body back as markdown, so a fetched body posts straight back unchanged. That’s the whole markdown story — raw decoration ranges, byte-literal sends and screen/bubble effects live in the openapi.json.

Typing indicator

Show the typing bubble in the thread while you compose, and clear it with stop. Sending a message clears it too, so a stop after a send is unnecessary.

$ curl -sS -X POST https://api.plow.co/v1/chats/$CHAT_UID/typing \
     -H "authorization: Bearer $TOKEN" \
     -H 'content-type: application/json' \
     -d '{"action": "start"}'
# → { "ok": true, "action": "start" }   Send "stop" to clear it.

It clears itself after about 85–90 seconds and nothing keeps it alive for you, so to hold it up, call start again about every 60 seconds. It’s iMessage only, and it doesn’t work in group chats — those return 424 provider_typing_failed. Even on a 200 it may not reach the recipient if nothing has been sent in the chat for the last few minutes; once you’ve sent one, it’s reliable. The rest is in the openapi.json.

Mint a short-lived WebSocket ticket, then connect and listen. Inbound texts arrive as message_received frames.

$ curl -sS -X POST https://api.plow.co/v1/ws/ticket \
     -H "authorization: Bearer $TOKEN" \
     -H 'content-type: application/json' \
     -d "{\"chat_id\": \"$CHAT_UID\"}"
# → { "ticket": "…" }   then connect:
#   wss://api.plow.co/v1/ws?ticket=<ticket>

Connect with any WebSocket client — Step 7’s script is the runnable version of this step — and leave it listening.

A minimal Python quickstart: given a token and chat id, it sends one message, then streams inbound replies. It works, but it’s the happy path only. You own the hardening.

#!/usr/bin/env python3
# Minimal Plow Chat quickstart: send one message, then stream inbound replies.
# deps: pip install websockets   (all HTTP uses the standard library)
import asyncio, json, os, urllib.request
import websockets
 
BASE = "https://api.plow.co"
TOKEN = os.environ["PLOW_TOKEN"]
CHAT_UID = os.environ["PLOW_CHAT_UID"]
AUTH = {"Content-Type": "application/json", "Authorization": f"Bearer {TOKEN}"}
 
def post(path, body):
    req = urllib.request.Request(
        f"{BASE}{path}", data=json.dumps(body).encode(), method="POST", headers=AUTH)
    with urllib.request.urlopen(req, timeout=30) as resp:
        return json.loads(resp.read().decode())
 
async def main():
    # send one message (any 2xx = success; the live API returns 201)
    sent = post(f"/v1/chats/{CHAT_UID}/messages", {"body": "hello from the quickstart"})
    print("sent:", sent.get("uid"))
 
    # receive: mint a short-lived ticket, then connect the WebSocket
    ticket = post("/v1/ws/ticket", {"chat_id": CHAT_UID})["ticket"]
    async with websockets.connect(f"wss://api.plow.co/v1/ws?ticket={ticket}") as ws:
        async for raw in ws:
            frame = json.loads(raw)
            if frame.get("type") != "message_received":
                continue
            msg = frame["message"]
            if msg.get("direction") == "outbound":   # echo of our own send - skip
                continue
            print(f"{msg['sender'].get('display_name', '?')}: {msg['body']}")
 
if __name__ == "__main__":
    asyncio.run(main())

The only third-party dependency is pip install websockets; everything else is the standard library. Python 3.8+. Run it with a token and chat id in the environment:

$ PLOW_TOKEN=… PLOW_CHAT_UID=cht_… python3 plow_quickstart.py

Everything the steps above call, the group-chat recipe, and the frames you’ll see on the WebSocket.

Endpoints

Group chats

There is no create call, and no codes for anyone to text. A group chat is born from the group text itself: add your Plow number — the send_to number from Step 2 — to a native group thread and send any message from the phone you activated with. Plow recognizes you, creates the chat with everyone in the thread, and replies 👋. Everything in this guide works on a group chat except the typing indicator, which returns 424 here.

hey everyone
# in a group thread that includes your Plow number (+1XXXXXXXXXX)
# Plow replies 👋 in the thread — that’s the chat, created

Nothing announces the new chat over the API, so pick it up from the list — it’s there the moment the 👋 lands:

$ CHATS=$(curl -sS https://api.plow.co/v1/chats -H "authorization: Bearer $TOKEN")
$ export CHAT_UID=$(jq -r '.data[-1].uid' <<<"$CHATS")   # oldest first, so the newest is last
# → { "object": "list", "data": [ { "uid": "cht_…", "status": "active",
#       "participants": [ {"type": "agent", …}, {"type": "member", …} ] } ], … }

Steps 5 and 6 then work unchanged with that CHAT_UID. Membership is whatever the messaging provider reports for the thread, and the roster grows on its own as quiet members first speak — you’ll see a message_received frame from a sender no earlier frame mentioned.

WebSocket frames

Read once before you start.

Nothing is installed on a host, so there’s nothing to uninstall. The only thing that persists is the credential.

The Bearer token is user-wide, so removing your copy is the cleanup. The exported TOKEN is gone when the shell closes; delete the durable copy Step 4 wrote:

$ rm -f ~/.plow-token        # remove the saved Bearer token

To retire the chat itself, soft-delete it through the API; the line returns to the pool. Success is 204 No Content.

$ curl -sS -X DELETE https://api.plow.co/v1/chats/$CHAT_UID \
     -H "authorization: Bearer $TOKEN"
# 204 No Content → deleted.   404 → already gone or not yours.

If you suspect the token leaked, rotate it: start over from Step 2 to mint a fresh one.