SMS API: send a text, prove it arrived

Paste this into ChatGPT, Claude, Lovable or Cursor inside your app's project.

You are adding SMS to my app using Call Bullet (UK business texting with delivery proof).
Docs: https://callbullet.com/developers/api/sms · Spec: https://callbullet.com/openapi.json
Base URL https://callbullet.com/api/public/v1 · Auth: Authorization: Bearer <key>, server-side only (env CALL_BULLET_API_KEY). Never call it from the browser.

Ask me ONLY for: the API key (the "Full SMS app" preset covers every brand it is scoped to) and my test mobile. Everything else you discover.

1. GET /sms/workspaces → every brand this key can use, with credits, senders, templates, live_ready and suggested_sender_names. Never guess IDs.
2. For each brand: GET /sms/readiness?workspace_id=… . Follow next_step. Show me human_actions in plain words (buy credits, verify mobile, consent) with their links.
3. No sender → POST /sms/senders {workspace_id, kind:"alphanumeric", value, use_case, sample_message}. Names are 3–11 letters/numbers/spaces; on 422 invalid_sender_name use error.suggestions and tell me what you picked. New senders are "pending" until Call Bullet approves (usually one working day). Sender names can't take replies.
4. Templates → GET /sms/templates; create/update with POST /sms/templates and PATCH /sms/templates/{id} using {{customer_name}}, {{job_ref}} variables. 409 = exists → PATCH. Keep under 160 plain characters.
5. Simulated test now → POST /sms/messages with "test":true, template_id and realistic demo variables. Show me the rendered body, segments and timeline. Nothing is sent, no credits.
6. Real test to ANY number the owner chooses, free, even while the sender is pending → POST /sms/test-mobiles {workspace_id, phone}; ask for the 6-digit code that number receives; POST /sms/test-mobiles/verify {workspace_id, phone, code}. Then send with "test":"live". Pending senders arrive from "CallBullet" prefixed "[Test] <Brand>:". Max 20 a day per brand. Never send live to customers until the owner has reviewed every template.
7. Webhooks → POST /sms/webhooks {workspace_ids:[…], url:"https://<my app>/api/call-bullet", events omitted = all}. Store signing_secret (shown once); verify X-Call-Bullet-Signature = "v1=" + HMAC-SHA256(secret, X-Call-Bullet-Timestamp + "." + raw body). Handle sms.sent, sms.delivered, sms.failed, sms.clicked, sms.sender.approved (resume go-live automatically), sms.sender.rejected (tell me the reason).
8. Production sendSms({workspace, to, templateId, variables, reference, tags, campaign}) → POST /sms/messages with Idempotency-Key = stable reference ("job-1042-booked"), external_ref = my job/lead ID, metadata {job_id, lead_id, customer_id, customer_name}, tags, campaign, track_links:true when there is a link. Store the returned Call Bullet message id on my job/lead record. Normalise UK numbers to +44. Only send live once readiness.live_ready is true (every workspace includes 25 free credits; live texts need an approved sender).
9. Errors carry next_step and sometimes human_action: 402 insufficient_credits, 422 sender_not_ready | opted_out | compliance_blocked | missing_variables | invalid_phone, 429 → Retry-After. 403 forbidden with missing_permission → existing keys can be upgraded in place; do not ask for a new key. Ask me to click Edit permissions on the same key, choose Full SMS app and Save, then retry.

## Build an SMS accountability page in my app (single source of truth)
Make it unforgivingly simple and detailed. Plain English, no jargon, times in Europe/London.
- Workspaces: if the key covers more than one brand, group, location or workspace, add a switcher (tabs for a few, a dropdown/search for many; hide it when there is only one). Never mix workspaces' data. Adapt to how my app is structured — don't assume brands.
- Inside each workspace, sub-sections:
  a. Sender name — the name customers see, its status (pending / approved / rejected + reason) and what that means, and whether replies are possible.
  b. Templates — every template with a rendered preview using sample variables, characters, segments/credits per send, category, and a "Send test" button (any number, verified by code as in step 6).
  c. Messages log — every text, newest first, searchable by phone number, job/lead reference, customer, campaign, template, status and date (GET /sms/messages?workspace_id&to&external_ref&campaign&template_id&tag&status&from&to_date&test=all). Each row: date/time, recipient, linked job/lead/customer in my app (link to it), template, sender, status badge, credits_used. Clicking opens the timeline from GET /sms/messages/{id} (queued → sent → delivered/failed, clicks, linked callbacks) with error reasons in plain words. Label tests clearly.
  d. Usage & credits — current balance, credits used this period, texts / delivered / failed / delivery rate, breakdowns by day, template and campaign from GET /sms/usage?workspace_id&from&to_date&group_by=day|template|campaign|status|tag|sender, and the full credit history (top-ups, starter grant, sends, refunds with running balance) from GET /sms/credits/ledger?workspace_id&page. Warn when the balance is low. CSV export for the log, usage and ledger.
- On every job/lead/customer page, show the texts linked to it (filter by external_ref).
- Keep it in sync with webhooks plus a fallback sync every few minutes using updated_since.

10. Finish with a table per workspace: sender + status, templates, simulated test, live test result (delivered?), webhook id, accountability page URL, and what I still need to do.