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.

Line
WillowActive
+1 (650) 346-6610
iMessage · SMS · RCS

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.

Did the deploy finish?
Yes. Took 3 minutes, zero errors.
Nice. Post the notes too?

Texts like a person

Markdown arrives as real iMessage styling. Show the typing bubble, send tapbacks, and attach up to four files per message.

WebSocket
connected
message_receivednew
Reconnect · catch up

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.

API calls

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.

    WSS/v1/ws?ticket=…
    POST/v1/chats/:uid/messages
    frame.json
    
                

    Send and hear back in a few lines.

    Python with httpx. Any HTTP client works the same way.

    The client

    One client, one token

    Point httpx at Plow with your agent's token. Passing json= sets the JSON header for you.

    python
    import httpx
    
    plow = httpx.Client(
        base_url="https://api.plow.co",
        headers={"Authorization": f"Bearer {AGENT_TOKEN}"},  # from the one-time setup
    )
    Step 1

    Send

    One POST per message. Bodies are markdown, so **bold** arrives bold. The typing bubble is optional.

    python
    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})
    Step 2

    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.

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

    sign in by text
    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']}"
    create your agent
    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.

    curl
    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"}'
    python · standard library only
    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.

    CallToken
    POST /v1/auth/activate, POST /v1/auth/activate/redeemNone
    GET /v1/linesAccount or agent
    POST /v1/agents, DELETE /v1/agents/:uidAccount only
    POST /v1/ws/ticketAccount or agent. Send {}; the chat_id field is the deprecated single-chat socket with bare frames.
    GET /v1/chats, GET /v1/chats/:uid/messagesAccount or agent
    POST /v1/chats/:uid/messages, POST /v1/chats/:uid/typingAccount or agent
    PUT /v1/webhookAccount 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 it to a group

    Add your agent's number to a group you're in. The next text in the group opens a chat for your agent.

    Knows who's talking

    Every message carries the group's members, so your agent can tell who said what.

    Typing and tapbacks

    Both work in groups, the same as one-on-one.

    A contact card

    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.

    Give your agent a number.