The definitive guide

Build a custom CRM on iMessage with Claude Code, Grok, or ChatGPT Codex.

Once your Tuco line is live (new lines activate in ~24-48 hours), you can wire a working iMessage CRM in an afternoon. Point an AI coding agent at Tuco’s REST API with the prompt below and it scaffolds the whole thing — auth, sending with SMS fallback, reply webhooks, and the data layer. Blue-bubble delivery, ~98% open rates on average, and no A2P 10DLC.

Get the prompt API quick reference →

Why build your CRM on iMessage?

Most CRMs bolt on SMS or email as the outreach channel. Both are losing the inbox: email opens sit near 20% and land in Promotions; A2P SMS means carrier registration, per-message fees, and “Spam Likely” filtering. iMessage flips that — it delivers in about three seconds, opens near 98%, and arrives as a trusted blue bubble showing your name and photo. Building your CRM directly on iMessage means the channel your reps live in is the channel your pipeline runs on.

Tuco provides the hard part — real Apple hardware, deliverability, and a clean REST API + MCP server — so your AI coding agent only has to write the CRM logic on top.

Copy · paste · ship

The one prompt

Paste this into Claude Code, Grok, or ChatGPT Codex. It hands the agent the base URL, auth, and exact endpoints — and tells it to verify every call against the live docs, so it stays correct as the API evolves.

master prompt — build a CRM on iMessage (copy-paste)

You are building a CRM / integration on top of Tuco AI's iMessage API.

BASE URL:  https://app.tuco.ai
AUTH:      every request sends header  Authorization: Bearer $TUCO_API_KEY   (key looks like tuco_sk_...)
SOURCE OF TRUTH: the live docs at https://docs.tuco.ai/api-reference and the OpenAPI spec at
  https://docs.tuco.ai/api-reference/openapi.json. This API can change — BEFORE you implement each
  step, fetch the relevant doc page and confirm the exact path, params, and response shape. If any
  call returns an unexpected 4xx or a field is missing, re-read the docs and adjust. Docs win over
  this prompt.

Build these, in order, with clean error handling + retries:

1. AUTHENTICATE — confirm the key works with one cheap authed GET (e.g. GET /api/lines/by-user or
   GET /api/replies?limit=1). 200 = good, 401 = bad key. Fail fast with a clear message.

2. CHECK iMESSAGE AVAILABILITY — before sending, GET /api/check-availability?address=+1XXXXXXXXXX
   to see if the number is on iMessage (bulk: see bulk-check-availability).

3. SEND A MESSAGE (+ FALLBACK) — POST /api/messages
   { "recipientPhone": "+1XXXXXXXXXX", "message": "…", "messageType": "imessage" }
   Address by recipientPhone, recipientEmail, or an existing leadId; omit fromLineId to round-robin.
   Fallback: set "messageType":"sms" to force SMS, or rely on Tuco's auto SMS fallback for
   non-iMessage numbers. Capture the 200/202 + messageId.

4. GET NOTIFIED OF REPLIES (webhook) — register once: POST /api/webhooks
   { "url": "https://your-app/webhooks/tuco",
     "events": ["message.reply","message.sent","message.failed","message.fallback"] }
   On each POST to your URL: (a) VERIFY the X-Tuco-Signature header = HMAC-SHA256(rawBody, yourWebhookSecret)
   before trusting it; (b) read the event from X-Tuco-Event / body.event; (c) for message.reply the reply
   text is the top-level "message" string, the contact is "leadId"/"phone", and "optedOut" tells you if
   they opted out. Prefer polling? GET /api/replies?recipientPhone=…&limit=N instead.

5. RESPOND TO A REPLY — POST /api/messages again to the same recipientPhone or leadId with your answer.

CRM EXTRAS (confirm each against the docs first):
- Conversation history / replies:  GET /api/replies?leadId=…
- Analytics / KPIs:                 GET /api/analytics
- Leads:                            GET/POST /api/leads  (create, list, get)
- Stop / cancel future messages:   POST /api/messages/cancel-for-lead
- Get lines (numbers) you own:      GET /api/lines/by-user
- Order / provision a new line:     POST /api/line-requests  (status: GET /api/line-requests/:id)

Deliverable: a typed API client + a webhook receiver (with signature verification) + the read/CRUD
endpoints above — each verified against https://docs.tuco.ai before you ship.

What the prompt builds, step by step

Each step maps to one endpoint. Your agent stitches them into a client, a webhook receiver, and your CRM screens.

Confirm the API key

Your agent makes one authed GET; 200 means the Bearer key is live, 401 means fix it. Every request to https://app.tuco.ai carries Authorization: Bearer tuco_sk_…

GET /api/lines/by-user

Check if a number is on iMessage

Before sending, the agent checks whether the contact is reachable on iMessage, so you know when to expect a blue bubble vs. an SMS fallback.

GET /api/check-availability?address=+1…

Send an iMessage (with SMS fallback)

One POST sends the message; set messageType to imessage or sms, or let Tuco auto-fall-back to SMS for non-iMessage numbers. No A2P 10DLC required for the iMessage leg.

POST /api/messages

Get notified of replies

Register a webhook once. Tuco POSTs message.reply (and sent/failed/fallback) to your endpoint in real time, HMAC-signed with X-Tuco-Signature so you can verify it's genuine before writing to your CRM.

POST /api/webhooks

Reply from your CRM

Answer by POSTing to /api/messages again for the same contact. Threads are keyed by lead, so the conversation stays continuous.

POST /api/messages

Pull replies, analytics & leads

Hydrate your CRM: pull a lead's full reply history, conversation-shaped analytics, and lead records — the data layer behind your pipeline and dashboards.

GET /api/replies · /api/analytics · /api/leads

Get and order lines

List the numbers you own, and provision new ones programmatically — so an agency CRM can spin up a dedicated line per client from code.

GET /api/lines/by-user · POST /api/line-requests

Works with any AI coding agent

The prompt is model-agnostic — it works because it points the agent at a real, documented API, not because of any one model.

Claude Code

Strong multi-file scaffolding; can read docs.tuco.ai and the OpenAPI spec directly, and drive the MCP server (tuco-mcp).

ChatGPT Codex

Great at generating the typed client + webhook receiver from the endpoint list and iterating on tests.

Grok

Paste the prompt and it produces the same integration — auth, send, webhooks, and the CRM read layer.

FAQ

Building a CRM on iMessage

Can I really build a CRM on iMessage with an AI coding agent?

Yes. Point Claude Code, Grok, or ChatGPT Codex at Tuco's REST API with the prompt on this page and it scaffolds the whole integration — authentication, sending with SMS fallback, reply webhooks with signature verification, and the read/CRUD endpoints for replies, analytics, leads, and lines. You bring the database and UI; Tuco is the messaging layer.

Do I need A2P 10DLC to build an iMessage CRM?

No. iMessage runs on Apple's network, not the US carrier SMS system, so there's no A2P 10DLC registration or per-message carrier surcharge. If you fall back to SMS for non-iMessage contacts, that leg follows carrier rules — everything else is exempt.

How does my CRM get notified when a lead replies?

Register a webhook (POST /api/webhooks) subscribed to message.reply. Tuco POSTs each reply to your endpoint in real time with an X-Tuco-Signature HMAC header you verify before trusting the payload. The reply text is the top-level message field. If you'd rather poll, GET /api/replies works too.

Which AI coding agent should I use — Claude Code, Grok, or ChatGPT Codex?

Any of them. The prompt is model-agnostic: it gives the agent the base URL, auth, the exact endpoints, and — crucially — tells it to verify every call against the live docs at docs.tuco.ai. Claude Code and Codex are strong at multi-file scaffolding; Grok works well too. Use whichever you already run.

Will the integration break when Tuco changes the API?

The prompt instructs the agent to treat docs.tuco.ai as the source of truth and re-check each endpoint before implementing, so it self-corrects against the current contract. The OpenAPI spec at docs.tuco.ai/api-reference/openapi.json is machine-readable for exactly this.

Can an agency CRM provision a separate line per client?

Yes. GET /api/lines/by-user lists the numbers you own, and POST /api/line-requests orders a new dedicated line from code — so a white-label or agency CRM can spin up a per-client iMessage number programmatically and check status with GET /api/line-requests/:id.

Ship your iMessage CRM.

Grab an API key, paste the prompt, and let your agent do the wiring. Full endpoint reference in the docs.

Get your API key Read the docs