> ## Documentation Index > Fetch the complete documentation index at: https://developers.mihu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bulk-sync templates for a WABA from Meta into local DB > Pulls all templates Meta has on file for the given waba_id and upserts them locally (matched by Meta template id). Walks Meta's pagination internally (capped at 10 pages, ~250 templates per WABA). **When to call this:** - **Bootstrap** — once after linking a WABA, to import templates you created in Meta Business Manager. - **Periodic refresh** — to pick up status changes, edits made in Meta Business Manager, or templates created outside this API. - **NOT needed after POST /templates** — that endpoint already stores the template locally; only individual status changes need /sync. **Idempotent:** safe to re-run. Existing rows are updated in place; new rows inserted; nothing is deleted (templates removed from Meta remain locally with their last-known status — call DELETE /templates/{uuid} to clean up). ## OpenAPI ````yaml https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/templates/sync openapi: 3.0.0 info: title: Mihu API Documentation description: >- Welcome to Mihu API Documentation for developers.Here you can find all the information about the API endpoints and how to use them.If you have any questions or need help, please contact us at support@mihu.ai version: 1.0.0 servers: - url: https://{subdomain}.mihu.ai description: Your subdomain variables: subdomain: default: demo description: Subdomain name - url: /docs security: [] tags: - name: Agents description: >- Manage AI agents, settings, knowledge sections, rules, appointments, and channel provisioning - name: Contact Analyzers description: >- Configure what information should be extracted from conversations and how extracted values should update contacts, custom contact fields, or pipeline stages. Analyzer IDs use prefixes: `b_` means a built-in contact field, `f_` means a custom contact field, and `p_` means a pipeline stage rule. - name: Appointments description: Appointment management endpoints - name: Appointment Requests description: Appointment request endpoints - name: Assistant Channels description: >- Configure how a tenant user's Mihu Assistant is reached from outside the app — assign an inbox/WhatsApp number, set 'Your email'/'Your number', and optional PIN-based 2FA. This API is tenant-token authenticated but the resources it manages are per-user, so every request identifies the target user by their login email. - name: Availability Types description: Availability type endpoints - name: Builders description: >- Build and run apps on isolated cloud sandboxes (mihu Builders). Two ways in: **1. Describe it (Builder Agent):** POST /api/v1/builder-agents with a one-sentence prompt. The agent replies with questions (credentials, size, schedule); answer until it generates the code and deploys a running app with a public URL. **2. Ship your own code (Builders):** POST /api/v1/builders with your files + entrypoint. Returns a running app on a public HTTPS URL. --- **Which endpoint to call, by conversation `status` (the build-agent flow is async — always poll after a write):** | You have… | Call | Then | |---|---|---| | nothing yet | `POST /builder-agents` (prompt) | poll the conversation | | `status: processing` | nothing — it's working | keep polling `GET /builder-agents/{uuid}` (~2-3s) | | `status: gathering` (questions) | `POST /builder-agents/{uuid}/answers` | poll again | | `status: deployed` and want changes | `POST /builder-agents/{uuid}/rebuild` | poll again | | `status: deployed`, happy with it | operate it via `/api/v1/builders/{uuid}` (start/stop/logs/exec/files) | — | | `status: failed` | `POST /builder-agents/{uuid}/rebuild` with a fix, or start a new conversation | poll again | Rule of thumb: **write → then poll `GET /builder-agents/{uuid}` until status leaves `processing`.** Use `/answers` only while `gathering`; use `/rebuild` once `deployed`/`failed`. Once running, a builder exposes lifecycle controls (start/stop/auto-stop), live logs, a command terminal (exec), and direct file access. A preview URL only resolves while the builder is running. --- ### Connect via the standalone Builder MCP server Besides this REST API, the builder can be driven from your own AI client over the Model Context Protocol. The Builder MCP server lets a customer **build their own business integrations and apps** — CRMs, connectors, data migrations, webhooks, automation agents — by describing them in plain language from Claude Desktop, Claude Code, or Cursor. It is the integration and app builder for the customer, delivered over MCP. Each connection is bound to one tenant and scoped to it; no other tenant is reachable. **Get your connection details.** You get everything you need from the app: go to the **Builders** page and open the **Credentials** tab — the **Builder connection** panel there shows your three values. Server (for example https://builder.mihu.ai), Tenant (your workspace's builder tenant name), and Token (masked by default — click the eye icon there to reveal and copy it; it is your tenant key). Everything below comes from that panel. **Run the server (stdio).** Install with `pip install mcp`, then run it with your three values as environment variables: `MIHU_API_URL=Server MIHU_TENANT=Tenant MIHU_TENANT_KEY=Token python mcp_server.py`. **Register it with your MCP client.** In Claude Desktop's config, add an MCP server named mihu-builder whose command is `python`, whose argument is the path to `mcp_server.py`, and whose env sets MIHU_API_URL, MIHU_TENANT and MIHU_TENANT_KEY to your three values. In Claude Code, use `claude mcp add` with the same three env vars and the script path. **Tools the client gets:** create_agent, answer_agent, approve_agent, get_agent, list_agents, deploy_code, list_deployments, review_deployment, test_deployment, get_qa_report, get_logs, exec_command, start, stop, set_auto_stop, get_spending, store_credentials, and more. **Build flow (asynchronous — poll after each write):** create_agent, then poll get_agent; while gathering, call answer_agent and poll; when awaiting_approval, call approve_agent and poll; once deployed it is live with a preview URL. Keep your token secret — it authorizes everything for your tenant; rotate it from the Credentials tab if it leaks. - name: Call Actions description: >- Real-time control actions for an active call: say, forward, hangup, mute, and unmute. Each action targets a live call by its conversation UUID, returned as `conversation_uuid` from POST /api/v1/call. Requires a bearer token and a live (non-ended) call. - name: Campaigns description: Campaign management endpoints - name: Coaching Agents description: >- Coaching Agents turn evaluation results into coaching feedback for your agents — what went well, what to improve, and which resources to study. Each coaching agent is identified by its `uuid`. Quick start: 1. `POST /api/v1/coaching-agents` with a name — you get a ready-to-use coaching agent with sample templates and a training example. 2. Tune the style: `coaching_tone` (supportive, direct, constructive, motivational, or your own wording), `auto_trigger_threshold` (coach when the score drops below this %), and content options. 3. Make it the active coach with `POST /api/v1/coaching-agents/{uuid}/set-default`. Good to know: - One coaching agent is always the default; the first one you create becomes the default automatically. - Train the AI on your style with `training_examples` (an issue + your ideal coaching response) — 5-10 diverse examples work best. - Feedback is written in the `language` you set, e.g. "English". Recipe — recommend a resource when something is missing from the conversation: 1. Add the resource to `resource_library` with matching `topics`, e.g. `{"title": "Pricing Conversation Tutorial", "type": "video", "url": "https://example.com/pricing-video", "topics": "pricing, price objections, sales"}`. 2. Add the trigger rule to `general_guidelines`, e.g. "If the price was not mentioned during the conversation, point this out, explain why discussing price matters, and recommend the pricing video from the resource library.". 3. Keep `include_resources` on. The coaching feedback will now flag the gap and link the resource. - name: Contacts description: Contact management endpoints - name: Contact Approvals description: >- Manage AI-suggested contact field updates pending human review. Each approval is identified by its `uuid`. - name: Contact Fields description: >- Manage custom contact fields for your account. Each field is identified by its `key` (unique and immutable once created). - name: Contact Settings description: >- Toggle contact-list display preferences such as masking phone numbers or email addresses. Each setting is identified by its `key`. - name: Conversations description: Conversation management endpoints - name: Sessions description: Conversation session endpoints - name: Tables description: >- Tables are user-defined datasets that AI agents use as a knowledge base (semantic search over text) or as a real-time lookup (structured rows the agent queries during conversations). **When to create a table.** Create one whenever an agent needs to ground its answers in your data: product catalog, FAQ, pricing list, internal policies, customer records, business rules, etc. One table = one dataset on one topic. **How to create + populate.** Pick one of: - `POST /api/v1/data/tables` — create an empty table with a typed column schema (text/number/date/boolean/json/url). Use this when you have structured data and want to add rows yourself via the records endpoints. - `POST /api/v1/data/import/copypaste` — paste raw text. Best for FAQs, policy docs, or any unstructured knowledge content. - `POST /api/v1/data/import/file` — upload CSV/Excel/JSON/PDF/XML/audio. Best for spreadsheets, documents, transcripts. - `POST /api/v1/data/import/website` — crawl a URL. Best for public knowledge bases, marketing sites. **Records.** Once a table exists, add/update/delete rows via `POST|PUT|DELETE /api/v1/data/{uuid}/records[/{record}]`. Inspect the schema with `GET /api/v1/data/{uuid}/fields`. **Connecting to an agent.** Call `POST /api/v1/data/{uuid}/assign` to make a table available to an agent. After bulk changes, call `POST /api/v1/data/{uuid}/sync` to refresh the agent's index. **Lifecycle.** create → populate (records or import) → assign to agent → agent uses it at runtime → update/sync as data changes → delete when no longer needed. - name: Logs description: >- Read-only audit feeds covering three kinds of activity. **Actions** is a chronological stream of every task, workflow run, and AI action taken during a call — what your agents actually did, when, and how long it took. **API** records inbound requests made against this tenant's API (method, path, status, calling token, request/response bodies) — useful for debugging integrations and auditing access. **Webhooks** records outbound webhook deliveries sent to your registered endpoints (event, destination, status, payload, headers, response). Across all three, tokens, passwords, signatures and other secrets are masked before being returned. - name: Email Addresses description: >- Manage the mihu email addresses agents send and receive from. Create an address on the shared sending domain (instant) or connect your own domain (DNS or single-email verification), assign or unassign the handling agent, enable or disable an address, and check domain verification status. - name: Email Messages description: >- Send email through the mihu Connect channel: start a new email from one of your addresses, reply within an existing email conversation, or forward a conversation to a third party. Inbound email is received automatically and surfaced as conversations. - name: Evaluate description: >- Per-agent and global settings that control how conversations are sessionized and analyzed. WHAT EVALUATION DOES: At runtime, every conversation is grouped into 'sessions' (continuous bursts of messages). When a session ends — either because the customer goes idle for sessionization.timeout_minutes, or the conversation closes — the runtime fires SessionSummaryService and runs each enabled analyzer feature against the full session transcript. Outputs are persisted as 'evaluation' records. WHEN IT RUNS: - Voice calls and WhatsApp Call: at end of call (or after silence_timeout) - SMS, WhatsApp text, Instagram, FB Messenger: when the session creator job (SmsSessionCreatorJob / WhatsappSessionCreatorJob / equivalents) closes the session - Triggered automatically; not on demand WHICH CHANNEL'S CONFIG RUNS: - text.* features run for sessions on text channels (SMS, WhatsApp text, Instagram, FB Messenger, chat) - voice.* features run for sessions on voice channels (phone calls, WhatsApp Call) - Both blocks live on the same settings row; only the relevant one fires per session WHAT THE FEATURES PRODUCE: Each enabled feature emits a classification (one label per session, per feature) using its 'description' field as the LLM prompt. success_evaluation_prompt is special: it returns true/false based on the 'prompt' field — leave 'prompt' empty and the result is meaningless. summary_prompt is consumed by SessionSummaryService to produce the human-readable session summary in report_language. WHERE TO READ RESULTS: - GET /api/v1/sessions/{uuid}/evaluation — single session result - GET /api/v1/evaluations — list, filterable - GET /api/v1/analytics/evaluations — aggregated dashboard data COST CONSIDERATIONS: Each enabled feature is one extra LLM call per session. Disable features you don't read. is_active=false disables every analyzer for that agent (and skips the summary). WORKFLOW: 1. GET /default to see the workspace-wide config every agent inherits 2. POST /agents/{uuid}/evaluate/assign to give one agent its own override 3. PUT /agents/{uuid}/evaluate (or /default) for partial updates 4. DELETE /agents/{uuid}/evaluate to revert that agent to the default - name: Language description: Languages available for agent configuration. - name: Listings description: Listing management endpoints - name: Memorize description: >- Manage what your agents remember from contacts and conversations. There is one global default; each agent can optionally override it with its own settings. - name: Call description: Voice call endpoints - name: WhatsApp description: WhatsApp messaging endpoints - name: WhatsApp Calling description: WhatsApp voice call endpoints - name: SMS description: SMS messaging endpoints - name: Evaluations description: >- Evaluations are AI-generated analysis records for conversation sessions. Use these endpoints to list or retrieve scores, labels, reasons, and linked conversation/contact identifiers for quality review and reporting. - name: Schedules description: >- Schedules are bookable calendars used by agents and appointment flows. A schedule links to an availability type, stores assignment metadata, and can include custom questions for appointment collection. - name: Tasks description: >- Tasks are scheduled units of work for agents, such as outbound calls and WhatsApp template messages. Use task endpoints when you need to inspect campaign-generated work, create one-off outreach, queue a task, cancel it, or retry a failed attempt. - name: Transcriptions description: >- Transcriptions turn audio files or audio URLs into conversation text, session records, and optional AI evaluations. Use these endpoints to submit recorded calls, receive asynchronous completion webhooks, fetch transcription status, and retrieve the final transcript with analysis. - name: Analytics description: >- Aggregated analytics across calls, conversations, sessions, evaluations, intents, appointments, and messages - name: Flows description: >- Studio automation flows — list, create, read, update, delete. A flow is a trigger step + N action steps that fire on real events (e.g. inbound call → post to Slack → create CRM contact). Flows live in draft until POST /deploy makes them live. - name: Flow Steps description: >- Add / update / delete steps inside a flow. The first step is always a trigger; subsequent steps are actions. Step IDs and their ordering (`step_number`) are managed by the server — adding or deleting a step automatically renumbers and rewrites `{{stepN.field}}` references in downstream steps. - name: Flow Catalog description: >- Read-only discovery of integrations and their capabilities. Lists apps, triggers, actions, OAuth connections, agents, and dynamic field options. The MCP server uses this to translate natural language ("post to Slack #general") into the IDs/keys the action config requires. - name: Flow Executions description: >- Execution history for a deployed flow — every real trigger event that fires produces one execution row with per-step request/response/duration/status. - name: Voice IVR & Guards description: >- Two related but distinct features that decide when an agent transfers a call or ends a conversation. WHAT THEY ARE: - ROUTING RULES (Voice-Activated IVR): customer-intent-driven transfers. When the customer ASKS for something (sales, support, manager), routing rules pick the right destination. This is the IVR replacement. - GUARD RULES (Guard & Hand Over): situation-driven transfers or call-ends. When the runtime detects a sensitive SITUATION (legal complaint, profanity, compliance violation, customer in distress), the guard fires regardless of what the customer asked for. WHEN TO USE WHICH: - Customer says 'I want to speak to a manager' -> ROUTING rule (intent: customer wants escalation). - Customer threatens legal action -> GUARD rule (situation: compliance/safety overrides whatever the customer was asking). - Customer asks for technical support -> ROUTING rule. - Customer becomes abusive -> GUARD rule (then_action: end_conversation or forward). - Rule of thumb: routing = 'where do they want to go?', guard = 'this conversation needs to stop or hand off NOW'. PRIORITY AND ORDERING: - Routing rules have a numeric `priority` field. Lower number = higher priority = evaluated first. Ties resolved by insertion order. - Guard rules ALWAYS take precedence over routing rules. If a guard fires, routing is bypassed. - If multiple guards could fire on the same utterance, only the first match wins. DETECTION MECHANICS (routing only): - detection_mode = exact: the customer must say `trigger_keyword` literally. Fast, narrow, language-sensitive. - detection_mode = intent: the runtime AI uses `ai_prompt` + `phrases` to classify intent semantically. Broader, multilingual, requires good ai_prompt wording. - detection_mode = both: runs exact first, falls back to intent. Recommended for production. REQUIRED FIELDS FOR THE AI TO PICK THE RULE: - Routing intent/both: `ai_prompt` + `phrases` (3-5 examples). - Routing exact: `trigger_keyword`. - Guard: `when_condition` + `example_phrases`. Without these, the runtime cannot classify utterances and the rule never fires. CRUD MODES: - PUT /agents/{uuid}/routing-rules or /guard-rules — REPLACE all rules in one call. Old rules are deleted first. Use for bulk imports or full re-syncs. - POST /agents/{uuid}/routing-rules or /guard-rules — ADD one rule, leave others intact. Returns 201. Use for incremental builds. - PATCH /...{ruleUuid} — partial UPDATE of one rule. Only sent keys are touched. - DELETE /...{ruleUuid} — remove one rule. Per-rule POST/PATCH/DELETE preserve other rules; PUT replaces everything. - name: PBX Extension Connectors description: >- Voice PBX & Extension Connectors — register a PBX extension against an AI voice agent. This is the PBX-side configuration only; it does not provision a SIP trunk. Use it when you want to connect a number you've purchased from us into your existing PBX extension. If you already have a SIP trunk from a provider, use the SIP Trunking endpoints directly instead. - name: Phone Numbers description: Manage phone number inventory, channel bindings, search, and rates - name: Contact Pipeline description: >- Pipeline stages classify where a contact is in your sales, support, or onboarding process. Use these endpoints to define the ordered stage list, move contacts between stages through contact updates, and keep inactive stages out of normal selection while preserving history. - name: Pools description: >- Contact pools — named buckets of contacts that one or more campaigns draw from. A pool's `type` (FIFO / LIFO / Parallel) controls dispatch order when a campaign is running. **Typical workflow (build a pool from scratch):** 1. POST /api/v1/contacts — create the contacts you want to reach (or use existing UUIDs) 2. POST /api/v1/pools — create a pool 3. POST /api/v1/pools/{uuid}/contacts — bulk-add contacts by UUID 4. (attach to campaign — see Campaigns tag) **Inspect / manage:** - GET /api/v1/pools/{uuid}/contacts — paginated list of pool members with status, retries, started_at - DELETE /api/v1/pools/{uuid}/contacts/{contact_uuid} — remove one contact and cancel only THAT contact's pending tasks (not their tasks in other pools) - POST /api/v1/pools/{uuid}/duplicate — clone pool config, optionally with all members **Side effect on a running campaign:** if you POST /pools/{uuid}/contacts to a pool already attached to an In Process campaign, tasks are auto-created for the new contacts in EVERY running campaign attached to that pool. Same call works for draft campaigns too — it just doesn't create tasks until publish. **Delete guard:** DELETE /api/v1/pools/{uuid} returns 409 if the pool is attached to a campaign in In Process or Importing status. Stop or detach first. - name: QA Agents description: >- QA Agents score your conversations against a weighted skill scorecard and produce evaluation reports and coaching feedback. Each QA agent is identified by its `uuid`. Quick start: 1. `POST /api/v1/qa-agents` with a name — you get a ready-to-use scorecard (Greeting 15%, Empathy 20%, Compliance 25%, Resolution 25%, Sales 15%). 2. Adjust the scorecard with `PUT /api/v1/qa-agents/{uuid}/skills` — weights must always total 100%. 3. Make it the active evaluator with `POST /api/v1/qa-agents/{uuid}/set-default`. Good to know: - One QA agent is always the default; it evaluates sessions when no specific QA agent is chosen. The first one you create becomes the default automatically. - `evaluates_agent_type` controls who gets evaluated: `human` agents, `ai` agents, or `both`. - Reports are written in the `language` you set, e.g. "English". - name: Rules description: >- Campaign contact rules — call cadence, retry intervals, working-hours window, and escalation policy. A rule defines HOW often and WHEN a campaign reaches a contact; the campaign defines WHO and WHAT. **Typical workflow:** 1. POST /api/v1/rules — create a rule (call or text type) 2. POST /api/v1/campaigns — create a campaign in Draft status 3. PUT /api/v1/campaigns/{uuid}/rule — attach the rule (replaces any prior rule) 4. (continue with pool attachment + publish — see Campaigns tag) **Type-aware behavior:** - type='call' rules honor retry_interval_minutes and end_time (working-hours window). - type='text' rules force one-shot semantics: max_total_calls=1, retry/end_time nulled. Used for SMS and WhatsApp campaigns. **Caveat:** changing a rule on a campaign that's already In Process does NOT rebuild already-scheduled tasks. New tasks created after the change pick up new values; old ones keep the old cadence. To force a hard reset: stop campaign → assign new rule → publish again. - name: Simulations description: >- Simulation Studio — test an AI assistant against realistic AI customers before it goes live, and get a scored report with a full transcript per conversation. * * **What a simulation is.** One simulation = one assistant under test, on one channel, with a set of customer personas and test cases. A test case has a `title`, a `scenario` (what the simulated customer tries to do), an `expected` outcome, and `criteria` — short, objectively checkable statements the judge verifies from the transcript alone (e.g. 'Confirms date & time', 'Offers escalation', 'Keeps replies under 30 words'). Running the simulation executes `runs_per_case` conversations per test case; each conversation pairs one persona with the assistant, up to `max_turns` customer turns. * * **How faithful it is.** The assistant answers with its own production brain: its prompt, training rules, knowledge base, and its own configured model. With `with_intents=true` it also uses its real intent/appointment/guard tools — detected intents EXECUTE their events for real (webhooks and connected flows actually fire), so enable it deliberately. * * **Channels.** `voice`, `sms`, `whatsapp`, `whatsapp_call`, `email` (same set as Start Conversation). Text channels always run simulated (LLM ↔ LLM using the channel-appropriate prompt; nothing is sent externally, no real contacts touched). `voice` and `whatsapp_call` additionally support `call_mode=real`: the `caller_agent_uuid` agent's line (SIP trunk for voice, WhatsApp calling line for whatsapp_call — see `whatsapp_call_lines` in /options) places a REAL call to the assistant's number with its prompt fully overwritten by the persona — two live voice agents talk over real telephony, the assistant is exercised on its production inbound path, and the run carries a `record_url` recording. * * **State machine.** `draft → queued → running → passed | failed`. `passed` means the average judge score reached `pass_threshold`. A stopped simulation keeps results of finished conversations, or returns to `draft` if none finished. Stuck runs self-heal within minutes. * * **Billing.** Every assistant message in a simulated conversation is billed at the plan's text-message rate (see `message_rate` in /options; ceiling per run = test_cases × runs_per_case × max_turns × rate). Charges appear in the wallet transaction history as 'Simulation …'. An empty wallet blocks new runs. Real calls are billed as calls, not messages. * * **Which endpoint to call, by where you are:** * * | You have / want | Call | Then | * |---|---|---| * | nothing yet | `GET /simulations/options` | pick channel + assistant (+ caller line for real calls) | * | want AI-written config | `POST /simulations/generate-test-cases`, then optionally `/generate-personas` | edit the drafts, pass them into create | * | a config | `POST /simulations` (add `run:true` to start immediately) | poll | * | `state: queued/running` | `GET /simulations/{uuid}` (~3-5s) — run summaries update live; a run's transcript grows under `/runs/{runUuid}` | keep polling until `passed`/`failed` | * | want to abort | `POST /simulations/{uuid}/stop` | finished conversations keep their scores | * | `state: passed/failed` | `GET /simulations/{uuid}/report` | drill into `/runs/{runUuid}` for transcripts | * | want changes | `PUT /simulations/{uuid}` (409 while running), then `/run` again | previous spend stays in `billed_total` | * | a FAILED report, want auto-fix | `POST /simulations/{uuid}/optimize` | poll; then accept/reject the proposed field changes | * * **Self-improvement (optional).** On a finished report, `POST /{uuid}/optimize` proposes changes to the agent's STRUCTURED FIELDS (role, objective, tone, length, fallback response, company context) plus new Response Guidelines, Notes and Training Data — NOT a raw prompt. It returns a 'proposed' entry in `data.optimizations[]` with a plain-language `summary`, a `changes` object (`{fields:{col:newValue}, guidelines_add:[], notes_add:[], training_add:[]}`), and `before_score` — nothing is tested or applied yet. Then choose: `POST /{uuid}/optimize/accept {attempt_id}` to apply it, or `POST /{uuid}/optimize/trial {attempt_id}` to re-run the simulation with it first (poll `GET /{uuid}` — the attempt becomes 'ready' with `after_score`). Both accept and trial take an OPTIONAL `changes` body — pass an edited/trimmed version of the proposed `changes` to apply or test only what you want (drop a field key or a list item to skip it). Accept writes those fields to the agent, regenerates its prompt (via the same builder the Skills editor uses) and clears any custom_prompt override; `POST /{uuid}/optimize/revert` restores the changed fields. The live assistant is untouched until accept. * * **Attempt status lifecycle** (`data.optimizations[].status`): `proposed` → (`running` → `ready`, only if you trial it) → `accepted` | `rejected` | `reverted`. Only one attempt can be pending (`proposed`/`running`/`ready`) at a time; a second `optimize` returns 409 while one is pending. 409 reasons on these endpoints: no report yet, an attempt already pending, an empty change set, an empty wallet (trial), or (revert) the agent's prompt changed since it was applied. * * **Self-improvement worked example** (apply only some of the proposed changes): * 1. `POST /{uuid}/optimize` → `{ attempt_id }`. * 2. `GET /{uuid}` → find the `data.optimizations[]` entry with `status: proposed`; read its `changes`, e.g. `{ fields: { tone: Concise and factual, negative_response: … }, guidelines_add: [On SMS confirm the email by reading it back in full — never letter by letter], notes_add: [], training_add: [] }`. * 3. Drop anything you don't want — remove a key from `fields` or an item from a list. * 4. `POST /{uuid}/optimize/accept` with `{ attempt_id, changes: }` (omit `changes` to apply as-is). The agent's fields are written and its prompt rebuilt. * 5. Confirm on the agent with `GET /api/v1/agents/{agent_uuid}` (role/objective/tone/guidelines now reflect it). Undo with `POST /{uuid}/optimize/revert { attempt_id }`. * * **Reading a transcript.** Entries are `{who, text, at}` with `who` one of `customer` (the persona), `assistant` (the agent under test), or `tool` (a real intent/tool execution — carries `name`, `request`, `response`, `success`). A `tool` entry named `call_timeout` marks a call cut by its time budget. * * **Response envelope.** Every endpoint returns `{success: bool, message: string, data: ...}`; errors use HTTP status + `success:false` with the reason in `message`. A 409 on /run tells you exactly what to fix (already running, incomplete configuration, missing caller line, or empty wallet). * * **Operational rules (follow them — each prevents a misleading result):** * - If a test case's criteria reference the assistant's intents/activities (generate-test-cases often writes such criteria), run with `with_intents: true` — without it the assistant cannot trigger intents and those criteria fail unfairly. * - Size `max_turns` to the scenario: 3-4 turns suit a single-question smoke test; discovery/booking scenarios with multi-step criteria need 6-10 turns, or the judge will correctly fail criteria the conversation never had room to reach. * - `POST /simulations` with `run: true` can return 201 with 'created, but it could not start: …' in `message` — always check `data.state`: `queued` means running; `draft` means fix the stated reason, then call `/{uuid}/run`. * - A real-call run that errors with 'requested sip trunk does not exist' means that CALLER line's telephony is stale — pick a different `caller_agent_uuid` from /options and have the broken line re-provisioned. * - A real-call run that errors with 'produced no transcript' may still have connected (check `record_url` for a recording); it means the platform's transcripts never reached the run within 3 minutes. * - Judge scores vary between runs of the same configuration; for decisions use `runs_per_case: 3` (criteria resolve by majority) and treat single-run results as smoke signals only. * * **Minimal end-to-end example** (WhatsApp, auto-generated cases, run immediately): * 1. `GET /api/v1/simulations/options` → pick an agent whose `channels` contains `whatsapp`. * 2. `POST /api/v1/simulations/generate-test-cases` with body `{ agent_uuid: …, channel: whatsapp }` → returns cases. * 3. `POST /api/v1/simulations` with body `{ name: wa-smoke, channel: whatsapp, agent_uuid: …, test_cases: , runs_per_case: 1, run: true }`. * 4. Poll `GET /api/v1/simulations/{uuid}` every ~5s until `state` is `passed` or `failed`. * 5. `GET /api/v1/simulations/{uuid}/report` → score, criteria verdicts, issues, suggestions; transcripts under `/runs/{runUuid}`. - name: Contact Tags description: >- Manage contact tags for your account. Each tag is identified by its `uuid`. - name: WhatsApp Template Settings description: >- Template Settings make an APPROVED WhatsApp template campaign-ready by defining what fills each {{n}} placeholder when a message is sent to a contact. **Why two layers?** A WhatsApp template (see the WhatsApp Templates tag) is the Meta-approved message skeleton: 'Hi {{1}}, your {{2}} is ready'. A Template Setting is YOUR mapping for it: {{1}} = the contact's name, {{2}} = a fixed value like 'service appointment'. Campaigns reference a Template Setting, never a raw template — without one, a WhatsApp campaign has nothing to send. **Placeholder values — three kinds, resolved per contact at send time:** - `{{contact.}}` — a base contact field: name, surname, phone_number, email, country_code, timezone, primary_language - `{{custom.}}` — a custom contact field by its snake_case key (e.g. {{custom.car_model}}, {{custom.plate_number}}) - any other string — sent literally, identical for every contact If a mapped field is empty for a contact, the placeholder resolves to an empty string and the message still sends. **Typical workflow:** 1. GET /api/v1/whatsapp/templates?active_only=true — find an APPROVED template, note its uuid and how many {{n}} placeholders its content has 2. POST /api/v1/whatsapp/template-settings — create the mapping (one value per placeholder, keys '1'..'N') 3. POST /api/v1/listings with campaign_type='text' and contact_template_setting_uuid — launch the campaign **Deletion guard:** a setting referenced by a campaign that is In Process, Importing, Active, or Paused cannot be deleted (409). Finished campaigns don't block deletion. - name: Timezone description: Timezones available for agent configuration. - name: Voice Library description: >- Catalog of voices available to agents and the speed options each voice supports. - name: WhatsApp Templates description: >- Manage WhatsApp message templates — Meta-approved messages used for outbound WhatsApp campaigns. All endpoints are scoped to the tenant: you can only act on linked WABAs (WhatsApp Business Accounts). **Typical workflow — pull existing templates:** 1. GET /api/v1/whatsapp/wabas — discover WABAs linked to your tenant 2. POST /api/v1/whatsapp/templates/sync — pull all templates Meta has for a WABA (one-time bootstrap) 3. GET /api/v1/whatsapp/templates?waba_id=...&active_only=true — list APPROVED templates ready to use 4. Use a template UUID with POST /api/v1/whatsapp/template (one-shot send) or in a campaign **Typical workflow — create a brand-new template with a media header:** 1. POST /api/v1/whatsapp/templates/upload-media (multipart) — upload your image/video/document, receive a `handle` 2. POST /api/v1/whatsapp/templates — submit with `components` including HEADER referencing the handle 3. Wait — Meta approval is async, usually minutes. Status starts as PENDING. 4. POST /api/v1/whatsapp/templates/{uuid}/sync — refresh status until APPROVED, REJECTED, or PAUSED 5. Once APPROVED, use it in sends/campaigns **Component shape — quick reference:** - HEADER text: { type:'HEADER', format:'TEXT', text:'Hi {{1}}', example:{header_text:['John']} } - HEADER image: { type:'HEADER', format:'IMAGE', example:{header_handle:['']} } - HEADER video/document: same as image with format=VIDEO or DOCUMENT - BODY: { type:'BODY', text:'Order {{1}} ready', example:{body_text:[['12345']]} } note nested array - FOOTER: { type:'FOOTER', text:'Reply STOP to unsubscribe' } - BUTTONS group: { type:'BUTTONS', buttons:[ ... ] } with up to 10 buttons: QUICK_REPLY: { type:'QUICK_REPLY', text:'Yes please' } URL: { type:'URL', text:'Track', url:'https://example.com' } PHONE_NUMBER: { type:'PHONE_NUMBER', text:'Call', phone_number:'+1234567890' } COPY_CODE: { type:'COPY_CODE', example:'WELCOME10' } **Tenant scoping:** - 403: WABA is not linked to your tenant (no matching WhatsappSetting row) - 404 (not 403): templates that belong to other tenants — surfaced as 'not found' to avoid info leak. Same convention for non-whatsapp template types and orphan rows. **How auth works:** the existence of a WhatsappSetting row in the tenant DB IS the ownership proof — multi-tenant DB scoping handles isolation. The Meta access token used for API calls is the platform-global config('whatsapp.access_token'), the same token that powers every other WhatsApp send in this codebase (replies, campaigns, one-shot template sends). If WhatsappSetting.access_token is populated, that takes precedence — but onboarding doesn't fill it today, so the platform token is what actually runs. - name: Agent Channel Bindings description: Agent Channel Bindings - name: Agentic Search description: Agentic Search - name: Contact Blacklist description: Contact Blacklist - name: Flow description: Flow - name: SIP Trunk description: SIP Trunk paths: /api/v1/whatsapp/templates/sync: post: tags: - WhatsApp Templates summary: Bulk-sync templates for a WABA from Meta into local DB description: >- Pulls all templates Meta has on file for the given waba_id and upserts them locally (matched by Meta template id). Walks Meta's pagination internally (capped at 10 pages, ~250 templates per WABA). **When to call this:** - **Bootstrap** — once after linking a WABA, to import templates you created in Meta Business Manager. - **Periodic refresh** — to pick up status changes, edits made in Meta Business Manager, or templates created outside this API. - **NOT needed after POST /templates** — that endpoint already stores the template locally; only individual status changes need /sync. **Idempotent:** safe to re-run. Existing rows are updated in place; new rows inserted; nothing is deleted (templates removed from Meta remain locally with their last-known status — call DELETE /templates/{uuid} to clean up). operationId: b637f16412fd1621f20a957841192e77 requestBody: required: true content: application/json: schema: required: - waba_id properties: waba_id: type: string example: '123456789012345' type: object responses: '200': description: >- Sync complete. Response includes how many templates Meta returned and what's now in local DB for that WABA. content: application/json: schema: properties: success: type: boolean example: true message: type: string example: Synced N templates from Meta data: properties: waba_id: type: string meta_returned: type: integer local_total_after_sync: type: integer type: object type: object '403': description: WABA not linked to this tenant. '502': description: Meta API call failed. security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Use a Bearer token to access these API endpoints. Example: "Bearer {your-token}" ````