WebSocket overview
The WebSocket gives you one persistent connection to the farm. Over it you call the same operations the REST API exposes, and you receive status events as they happen.
Open it once, keep it open, and work through it. There is no per-request handshake, no polling loop, and no new token on every call.
When to use it
Pick the WebSocket when your program needs to react to what a phone or a publish is doing.
| WebSocket | REST | MCP | |
|---|---|---|---|
| Shape | One connection, many frames | One request, one response | Tools called by an AI client |
| Auth | API token, exchanged for a socket URL | API token on every request | OAuth in a browser |
| Push updates | Yes | No, poll | No, poll |
| Best for | Live control, long sessions, reacting to status changes | Scripts, one-off calls, anything stateless | Assistants and agents |
Use REST for a script that does one thing and exits. Use MCP when an assistant is the caller. Use the WebSocket when you are driving phones interactively, or when something in your app has to update the moment a run finishes.
The mental model
Three ideas cover the whole surface.
Funs are what you call. A fun is one operation, named like a path: /app/phones/list,
/app/submissions/create, /app/billing/summary. You send a frame naming the fun, and a
reply comes back with a status and a body. See Frames and replies.
Events are what you receive. The connection also pushes frames you never asked for, one per status change on a run, a submission or a billing request. There is nothing to subscribe to. See Events.
Abilities and phone grants decide what you can reach. Your API token carries abilities
(phones:read, phones:control, accounts, submissions, billing), and your account
holds view or control grants on individual phones. Both are baked into the connection when
you open it. A fun your token cannot use, or a phone you cannot reach, comes back 403.
Nothing is global. You see your own accounts and submissions, and you touch only the phones granted to you.
Where to go next
- Connecting: get a socket URL, connect, stay connected, reconnect.
- Frames and replies: the frame format, the reply envelope, every status code.
- Events: the three push events and what they carry.
- Phones: list, snapshot, read the screen, send input, run macros and agents.
- Accounts: link and manage posting accounts.
- Submissions: publish videos and follow them.
- Billing: rentals, phone count changes and approvals.
The Python and TypeScript SDKs wrap all of this. They mint the URL, connect, match replies and hand you typed events, so most people never write a frame by hand.