Give your agent an iMessage number.
Text your agent from your phone like you'd text a friend. Plow gives it a real phone number. Your code sends over HTTP and hears back over one WebSocket, from any host, in any language.
A real phone number
Your agent answers on an iMessage number you can save in your contacts. Phones without iMessage get SMS or RCS, picked automatically.
Texts like a person
Markdown arrives as real iMessage styling. Show the typing bubble, send tapbacks, and attach up to four files per message.
Real-time texts
Texts arrive in real time over a WebSocket. Fetch past messages any time with GET /v1/chats/:uid/messages.
Try it on your phone.
Sign in with one text and Plow sets up a test agent on a real line. Text it, then answer from this page. Every API call the page makes shows up on the right.
Scan with your phone's camera and send the text it opens to Plow's sign-in number. Or text to .
Each request this page sends to the Plow API appears here. Open one to see its headers, body and response. Tokens are blocked out.
You text. It texts back.
Your agent hears you over one WebSocket and answers with one POST. On your phone it's a normal iMessage thread.
Send and hear back in a few lines.
Python with httpx. Any HTTP client works the same way.
One client, one token
Point httpx at Plow with your agent's token. Passing json= sets the JSON header for you.
import httpx plow = httpx.Client( base_url="https://api.plow.co", headers={"Authorization": f"Bearer {AGENT_TOKEN}"}, # from the one-time setup )
Send
One POST per message. Bodies are markdown, so **bold** arrives bold. The typing bubble is optional.
def send(chat_uid, text): plow.post(f"/v1/chats/{chat_uid}/typing", json={"action": "start"}) plow.post(f"/v1/chats/{chat_uid}/messages", json={"body": text})
Listen and reply
Trade a one-time ticket for a socket. Every text to your agent arrives as a frame. Your agent's own sends echo back as outbound, so skip those. After a reconnect, GET /v1/chats/:uid/messages returns anything you missed.
Prefer webhooks? Register an HTTPS URL with PUT /v1/webhook (account token, port 443). Plow POSTs the same events there, signed with X-Webhook-Signature, once each with no retries.
Registering returns a secret. Your receiver uses it to check X-Webhook-Signature: the hex HMAC-SHA256 of X-Webhook-Timestamp, a ., and the raw body. That signature is the only credential Plow sends, so any other auth on your endpoint is yours to add.
import json from websockets.sync.client import connect ticket = plow.post("/v1/ws/ticket", json={}).json()["ticket"] with connect(f"wss://api.plow.co/v1/ws?ticket={ticket}") as ws: for frame in ws: event = json.loads(frame) if event.get("event_type") != "message_received": continue msg = event["data"]["message"] if msg["direction"] == "inbound": send(msg["chat_uid"], f"**Got it:** {msg['body']}")
One-time setup: get your agent's token. The only human step is one text.
A person does one thing here: text a sign-in code from their phone. An agent can do every other step.
Sign in by texting a code from your phone, then create your agent on an open line. After that, text the line's number from the same phone and your agent hears it.
import time, httpx setup = httpx.Client(base_url="https://api.plow.co") a = setup.post("/v1/auth/activate", json={}).json() print(f'Text "Plow Activate: {a["display_code"]}" to {a["send_to"]}') secret = {"activation_secret": a["activation_secret"]} while True: r = setup.post("/v1/auth/activate/redeem", json=secret).json() if r["status"] == "verified": break time.sleep(2) setup.headers["Authorization"] = f"Bearer {r['token']}"
lines = setup.get("/v1/lines").json()["data"] line = next(ln for ln in lines if ln["provider_type"] == "imessage" and ln["available"]) agent = setup.post( "/v1/agents", json={"line_uid": line["uid"], "provider": "self_hosted", "name": "my-agent"}, ).json() AGENT_TOKEN = agent["token"] # works on this line only print("Now text your agent at", line["provider_key"]) # e.g. +16503466610
No library? Plain HTTP works.
Setup and sending in curl and in the Python standard library. Receiving needs a WebSocket client such as the websockets package, since the standard library has none. Without one, register a webhook and Plow POSTs each event to your HTTPS URL.
API=https://api.plow.co # Sign in: text the display_code to send_to from your phone, then redeem until "verified" curl -s $API/v1/auth/activate -H 'Content-Type: application/json' -d '{}' curl -s $API/v1/auth/activate/redeem -H 'Content-Type: application/json' \ -d '{"activation_secret":"…"}' ACCOUNT_TOKEN=plow_… # Create your agent on an "available" iMessage line; keep the "token" it returns curl -s $API/v1/lines -H "Authorization: Bearer $ACCOUNT_TOKEN" curl -s $API/v1/agents -H "Authorization: Bearer $ACCOUNT_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"line_uid":"ln_…","provider":"self_hosted","name":"my-agent"}' AGENT_TOKEN=plow_… # After you text the line: find the chat, then send curl -s $API/v1/chats -H "Authorization: Bearer $AGENT_TOKEN" curl -s $API/v1/chats/cht_…/messages -H "Authorization: Bearer $AGENT_TOKEN" \ -H 'Content-Type: application/json' -d '{"body":"Hello from curl"}'
import json, time, urllib.request
API = "https://api.plow.co"
def call(method, path, token=None, body=None):
data = None if body is None else json.dumps(body).encode()
req = urllib.request.Request(API + path, data=data, method=method)
req.add_header("Content-Type", "application/json")
if token:
req.add_header("Authorization", f"Bearer {token}")
with urllib.request.urlopen(req) as res:
return json.load(res)
a = call("POST", "/v1/auth/activate", body={})
print(f'Text {a["display_code"]} to {a["send_to"]}')
secret = {"activation_secret": a["activation_secret"]}
while (r := call("POST", "/v1/auth/activate/redeem", body=secret))["status"] != "verified":
time.sleep(2)
account = r["token"]
lines = call("GET", "/v1/lines", account)["data"]
line = next(ln for ln in lines if ln["provider_type"] == "imessage" and ln["available"])
agent = call("POST", "/v1/agents", account,
{"line_uid": line["uid"], "provider": "self_hosted", "name": "my-agent"})["token"]
input(f"Text {line['provider_key']} from the same phone, then press Enter ")
chat = call("GET", "/v1/chats", agent)["data"][0]["uid"]
call("POST", f"/v1/chats/{chat}/messages", agent, {"body": "Hello from the standard library"})
Which token for which call
The account token comes from redeem and covers every chat on your account. The agent token comes from creating the agent and covers the chats on its line.
| Call | Token |
|---|---|
POST /v1/auth/activate, POST /v1/auth/activate/redeem | None |
GET /v1/lines | Account or agent |
POST /v1/agents, DELETE /v1/agents/:uid | Account only |
POST /v1/ws/ticket | Account or agent. Send {}; the chat_id field is the deprecated single-chat socket with bare frames. |
GET /v1/chats, GET /v1/chats/:uid/messages | Account or agent |
POST /v1/chats/:uid/messages, POST /v1/chats/:uid/typing | Account or agent |
PUT /v1/webhook | Account only |
Bring it into your group texts.
You're in every conversation your agent has. One-on-one, it's you and your agent. In a group text, you're one of the members. Your agent only talks in threads you're in.
Add your agent's number to a group you're in. The next text in the group opens a chat for your agent.
Every message carries the group's members, so your agent can tell who said what.
Both work in groups, the same as one-on-one.
When a group chat starts, Plow sends the line's contact card, with its name and photo.
Shared numbers. Many agents answer on each Plow number. Every conversation belongs to one account and reaches only that account's agent.
Its own key. Your agent's token works on its line only. Rotate or revoke it any time.
The spec. Everything else, including reactions, attachments and voice memos, is in the OpenAPI spec at https://api.plow.co/openapi.json.