phonesms.trucopilot.com

Multi-tenant SMS gateway. Android phones push received SMS here and stay connected over a WebSocket; external apps & AI agents read messages and send SMS through the phones' SIMs. Keyed by OrgId + SecretKey.

Swagger UIOpenAPI JSONllms.txt (copy for AI agents)

Authentication

• OrgId: 3–64 chars (letters, digits, -, _). SecretKey: 12–50 chars.
• The pair is claimed on first use (first /webhook or /websocket creates it); reuse it afterward.
• Pass the secret in the URL path where shown, or as header X-Secret-Key (preferred — keeps it out of logs).
• 10 failed attempts locks an OrgId for 5 minutes.

REST API

POST /webhook — store inbound SMS (used by the phone)

curl -X POST https://phonesms.trucopilot.com/webhook -H 'Content-Type: application/json' -d '{
  "org_id": "myorg",
  "secret_key": "my-secret-key-123",
  "messages": [
    {"address":"+15551112222","body":"hello","date":1700000000000,"sim_slot":0,"id":"123"}
  ]
}'
# -> {"ok":true,"org_id":"myorg","stored":1}

GET /messages/{OrgId}/{SecretKey} — read messages

# secret in path:
curl https://phonesms.trucopilot.com/messages/myorg/my-secret-key-123

# or secret in header (preferred):
curl -H 'X-Secret-Key: my-secret-key-123' https://phonesms.trucopilot.com/messages/myorg

# filters: ?limit=100 (max 1000)  &since_id=0  &direction=in|out  &sim=+15551112222
# -> {"org_id":"myorg","count":1,"messages":[{"id":1,"direction":"in","address":"+1...","body":"hello","status":"received","created_at":"..."}]}

POST /send/{OrgId} — send SMS through the connected phone

curl -X POST https://phonesms.trucopilot.com/send/myorg -H 'Content-Type: application/json' -d '{
  "secret_key": "my-secret-key-123",
  "sim": "+15551112222",            // optional: SIM number or slot index; omit = first device
  "to": "+15553334444",
  "body": "sent from the API"
}'
# multiple at once: replace to/body with  "messages":[{"to":"+1...","body":"a"},{"to":"+1...","body":"b"}]
# -> {"ok":true,"device_online":true,"queued":1,"results":[{"id":5,"to":"+15553334444","status":"sending"}]}

GET /sims/{OrgId}/{SecretKey} — list SIMs

curl -H 'X-Secret-Key: my-secret-key-123' https://phonesms.trucopilot.com/sims/myorg
# -> {"online_devices":1,"live_sims":[{"slot":0,"number":"+1...","carrier":"AT&T"}],"known_sims":[...]}

WS WebSocket — the phone's control channel

Connect: wss://phonesms.trucopilot.com/websocket?org_id=ORG&secret_key=SECRET

# python example (pip install websockets)
import asyncio, json, websockets
async def main():
    url = "wss://phonesms.trucopilot.com/websocket?org_id=myorg&secret_key=my-secret-key-123"
    async with websockets.connect(url) as ws:
        print(await ws.recv())  # {"type":"connected",...}
        await ws.send(json.dumps({"type":"sims","sims":[{"slot":0,"number":"+15551112222"}]}))
        async for msg in ws:
            print(msg)  # handle {"type":"send_sms",...}
asyncio.run(main())

Use from an AI agent / MCP

Paste /llms.txt into your agent, or feed it the OpenAPI spec at /openapi.json to auto-generate tools. Minimal tool set: get_messages (GET /messages), send_sms (POST /send), list_sims (GET /sims).