Tenant maintenance requests by iMessage, with photos

Who uses iMessage for maintenance requests?

iMessage maintenance requests suit residential property managers, small landlords and HOA managers with dozens to a few thousand units, whose tenants would rather text than log in to a portal. ZeroSettle is an iMessage API: a real phone number on real iMessage, running on Apple hardware we operate for you, that your code texts customers from and hears back on through a bearer token and signed webhooks.

The problem is the blind dispatch: a tenant calls about a leak with no details or photo, a technician goes out without the right part, and nobody knows whether the request was seen. A text thread carries the photo, the 👍 and the work-order number. Text-a-photo quotes for trades and insurance claim photos use the same inbound-photo pattern; the use cases hub lists more.

How iMessage maintenance requests work, step by step

The tenant texts your number, ZeroSettle posts each message to your webhook, and your code opens the work order and answers in the same thread. ZeroSettle has no built-in property-management integration; the work-order calls are yours.

1. Publish the number in the lease packet and on a laundry-room sign: “Text maintenance requests here,” with a QR code that encodes sms:+15555550100. Apple documents the sms: scheme as launching the Messages app; see how to get customers to text you first.
2. The tenant texts a description and a photo. Each reaches your webhook as a signed message.received event in about 1–2 seconds. A photo carries kind: "image" and an image.url; HEIC photos arrive as JPEG.
3. Match the sender to a tenant. The handle is usually the tenant's number, but it can be an iMessage email address (for example from an iPad with no number), so match on either.
4. Open a work order and attach the photo. Buildium's Open API, for example, has “Create a work order” and “Create a resident request” endpoints and a task-history file upload. Fetch the photo with GET /api/imessage/messages/{id}/image and your bearer token.
5. Confirm. POST /api/imessage/reactions with "reaction": "like" puts a 👍 on the tenant's message; a text with the work-order number follows.
6. Keep the visit in the thread. Text the vendor's arrival window from the ZeroSettle console or your software; after the job, send the vendor's “after” photo as image_b64 (up to 5 MB) with a caption in the same bubble.

Ask tenants for one photo per text and no videos: of several photos, ZeroSettle delivers only the first, and a video arrives with no file.

Example conversation: a leak under the kitchen sink

One request, from the first text to the “after” photo.

Aisha's text and photo are two message.received events: the text opens work order #2214 and gets the 👍, and the photo is attached to it. A coordinator typed the two questions and sent the “after” photo from the console.

Setup: webhook to work order

One receiver verifies ZeroSettle's signature, answers 2xx at once, then opens the work order, attaches the photo and confirms. It follows the webhook steps in the ZeroSettle docs; tenants, pms and notify_office stand in for your database, your property-management API and however your office gets alerts.

# maintenance.py: run with  uvicorn maintenance:app --port 8100
import asyncio, hashlib, hmac, json, os, time
from collections import defaultdict
import httpx
from fastapi import BackgroundTasks, FastAPI, Request, Response

ZS = httpx.AsyncClient(base_url=os.environ.get("ZEROSETTLE_BASE_URL", "https://portal.zerosettle.io"),
                       headers={"Authorization": f"Bearer {os.environ['ZEROSETTLE_TOKEN']}"}, timeout=120)
SECRET = os.environ["ZEROSETTLE_WEBHOOK_SECRET"]
app, seen, locks = FastAPI(), set(), defaultdict(asyncio.Lock)

def verify(header: str, raw: bytes, tolerance: int = 300) -> bool:
    try:
        p = dict(x.split("=", 1) for x in header.split(",")); t = int(p["t"])
    except Exception:
        return False
    if abs(time.time() - t) > tolerance:
        return False
    exp = hmac.new(SECRET.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(exp, p["v1"])

async def handle(m: dict) -> None:
    tenant = tenants.by_handle(m["handle"])          # your DB: phone number or iMessage email
    body, is_image = (m.get("text") or "").strip(), m.get("kind") == "image"
    if tenant is None or not (body or is_image):     # unknown sender, or a video with no file
        return notify_office(m)                       # a person answers from the console
    wo = pms.open_work_order(tenant)                  # the tenant's unclosed order, if any
    if wo:
        pms.add_note(wo, body)                        # a later "yes" joins the open order
    else:
        wo = pms.create_work_order(tenant, description=body)
        r = await ZS.post("/api/imessage/reactions", json={"message_id": m["id"], "reaction": "like"})
        if r.status_code == 403 and r.json()["error"]["code"] == "recipient_opted_out":
            pms.flag_for_call(wo)                     # they texted "stop": see below
        else:
            await ZS.post("/api/imessage/send", json={"to": m["handle"],
                          "text": f"Thanks, {tenant.first_name}. Work order #{wo.number} is open."})
    if m.get("image"):                                # null if the download never finished
        img = await ZS.get(m["image"]["url"])         # /api/imessage/messages/{id}/image
        pms.attach_file(wo, img.content, img.headers["content-type"])

async def serialized(m: dict) -> None:
    async with locks[m["handle"]]:                    # a text and a photo land concurrently
        await handle(m)

@app.post("/webhook")
async def webhook(req: Request, tasks: BackgroundTasks):
    raw = await req.body()
    if not verify(req.headers.get("X-ZeroSettle-Signature", ""), raw):
        return Response(status_code=401)
    ev = json.loads(raw); m = ev.get("message")
    if m and ev["event"] == "message.received" and (m["id"], ev["event"]) not in seen:
        seen.add((m["id"], ev["event"]))              # retries repeat the id and event
        tasks.add_task(serialized, m)
    return {"ok": True}

The per-tenant lock matters because ZeroSettle can deliver a line's events concurrently, so a text and a photo could otherwise each open a work order. Failed deliveries are retried after 1, 5 and 20 seconds (delivery status, webhook retries and latency). Register the receiver with PUT /api/imessage/webhook; receiving iMessages with a webhook covers testing.

Limits and consent for maintenance requests

Maintenance requests use none of ZeroSettle's new-contact limit, because anyone who texted the line first is never limited. The limit counts only the first text, photo or voice message you send to a tenant who has never texted the number.

Source: ZeroSettle iMessage API docs, “Errors, limits, and compliance”. The day runs 3 AM to 3 AM Eastern; tapbacks never count.

For a 240-unit portfolio, requests from all 240 tenants use no allowance. A first rent reminder to 240 tenants who have never texted takes 48 days on one Pro number at 5 a day, and every tenant who has sent a request drops out of that count. On any plan, end the arrival-window text with a question. If the tenant answers neither it nor the work-order text, and the two went out more than 5 minutes apart, ZeroSettle refuses the “after” photo with 403 awaiting_reply. Any reply from the tenant, even a tapback, resets the count.

When a request contains the word “stop”

A text with the word STOP in it opts the sender out, and a maintenance request can contain it: “the toilet won't stop running” opts that tenant out of every number on your account. The request still reaches your webhook, but your tapback and replies return 403 recipient_opted_out, so the handler flags the order for a phone call. Texting START, as the whole message, turns texts back on; if the tenant asks on that call instead, ZeroSettle can clear the opt-out for you.

Consent beyond maintenance

Rent reminders and community notices are texts you start, so they need the tenant's consent for that purpose and a record you can show, such as a lease clause or a separate form. Nothing promotional goes out before 8 am or after 9 pm in the tenant's time zone. Legally required notices still go through their required channels. See the compliance section of the docs. This isn't legal advice; check your notice and consent obligations with counsel.

When ZeroSettle is not a fit for maintenance requests

ZeroSettle is the wrong tool for a maintenance line in these cases:

• You need an emergency channel. Delivery is not guaranteed, so keep a staffed phone number.
• Tenants must send video. Inbound video arrives with no file; a noisy furnace has to be described.
• Many tenants use Android. iMessage reaches only iPhone and other Apple users, ZeroSettle has no SMS fallback, and on Android the QR code opens the SMS app. Keep the portal and an office number for those tenants.
• You need to reach a whole building today. A water-shutoff notice to tenants who have never texted the number goes out at 5 a day per Pro number (50 on Growth), so keep your existing notice channel for those.
• You want tenant, vendor and office in one thread. Group chats are not supported.
• You need to deliver legally required notices. Use the channel the law requires.

How much does iMessage for maintenance requests cost?

A maintenance line costs the plan price: ZeroSettle charges no per-message fees, and messages are unlimited (counted).

AI credits don't apply, because your code answers; on a number the hosted AI agent manages, inbound texts are not posted to your webhook, so nothing would open the work order. See pricing, the customer-support recipe in the docs, or get a number.