Technician on-the-way texts with a photo and ETA over iMessage

Who uses iMessage for on-the-way texts?

On-the-way texts suit companies that send staff into customers' homes: home-service, cleaning, pest control, appliance repair and moving companies. The customer sees a face and a first name in the same bubble as the arrival time, so they know who is about to knock instead of missing the window or leaving a stranger at the door.

The reply matters as much as the photo: a door code or “park on the side street” tends to reach the office, not the tech at the gate. ZeroSettle is not a fit for companies whose customers mostly use Android or who need a live map (see when ZeroSettle is not a fit). More service workflows are in 50 ways businesses use iMessage.

How iMessage on-the-way texts work, step by step

Your dispatch system makes one API call when a job goes en route; ZeroSettle carries the captioned photo out and the reply back, but does not watch your dispatch board.

1. At booking, the customer gives a mobile number for job updates; store that consent with the job. If the booking confirmation or reminder goes out from the same number, the thread exists before the job day.
2. When dispatch marks the job en route, your field-service software (or an automation step you build) calls POST https://portal.zerosettle.io/api/imessage/send with to, the tech's photo as image_b64, and the caption as text. If the customer has never replied to your number, the photo is refused with 403 attachment_before_reply, so send the caption alone. The call returns once the line hands the message to Apple: normally 2–5 seconds, at most about 105 seconds for a photo.
3. The photo and caption arrive as one bubble, “exactly as Messages shows a photo with a caption”. With the first message of a conversation, ZeroSettle also shares the brand name and photo you set (see what customers see).
4. The customer replies, and ZeroSettle posts a signed message.received event to your webhook about 1–2 seconds after the line receives it. A photo of the gate arrives with the file.
5. Your handler pushes the reply to the tech's job screen and sends a 👍 tapback, or a dispatcher answers in the ZeroSettle console.

Example conversation: an on-the-way text and a door code

The loop as the company sees it in the ZeroSettle console:

The door code reaches Ana's job screen while she is still driving. The first bubble has no tracking link on purpose: a first-time customer's iPhone would show it as plain text.

How do you send the photo and pass replies to the tech?

One small service does both: a send with image_b64 and a caption, and a receiver that verifies ZeroSettle's signature and forwards replies, following the send docs and webhook steps.

Prepare each headshot once. A JPEG within 5 MB and 2,048 px on its long edge goes out exactly as stored; HEIC, WebP, TIFF, BMP or anything over 2,048 px is re-encoded to JPEG, which strips EXIF and GPS, and an image over 5 MB is refused (more in what an iMessage API can send). A pass-through JPEG keeps its metadata, and an iPhone photo taken while the Camera has location access embeds where it was shot, per Apple's guide to photo location metadata, so strip it when you store the file.

# on_the_way.py: run with uvicorn on_the_way:app --port 8100
import base64, hashlib, hmac, json, os, time
import requests
from fastapi import BackgroundTasks, FastAPI, Request, Response

BASE = "https://portal.zerosettle.io"
AUTH = {"Authorization": f"Bearer {os.environ['ZEROSETTLE_TOKEN']}"}
SECRET = os.environ["ZEROSETTLE_WEBHOOK_SECRET"]
app = FastAPI()
seen: set[tuple[int, str]] = set()             # use your database in production

def send_on_the_way(to: str, caption: str, photo_path: str) -> dict:   # call from your en-route hook
    with open(photo_path, "rb") as f:
        image = base64.b64encode(f.read()).decode()
    r = requests.post(f"{BASE}/api/imessage/send", headers=AUTH, timeout=120,
                      json={"to": to, "image_b64": image, "image_format": "jpg", "text": caption})
    if r.status_code == 403 and r.json()["error"]["code"] == "attachment_before_reply":
        r = requests.post(f"{BASE}/api/imessage/send", headers=AUTH, timeout=120,
                          json={"to": to, "text": caption})   # never replied: caption alone
    return r.json()

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

def open_job_for(handle: str) -> dict | None: ...   # your dispatch DB
def push_to_tech(job: dict, m: dict) -> None: ...    # your field-service app's job notes

def forward(m: dict) -> None:
    job = open_job_for(m["handle"])
    if job is None:
        return                                 # a dispatcher answers in the console
    push_to_tech(job, m)
    requests.post(f"{BASE}/api/imessage/reactions", headers=AUTH, timeout=30,
                  json={"message_id": m["id"], "reaction": "like"})

@app.post("/webhook")
async def webhook(req: Request, tasks: BackgroundTasks):
    raw = await req.body()
    if not verify(SECRET, req.headers.get("X-ZeroSettle-Signature", ""), raw):
        return Response(status_code=401)
    ev = json.loads(raw)
    m = ev.get("message")
    if ev["event"] != "message.received" or m is None:
        return {"ok": True}                    # your own sends echo back as message.sent
    if (m["id"], ev["event"]) in seen:
        return {"ok": True}                    # retries carry the same id and event
    seen.add((m["id"], ev["event"]))
    tasks.add_task(forward, m)
    return {"ok": True}

Register the receiver with PUT /api/imessage/webhook and store the secret, which is shown once. ZeroSettle expects a 2xx within 10 seconds and retries after 1, 5 and 20 seconds, so forwarding runs after the response. On a failed send, wait retry_after_s on new_contact_limit, retry line_busy after 2 seconds, wait for the customer's reply on awaiting_reply, send the caption alone on attachment_before_reply, and never retry recipient_opted_out.

Which limits and consent rules apply to on-the-way texts?

An on-the-way text costs no new-contact allowance when the customer already has a thread with your number; a first-time customer's first message counts once. The pinch point is the morning rush.

Source: ZeroSettle iMessage API docs, “Errors, limits, and compliance”. A new contact is a handle the line delivers a text, voice message or photo to first.

The limit math for a morning dispatch

Take 12 techs whose first jobs go en route between 7:45 and 8:00 AM, each to a first-time customer.

• Confirmation sent at booking: every customer already has a thread, so all 12 texts go out as dispatched at no new-contact cost; customers who replied to the confirmation get the photo, the rest the caption alone. On Growth, each comes from the number the confirmation came from.
• On-the-way text is the first message, on Pro: it goes as the caption alone, since the customer has never replied. 5 go out; the 6th to 12th return 429 new_contact_limit with retry_after_s and wait for the 3 AM Eastern reset, so Pro can't cover this case.
• Same case on Growth with 3 numbers: each number takes 3 new contacts per 15 minutes, so the first 9 captions go out as dispatched and the last 3 wait until about 15 minutes after the first send. ZeroSettle refuses a new contact only when every number is full.
• Across a day on Pro: the 6th first-time customer waits for the 3 AM Eastern reset.

So send the confirmation at booking time: it still counts once, but on the day the customer books, not in the dispatch window. Ask for a reply in it (“Reply with any gate code or parking note”): a reply lets the tech's photo go later, and on every plan an unanswered confirmation plus an unanswered reminder makes the on-the-way text return 403 awaiting_reply, until the customer sends anything back, a tapback included.

One trap is specific to arrival texts: a text with the word STOP in it opts the customer out, and directions use it (“stop at the second gate”). Texts and tapbacks to that customer then return 403 recipient_opted_out from every number on your account, and the console disables the conversation, until they text START. Their messages still reach your webhook, so the tech still gets the directions; your number just can't text back.

When ZeroSettle is not a fit for on-the-way texts

ZeroSettle is the wrong tool for arrival texts in these cases:

• You need a live GPS map. ZeroSettle sends a photo and text, not a map. Send your field-service app's tracking link once the customer has replied or saved your number; before that, their iPhone shows it as plain text and the API returns warning.code: "link_not_tappable".
• Many customers use Android. There is no SMS fallback. iMessage only reaches iPhone and other Apple products, and texts to other phones go as SMS or RCS, as Apple explains. You can check whether a number is on iMessage before texting it, and the check sends nothing.
• You want texts to go out with no integration. ZeroSettle doesn't watch your dispatch board or schedule sends; without code or an automation step, a dispatcher sends each photo and caption from the console by hand.
• Techs insist on texting from their own phones. Replies to personal numbers never reach dispatch.
• You need proof the customer saw the ETA. The API reports message.sent and message.failed, not delivered or read status.

Related patterns: proof-of-delivery photos and technicians' voice notes as job reports.

How much do on-the-way texts cost?

On-the-way texts cost only the plan price: ZeroSettle charges no per-message fees and doesn't cap how many messages you send; only new contacts, unanswered messages and photos to customers who never replied are limited.

Both include a 30-day money-back guarantee on the subscription; this flow uses no AI credits. See ZeroSettle pricing, get a number, or read the API docs.