# mitsitik.io — agent-native telephony (Israel-first)
> Build phone apps (IVR, call routing, WhatsApp/SMS, AI receptionist soon) on Israeli numbers.
> Designed to be driven by AI agents: few verbs, strict schemas, self-describing limits.
catalog_version: 1.0.0

## Auth
All /v1 endpoints: header  Authorization: Bearer <API_KEY>

## Core idea
A phone number points at an "app". An app is a JSON document of named "sections";
each section is an ordered list of "steps" (verbs). "main" is the entry section.
Calls run the steps; gather branches on keypress; goto jumps between sections (loop-guarded);
variables captured with store_as are reused via {templating}.
Built-in vars: {caller} {called} {time}, gather captures under {input.NAME}, webhook responses under {NAME.field}.

## Verbs (v1)
- play: Play an uploaded audio recording to the caller.
    fields: recording: string (uploaded recording id)
- say: Speak text to the caller via TTS (Hebrew-first). No audio file needed.
    fields: text: string; language="he"; voice?: string  — spoken via TTS, no file needed
- gather: Play a prompt and collect DTMF keypresses; branch per key; capture multi-digit input.
    fields: say|play: prompt; digits: number | {min,max}; terminator?: "#"; timeout_s=7; retries=2; store_as?: var (capture multi-digit input); on: {"1":[steps],...}; on_invalid?: [steps]; on_timeout_final?: [steps]
- forward: Ring one or more numbers (serial hunt or parallel), with caller-ID passthrough and no-answer fallback. cli is limited by Israeli law to "caller" (follow-me), "own", one of your numbers, or a verified external number.
    fields: to: phone | [phones]; strategy: "serial"|"parallel"; ring_s=25; cli: "caller"|"own"|<your number or verified CLI> (Israeli reg 69b: arbitrary caller-ID is rejected at app creation); record?: bool; on_no_answer?: [steps]
- send_sms (side-effect, no media): Send an SMS (fire-and-continue).
    fields: to: phone | {var}; text: string
- send_whatsapp_template (side-effect, no media): Send an approved WhatsApp template message (fire-and-continue).
    fields: to: phone | {var}; template: string; params?: {k:v}
- webhook (side-effect, no media): POST/GET to an external URL mid-flow; capture the JSON response into a variable.
    fields: url; method="POST"; template?: {json body}; store_as?: var (captures JSON response); timeout_s=6; on_error?: [steps]
- record_call: Record the call from this point; set retention (default 730 days).
    fields: retention_days=730; consent_notice?: recording
- hangup: End the call.
    fields: (no fields)
- schedule (side-effect, no media): Route to a section by time-of-day/day-of-week; else a default section.
    fields: timezone="Asia/Jerusalem"; windows: [{days:"0-4",from:"08:30",to:"19:00",goto:section}]; default:{goto:section}  (0=Sunday)
- goto (side-effect, no media): Jump to a named section (guarded by max_visits to prevent loops).
    fields: section: string; max_visits=5 (loop guard)
- ai: PREVIEW: conversational AI voice turn (STT->LLM->TTS). Inert until keys are provisioned; runs on_unavailable meanwhile.
    fields: 

## Resources (REST)
- GET   /v1/capabilities            -> catalog + THIS tenant's limits (e.g. intl dialing on/off)
- POST  /v1/apps {name, doc}        -> validate + store an app (422 with details if invalid)
- GET   /v1/apps , GET /v1/apps/:id
- PATCH /v1/apps/:id {doc?, name?}  -> edit a flow in place (prior version archived, version bumps)
- GET   /v1/apps/:id/versions       -> version history
- GET   /v1/numbers                 -> your numbers
- POST  /v1/numbers/:e164/app {app_id} -> attach an app to a number
- GET   /v1/calls , GET /v1/calls/:id  -> call log + full step-by-step trace of any call
- GET   /v1/recordings              -> recording metadata
- GET   /v1/recordings/:id/audio    -> download the recording (mp3)
- POST  /v1/media {name, format, data_base64} -> upload a greeting; use its id in play.recording
- GET   /v1/media                   -> your uploaded greetings
- GET   /v1/usage , GET /v1/usage/ledger -> metered usage summary + itemized ledger (with costs)
- GET   /v1/billing                 -> credit balance, status, top-up/invoice history, alerts, details
- GET   /v1/alerts                  -> credit alerts raised (75% / 90% / 100% of credit used)
- PATCH /v1/billing/details {billing_name?, billing_email?, business_id?, alert_webhook_url?} -> invoice details + where to POST credit alerts

## Example app (Hebrew order-status IVR)
{
  "main": [
    { "verb": "schedule", "windows": [{"days":"0-4","from":"08:30","to":"19:00","goto":"menu"}], "default": {"goto":"closed"} }
  ],
  "menu": [
    { "verb": "gather", "say": "לשירות הקישו 1, למכירות 2", "digits": 1,
      "on": { "1": [{"verb":"goto","section":"support"}], "2": [{"verb":"forward","to":["+972500000000"],"cli":"caller"}] } }
  ],
  "support": [
    { "verb": "gather", "say": "הקישו מספר הזמנה ולסיום סולמית", "digits": {"min":4,"max":8}, "terminator":"#", "store_as":"order" },
    { "verb": "webhook", "url": "https://your.erp/status", "template": {"order":"{input.order}"}, "store_as":"r" },
    { "verb": "say", "text": "סטטוס: {r.text}" },
    { "verb": "send_sms", "to": "{caller}", "text": "מעקב: {r.link}" },
    { "verb": "hangup" }
  ],
  "closed": [ { "verb": "say", "text": "אנחנו סגורים כרגע" }, { "verb": "hangup" } ]
}

## Notes
- Hebrew-first: say/gather prompts and voices support Hebrew (a gap in every US AI-voice platform).
- Fraud rails: international dialing is OFF by default per tenant; hard spend caps apply.
- Coming: the "ai" verb — a conversational AI receptionist as one JSON step.