Qualify Leads With an AI Agent Over iMessage

Why qualify leads with an AI agent over iMessage?

Because the first few questions on a new lead are the same every time, and an agent can ask them the minute the lead arrives while your reps spend their calls on people who are ready to buy. Where is the project, when does it need to happen, what budget is realistic, what exactly do they need? Those answers decide whether a lead gets a rep's hour or a polite referral.

iMessage suits this because it is where people already answer friends, so a short question from a business number reads like a normal conversation. ZeroSettle gives you a dedicated number on real iMessage, running on Apple hardware we operate for you in a server facility, and either its hosted agent answers on that number or your own code does. iMessage reaches people on Apple devices; a lead on Android won't get it (SMS fallback is a limited pilot ZeroSettle has to enable per account), so keep a call or email path for those leads.

This post is for sales teams and agencies that get more inbound leads than reps can call. If speed is your main problem, read speed to lead for home service businesses first; for the wider funnel, see iMessage for lead generation.

What should the agent qualify on?

Qualify on the few facts that decide what a rep does next, usually budget, timeline, location and need, and decide in advance what counts as a pass for each. Vague criteria give vague conversations. Write each one as a question the agent can ask in plain words, an answer that qualifies, and what to do when it doesn't.

Ask one question per text. Sharing the starting price first (rather than asking “what's your budget?”) gives the lead something concrete to react to and saves a round trip.

How do you write the qualifying script?

Write it into the agent's business_context the way you would brief a new SDR: who it is texting and why, the criteria in order, what it may share, when to send the booking link, and what it must never say. The hosted agent uses it exactly as written, never invents facts it doesn't give, and the field holds up to 40,000 characters.

You are Cedar & Pine Remodeling's automated assistant. You text people who
asked for a remodel quote on cedarpine.example or a lead form. Your job is to
learn four things, one question at a time, then invite qualified leads to
book a free in-home design visit.

Ask in this order, skipping anything they already told you:
1. Location: is the home in the Denver metro? Check the service-area file.
2. Need: kitchen, bath, or other; cosmetic or layout changes.
3. Timeline: when they want to start.
4. Budget: share the starting price for their project from the pricing
   file and ask whether it fits. Never quote a final price.

Qualified = in the service area + kitchen or bath remodel + start within
6 months + budget at or above the starting price. Only then send the visit
link. Not qualified: be kind, say what we can't do, and give the referral
or check-back offer below. Never argue.

If they ask for a person, or ask about permits, financing approval or
anything not in these notes or the files: say a project designer will call
them within one business day.
If anyone sincerely asks whether you are a person, say you are Cedar &
Pine's automated assistant.
Never promise dates, discounts or prices that aren't in the files.

Example:
Them: how much for a kitchen?
You: Full kitchen remodels here usually start around $45,000. Is that in
the range you had in mind?

Keep the voice out of it; the personality setting handles tone. A qualifying agent for a sales team usually wants professional (“polished, no slang or emoji”, in the docs' words).

Which agent settings fit qualification?

A qualifying agent needs six settings beyond the business context: who answers, the voice, the speed, the goal and link, the opener, and the follow-up triggers. Each is a field on PUT /api/imessage/agent and a box in the console's Messaging tab (walkthrough).

From code, send the script from a file so quoting stays sane. Only the fields you send change:

BASE=https://portal.zerosettle.io   # ZEROSETTLE_TOKEN is exported in your shell
jq -n --rawfile ctx qualify.txt '{
  managed_by: "zerosettle", business_context: $ctx,
  personality: "professional", response_time: "instant",
  goal: "demo_booked", link: "https://cedarpine.example/visit",
  timezone: "America/Denver",
  triggers: [
    {repeat: "once", after_days: 1, at: "morning",
     instruction: "If they have not replied, send one short follow-up that asks your last question again in different words."},
    {repeat: "once", after_days: 4, at: "afternoon",
     instruction: "If they qualified but have not booked, remind them once that the visit link is there. If they said no or not now, send nothing."}]}' |
curl -X PUT "$BASE/api/imessage/agent" \
  -H "Authorization: Bearer $ZEROSETTLE_TOKEN" -H "Content-Type: application/json" -d @-

Triggers land at a random moment in their window (morning is 9 to 11 AM in your timezone) and follow every sending rule. One matters here: a contact who has never replied gets at most 2 messages, and texts sent within 5 minutes of the first count as one. A two-text opener plus the next-morning follow-up uses both; anything after that waits for their reply. Lead nurture without getting your number flagged covers follow-up cadence in depth.

What should the agent read and look up?

Give it files for what it should know and an MCP server for what it should look up. Files are price lists, FAQs, service-area lists and policies (PDF, Excel, CSV, Word or text, up to 10 MB each and 10 per line group, sharing a space of 20,000 tokens); the agent reads every file before every answer. Keep prices in a file rather than the script, so updating them is a re-upload.

curl -X POST "$BASE/api/imessage/agent/files" \
  -H "Authorization: Bearer $ZEROSETTLE_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"pricing.pdf\", \"data_b64\": \"$(base64 < pricing.pdf | tr -d '\n')\"}"

curl -X POST "$BASE/api/imessage/agent/mcp" \
  -H "Authorization: Bearer $ZEROSETTLE_TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://mcp.cedarpine.example/mcp", "token": "YOUR_SERVER_TOKEN"}'

An MCP server lets the agent answer “do you have anything next week?” with real times instead of just the link. ZeroSettle lists the server's tools and turns on the ones that only read; a tool that changes something, such as booking a slot, starts off, because anyone who texts the number could ask the agent to use it. A read-only check_availability plus your booking link is the safe default. Details are in the AI agent docs.

How do leads get into the conversation?

Either the lead texts your number first, or you start the conversation with someone who gave you their number for this. Both are fine; the first is better.

• Text first. Put a “Text us” button (an sms: link) on the form's thank-you page, your ads and your site. People who text first never count toward the new-contact limit, and links you send them are tappable from the start. See how to get customers to text you first.
• You start. When a form submission with consent language arrives, start the agent on that number. It sends your first_message and answers whatever comes back.

curl -X POST "$BASE/api/imessage/agent/start" \
  -H "Authorization: Bearer $ZEROSETTLE_TOKEN" -H "Content-Type: application/json" \
  -d '{"to": "+13035550147", "name": "Maya"}'

Conversations you start count as new contacts: 5 a day per number on Pro, 50 a day per number on Growth (and 3 per 15 minutes). Over the limit you get 429 new_contact_limit with retry_after_s. Keep links out of the opener: until the lead replies or saves your number, a link from your number shows as plain text they can't tap (why). For ad leads, texting Facebook and Instagram lead-ad leads shows the wiring, and agencies on GoHighLevel can follow the GoHighLevel setup guide.

What does a qualifying conversation look like?

A good one is short, asks one thing at a time, discloses honestly, and only sends the link once the lead has replied and qualified.

How do you hand hot leads to a person?

With the hosted agent, the booking itself is the cleanest handoff: the lead picks a time on your calendar and a rep shows up prepared. For everything else there are three routes, and the main constraint is that the hosted agent's setting covers a whole line group, not one conversation.

Sending your own text through POST /api/imessage/send while the agent manages the group does go out, but the agent reads it as its own and answers the reply. That's fine for a nudge, not for a takeover. GET /api/imessage/agent/started lists the conversations you opened with replied on each, which is a quick way to see who engaged. CRM setup is in the CRM integrations docs.

How do you score leads with your own code?

Run your own model behind the webhook (managed_by: "api") and add a second, structured call after each reply that scores the lead from the thread and posts the result to your CRM. Your code then owns each conversation, so a rep can take over one lead while the model keeps answering the rest. The reply loop itself is in Building iMessage Agents; this is the scoring step.

// src/score.ts
import Anthropic from "@anthropic-ai/sdk";
import { z } from "zod";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { zs } from "./zerosettle.js"; // the fetch wrapper from the agent guide

const claude = new Anthropic();

const LeadScore = z.object({
  in_service_area: z.enum(["yes", "no", "unknown"]),
  timeline: z.enum(["within_6_months", "later", "unknown"]),
  budget_fits: z.enum(["yes", "no", "unknown"]),
  need: z.string(),
  score: z.enum(["hot", "warm", "cold", "disqualified"]),
  summary: z.string(),
});

const RUBRIC = `You score inbound remodeling leads from an iMessage thread.
Hot: Denver metro, starting within 6 months, budget at or above the starting price, clear project.
Warm: two or three of those. Cold: one or none so far.
Disqualified: outside the service area, or they asked us to stop.
Use only what the lead said. Answer "unknown" when they haven't said.`;

export async function scoreLead(handle: string) {
  const q = new URLSearchParams({ handle, after_id: "0", limit: "500" });
  const rows: any[] = (await zs(`/api/imessage/messages?${q}`)).messages;
  const transcript = rows
    .filter((r) => r.status !== "failed" && r.text)
    .map((r) => `${r.direction === "in" ? "Lead" : "Us"}: ${r.text}`)
    .join("\n");

  const res = await claude.messages.parse({
    model: "claude-opus-5-5",
    max_tokens: 16000,
    output_config: { effort: "low", format: zodOutputFormat(LeadScore) },
    system: RUBRIC,
    messages: [{ role: "user", content: transcript }],
  });
  return res.parsed_output; // null if it couldn't be parsed
}

Call it after each reply your agent sends, post the score to your CRM, and mark hot leads as owned by a person so your reply loop leaves them alone:

// src/handoff.ts
import { scoreLead } from "./score.js";

export const humanOwned = new Set<string>(); // persist this in real code

export async function afterReply(handle: string) {
  if (humanOwned.has(handle)) return;
  const s = await scoreLead(handle);
  if (!s) return;

  // Your CRM's own API; the URL is a placeholder.
  await fetch(`${process.env.CRM_URL}/leads/score`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.CRM_TOKEN}` },
    body: JSON.stringify({ phone: handle, ...s }),
  });

  if (s.score === "hot") {
    humanOwned.add(handle); // reply() returns early for these handles
    await fetch(process.env.SLACK_WEBHOOK_URL!, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text: `Hot lead ${handle}: ${s.summary}` }),
    });
  }
}

With the line group managed by API, the rep answers that lead from the console composer, Close, HubSpot or the GoHighLevel inbox, and the conversation keeps logging to the CRM. Two rules from the webhook and AI agent docs matter here: answer only message.received (your own sends come back as message.sent), and check STOP before any model call. Your model's bill is yours; texts from a line group managed by API use no credits (videos aside).

Should the agent say it is automated?

Yes when asked, and preferably up front. The hosted agent says it is your automated assistant when someone sincerely asks, and points anyone who wants no more texts to STOP. To disclose from the first text, say so in first_message, as the example does; it is sent both when you start a conversation and as the first answer to someone who texts first. With your own model, put the same rule in the system prompt. AI disclosure laws vary by place and change; this is not legal advice.

What does it cost?

The number is a subscription, and the hosted agent's texts use credits: one per text it sends. A conversation with a two-text opener and six one-text answers uses 8 credits. Free credits come once per account and never refill; packs are 1,000 for $50 or 5,000 for $200 and never expire.

Each number allows 10,000 messages a day, sent and received, with known contacts. The 30-day money-back guarantee covers the subscription.

For a team whose reps share the inbox, Growth's team members matter as much as its contact limit. Leads who text first don't touch the new-contact limit on any plan.

What mistakes should you avoid?

• Leaving the example context in place. Until you replace it, the agent talks about a made-up software business.
• Asking four questions in one text. People answer the last one. One question per text, in the order of what disqualifies fastest.
• Sending the link too early. In an opener it's untappable, and before qualification it books visits your reps shouldn't take.
• Prices in the script. Put them in a file and replace the file when they change.
• Turning on write tools casually. Anyone who texts the number can ask the agent to use them.
• Chasing silence. Two unanswered messages is the hard cap for a reason: repeated texts to people who never answer are the fastest way to get a number flagged by Apple, and then every send fails.
• Testing on leads. Text the number from your own iPhone with the questions real leads ask, including ones the context doesn't cover. It should say a person will follow up, not guess.

Ready to try it? Get a number, write the script, and run five test conversations before the first real lead.