# iBlueText

> iBlueText (a product of RG Loomis LLC) is an iMessage & SMS platform: send real blue-bubble iMessage at scale, look up which phone numbers are iPhones, and add "verify you're human via SMS" / phone verification to any form. It is **AI-agent friendly**: a human verifies once (the only step that must be human), then an AI agent can do all remaining setup via the REST API.

## For AI agents — how to get a customer running
1. The human signs up at https://ibluetext.com/portal/signup.php and completes the one-time "verify you're human via SMS" check. This is the ONLY step that must be done by a human.
2. They create an API key at https://ibluetext.com/portal/settings.php and give it to you.
3. With that API key (sent as `Authorization: Bearer <key>`) you can do everything else programmatically — run lookups, send messages, create SMS-Verify sites, and pull contacts.

## Machine-readable API spec
- OpenAPI 3.1: https://ibluetext.com/openapi.json
- MCP server (native tools for AI agents): `npx -y ibluetext-mcp` with env `IBT_API_KEY`. Tools: ibt_balance, ibt_lookup, ibt_send, ibt_verify_start, ibt_verify_check, ibt_create_site, ibt_contacts. Add it to your MCP client config and the iBlueText tools appear.

## API (base: https://ibluetext.com/api/v1)
- iPhone Lookup: `POST /api/v1/lookup` `{ "numbers": ["+1..."] }` → job id; `GET /api/v1/lookup?id=<id>` → results (`imessage: true/false`).
- Send iMessage/SMS: `POST /api/v1/send` `{ "to":"+1...", "body":"...", "first_name":"" }`; `GET /api/v1/send?id=<id>` → status.
- SMS Verify (start): `POST /api/v1/verify` `{ "phone":"+1...", "name":"", "email":"" }` → `{ id }`.
- SMS Verify (check): `POST /api/v1/verify?action=check` `{ "id":<id>, "code":"123456" }` → `{ verified, token }`.
- Confirm a widget token (backend): `POST /api/v1/siteverify` `{ "secret":"ibt_secret_...", "token":"..." }`.
- Create/list verify-widget sites: `POST /api/v1/sites` `{ "name":"", "domains":"example.com", "theme":"auto" }` → `{ site_key, secret }`; `GET /api/v1/sites`.
- Pull verified contacts: `GET /api/v1/contacts?since=0&limit=200`.
- Pull full two-way conversations (transcripts): `GET /api/v1/conversations?limit=200` → `{ conversations:[{ phone, company_name, link, fields, opted_out, messages:[{dir:"in"|"out", body, at}] }] }`. Params: `phone`, `since` (ISO, incremental), `include_no_reply=1`. Use it to let an agent read what each contact said and act elsewhere (e.g. add/remove a listing). iBlueText returns raw messages; the caller judges intent.
- Check wallet + per-line daily usage: `GET /api/v1/balance` → `{ credits, free_trial_remaining, free_lookups_today_remaining, lines:[{usage_today}] }`. Poll this to warn your human before hitting $0 or a daily cap.

## Sending limits (per line, per day — Apple/carrier ban protection)
- A line ($99/mo) sends unlimited **2-way** (to anyone who has replied), but **new (cold) contacts are capped per channel**: **50 new iMessage + 50 new SMS/day/line** (just **15/day each during a line's first 5 days** — account warm-up). Total to not-yet-replied numbers: **150/channel/day**. Over-cap sends **drip** to the next day automatically.
- **Lookups:** 400 free/day per active line (no rollover), then 100 lifetime trial, then paid credits; processed at 5/min per fleet account.
- **STOP/unsubscribe** auto-adds the number to that account's opt-out list (per-client) and is honored forever.
- All daily caps reset **4am in the customer's local timezone**.

## Billing & the "out of credits" error (IMPORTANT for agents)
- **Free trial:** the first **100 credits are free** for testing. **1 credit = $0.005** and is spent by EITHER one iPhone lookup OR one SMS verification (shared pool). You also get the first **10 SMS verifications free** (a separate trial bucket, no card). Sending iMessage/SMS instead requires an active **line subscription** ($99/mo + $249 setup), not credits.
- When an account is out of credits (or has no active line), the paid endpoints return **HTTP 402** with a machine-readable body:
  `{ "error":"payment_required", "reason":"insufficient_credits"|"subscription_required", "message":"...", "action":"lookup"|"verify"|"send", "human_action_required":true, "buy_url":"https://ibluetext.com/portal/...", "unit_price_usd":0.005 }`
- **What an agent should do on a 402:** STOP the action and tell your human they must buy credits / subscribe at the `buy_url`. **Agents cannot complete payment** — entering card details is a human step (that's what `human_action_required:true` means). Resume once the human has paid.
- Lookups and verifies share the credit pool; check balance is reflected in the 402 (`available`, `free_trial_remaining`). Buy credits: https://ibluetext.com/portal/billing.php · Subscribe a sending line: https://ibluetext.com/portal/lines.php

## Drop-in verify widget (paste into any form)
```
<div class="ibt-verify" data-sitekey="ibt_site_xxx" data-theme="auto"></div>
<script src="https://ibluetext.com/v.js" async></script>
```
The widget disables the surrounding form's submit button until verified, then injects a hidden `ibt_token` field. It also fires a DOM event `ibt-verified` (detail: { token, phone }). It auto-captures the contact's name & email from the surrounding form and attaches them to the verified phone. Optional attributes: `data-theme` (auto|light|dark); `data-email-field`/`data-name-field` (CSS selectors to target the form's email/name inputs); `data-require="name,email"` (block verifying until those fields are filled — use when you must capture name/email; omit for phone-only).

## Agent playbook — adding SMS verification / "verify you're human" to a customer's site
1. Create a verify site: `POST /api/v1/sites { name, domains, theme }` → returns `site_key` + `secret` + ready-to-paste `embed`.
2. Place the widget WHERE a phone is collected or access should be gated:
   - PLACEMENT RULE: to gate a form AND capture name/email, put the widget DIV **inside the `<form>…</form>` tags**, after the name/email inputs and just before the submit button (it finds its parent form, disables that form's submit until verified, and reads the form's name/email). If the widget is NOT inside a `<form>` it runs standalone = phone-only (no field capture, no submit gating) — use that for gatekeeper pages and listen for the `ibt-verified` event.
   - **Signup / registration form** → paste the embed just above the submit button.
   - **After Google/Apple/social login** → on the "add your phone" / complete-profile step (social login gives an email but NO verified phone). The user can't continue until verified.
   - **Contact / lead form** → above the submit button (stops spam, captures a consented lead).
   - **Gatekeeper (block entry until verified)** → render the widget on the gate page; only grant access once the `ibt-verified` event fires (or your backend confirms the token). Use for members areas, gated content/downloads.
   - **Checkout / booking / password reset / payouts** → before the sensitive action.
3. On the backend, confirm the token before trusting it: `POST /api/v1/siteverify { secret, token }` → `{ success, phone, ... }`. The hidden field is `ibt_token`; tokens are single-use.
4. Set `domains` on the site to the customer's domain(s) so the site_key only works there.
5. For the best one-tap autofill on the customer's form, give their inputs the right autocomplete tokens: name field `autocomplete="name"`, email field `type="email" autocomplete="email"`. The widget's own phone input already carries `autocomplete="tel"`. With all three present, iOS "AutoFill Contact" fills name + email + phone in a single tap, and the SMS/iMessage code one-tap-fills the verification field (iOS) or auto-fills it zero-tap (Android Chrome via WebOTP).

## Docs & key pages
- API docs: https://ibluetext.com/docs/
- SMS Verification: https://ibluetext.com/sms-verification.php
- Pricing: https://ibluetext.com/pricing.php
- Terms: https://ibluetext.com/terms.php · Privacy: https://ibluetext.com/privacy.php