# Assign a Facebook page (Messenger) to an agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/assign-a-facebook-page-messenger-to-an-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/messenger Assigns a connected Facebook page to the agent for Messenger conversations. Use this before routing Messenger messages to the agent. The page must already be connected to your account. # Assign a WhatsApp Calling number to an agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/assign-a-whatsapp-calling-number-to-an-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/whatsapp-call Assigns a WhatsApp Business number to the agent for WhatsApp Calling. Use this when the agent should place or receive WhatsApp voice calls through an already connected number. Calling must be enabled on the number, and the agent is also assigned for WhatsApp messaging. # Assign a WhatsApp number to an agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/assign-a-whatsapp-number-to-an-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/whatsapp Assigns a connected WhatsApp Business number to the agent for WhatsApp messaging. Use this before sending WhatsApp template tasks or letting the agent answer WhatsApp conversations. The WhatsApp number must already be connected to your account. # Assign an Instagram account to an agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/assign-an-instagram-account-to-an-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/instagram Assigns a connected Instagram business account to the agent. Use this before routing Instagram direct messages to the agent. The Instagram account must already be connected to your account. # Assign an SMS phone number to an agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/assign-an-sms-phone-number-to-an-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/sms Assigns one owned phone number to the agent for SMS conversations and provisions its messaging profile plus inbound webhook. Use this after purchasing or importing an SMS-capable number and before sending SMS tasks or receiving SMS replies with this agent. Any existing SMS assignment for the agent is replaced. The call fails if inbound provisioning cannot be completed. # Unbind the Instagram channel from this agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/unbind-the-instagram-channel-from-this-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/instagram/unbind Removes the agent's Instagram binding. Use this when Instagram messages should stop routing to this agent. The Instagram account stays connected to your account and can be assigned again later. # Unbind the Messenger channel from this agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/unbind-the-messenger-channel-from-this-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/messenger/unbind Removes the agent's Messenger binding. Use this when Facebook page messages should stop routing to this agent. The page stays connected to your account and can be assigned again later. # Unbind the SMS channel from this agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/unbind-the-sms-channel-from-this-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/sms/unbind Removes the agent's SMS channel binding. Use this when the agent should stop handling SMS on its current number. The phone number stays in your account and can be assigned to another agent later. # Unbind the WhatsApp channel from this agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/unbind-the-whatsapp-channel-from-this-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/whatsapp/unbind Removes the agent's WhatsApp messaging binding. Use this when the agent should no longer answer or send WhatsApp messages through that number. The WhatsApp number stays connected to your account. # Unbind WhatsApp Calling from this agent Source: https://developers.mihu.ai/api-reference/agent-channel-bindings/unbind-whatsapp-calling-from-this-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/whatsapp-call/unbind Removes the agent's WhatsApp Calling binding while keeping WhatsApp messaging unchanged. Use this when the number should still send and receive WhatsApp messages but should no longer route WhatsApp voice calls to this agent. # List an agent's knowledge tables Source: https://developers.mihu.ai/api-reference/agent-knowledge-base/list-an-agents-knowledge-tables https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/knowledge-base Returns the knowledge tables attached to the agent, with the agent's relevance filter (`min_score`, null = platform default), each table's own relevance filter (overrides the agent's for that table's content) and each table's indexing state. `status` is this agent's processing state for the table (`completed` = ready, `pending` / `in_progress` = still processing). `sync_status` values: `up_to_date` — indexed and current, searchable; `updating` — indexing is running in the background, compare `indexed_records` with `records_count` for progress; `sync_required` — the table's content changed after the last sync, search still returns the previously indexed version until it is re-synced; `not_indexed` — never indexed or removed from search, this table is NOT searchable until it is synced. # Search an agent's knowledge base Source: https://developers.mihu.ai/api-reference/agent-knowledge-base/search-an-agents-knowledge-base https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/knowledge-base/search Runs the same retrieval pipeline the agent uses when answering (semantic search with relevance reranking; exact matching for numeric lookups such as phone numbers) and returns the most relevant excerpts. # Update the agent's knowledge retrieval settings Source: https://developers.mihu.ai/api-reference/agent-knowledge-base/update-the-agents-knowledge-retrieval-settings https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/knowledge-base/settings min_score (0-1) is the minimum relevance a knowledge excerpt needs before it is used in the agent's answers, across every channel. Send null to restore the platform default. Note: relevance scores are not percentages — correct answers typically score 0.4-0.7, so values above ~0.5 will start dropping valid results. # Agentic web search and analysis Source: https://developers.mihu.ai/api-reference/agentic-search/agentic-web-search-and-analysis https://app.mihu.ai/docs/api-docs.json post /api/v1/agentic-search Runs an agentic, web-grounded search for any research question and returns a written answer with source citations. **When to use this endpoint:** - Agentic search over public web data - Local market questions (combine with search_country / search_city filters) - Any question that cannot be answered from internal data alone **Choosing a depth (search_preset):** start with fast-search for simple questions. Use pro-search when answer quality and source coverage matter (recommended for business research). Reserve deep-research and advanced-deep-research for complex multi-source research where a longer response time is acceptable. # Add a single guideline Source: https://developers.mihu.ai/api-reference/agents/add-a-single-guideline https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/guidelines Adds one guideline to the agent without changing existing guidelines. Use guidelines for concise behavior rules such as tone, compliance boundaries, or things the agent should always or never do. # Add a single note Source: https://developers.mihu.ai/api-reference/agents/add-a-single-note https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/notes Adds one note to the agent without changing existing notes. Use notes for factual reference material the agent should remember during conversations, such as policy snippets, product facts, or business context. # Add a single procedure (with optional steps) Source: https://developers.mihu.ai/api-reference/agents/add-a-single-procedure-with-optional-steps https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/procedures Adds one procedure to the agent without replacing existing procedures. Use procedures for ordered workflows the agent should follow, such as qualification, troubleshooting, or booking flows. Include steps when the procedure needs explicit sequence. # Add a single training data row Source: https://developers.mihu.ai/api-reference/agents/add-a-single-training-data-row https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/training Adds one training row to the agent without changing existing training. Use training rows to provide examples, expected responses, or intent-specific reference material that improves runtime answers. # Add a webhook to this agent Source: https://developers.mihu.ai/api-reference/agents/add-a-webhook-to-this-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/webhooks Creates a webhook subscription for an agent. Use this to receive event notifications such as conversation updates, evaluations, or intent calls. Provide the destination URL and event list. Returns 409 webhook_limit_reached if the agent already has 5 webhooks. # Analyze website documentation for agent creation Source: https://developers.mihu.ai/api-reference/agents/analyze-website-documentation-for-agent-creation https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/analyze-website Researches a public website or documentation URL with a web-grounded search and returns structured business context (company, services, audience, FAQ, automation opportunities) that can be used to create an agent. The URL is not fetched directly \u2014 see the note on source_url. **When to use this endpoint:** - Preview the analysis before creating an agent with /api/v1/agents/from-website - Research a company, its services, and automation opportunities without creating anything - Market research: add an analysis_prompt and read the result from additional_analysis The response contains the structured analysis plus _citations with the source URLs. # Channels and phone numbers for an agent Source: https://developers.mihu.ai/api-reference/agents/channels-and-phone-numbers-for-an-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/channels Lists every phone number this agent answers on, with the channels (call, SMS, WhatsApp) the agent serves on each number. The outer `channels` array is the union across all of the agent's numbers — handy for showing badges in a list view. # Clear the agent's email signature Source: https://developers.mihu.ai/api-reference/agents/clear-the-agents-email-signature https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/email-signature Removes the agent's email signature by setting it to empty. Nothing is deleted from the account — the connected email address stays; only the signature is cleared. # Clear the intent's action (event) Source: https://developers.mihu.ai/api-reference/agents/clear-the-intents-action-event https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/intents/{intentUuid}/event Removes the intent's configured action. The intent itself remains; it just no longer performs an action when it fires. # Create an agent Source: https://developers.mihu.ai/api-reference/agents/create-an-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents Creates a new AI agent. Provide as much of the structured shape as you can in one call — a fully-formed agent at creation time has dramatically better runtime behavior than a thin agent that gets configured incrementally. A high-quality agent typically includes: (1) identity (name, company_name, role, language); (2) prompt fields that shape the runtime AI (objective, tone, behavior_guidelines, negative_response, length_detail); (3) the relevant settings block (settings.voice for phone agents, settings.text for messaging agents) populated with at minimum the interaction first/end messages and voice_profile or working_hours; (4) reference knowledge (notes, training Q&A pairs); (5) operational rules (guidelines for short do/don'ts, procedures for multi-step workflows); (6) capabilities the agent should perform (appointments + schedule_assignments with name/description filled, routing_rules with ai_prompt + phrases for IVR, guard_rules with when_condition + example_phrases for compliance escalations). Skipping prompt/description fields produces hollow agents that respond generically and ignore the operational rules at runtime — see each sub-schema's description for the AI-prompt fields that must not be left empty. # Create an agent from website documentation Source: https://developers.mihu.ai/api-reference/agents/create-an-agent-from-website-documentation https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/from-website Researches a public website or documentation URL with a web-grounded search, decides the best agent identity and behavior from the discovered business context, creates the agent, and stores the analysis as agent notes. The URL is not fetched directly \u2014 see the note on source_url. **When to use this endpoint:** - Onboarding a new customer: turn their website into a ready-to-use agent in one call - Creating a demo agent for a prospect from just their URL - Rebuilding an agent after a company website or product change Use /api/v1/agents/analyze-website first if you want to inspect the analysis before creating the agent. The created agent starts with default voice and text settings — customize them afterwards via the agent update endpoints. # Create an intent Source: https://developers.mihu.ai/api-reference/agents/create-an-intent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/intents Creates a custom intent for an agent. Use intents when the agent should recognize a user goal and optionally collect parameters or call a webhook. Provide a clear description of when the intent should trigger and define parameters for any values the agent must collect. # Create or set the agent's email signature Source: https://developers.mihu.ai/api-reference/agents/create-or-set-the-agents-email-signature https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/email-signature Alias of PUT — a signature is a single value, so this creates it if none exists and replaces it otherwise (upsert). Accepts HTML, sanitized before saving. The agent must have a connected email address (Mails channel). # Delete a single guideline Source: https://developers.mihu.ai/api-reference/agents/delete-a-single-guideline https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/guidelines/{guidelineUuid} Deletes one guideline from the agent. Use this when a behavior rule no longer applies. Other guidelines are not changed. # Delete a single note Source: https://developers.mihu.ai/api-reference/agents/delete-a-single-note https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/notes/{noteUuid} Deletes one note from the agent. Use this when a reference fact is outdated or should no longer be available to the agent. Other notes are not changed. # Delete a single procedure (and its steps) Source: https://developers.mihu.ai/api-reference/agents/delete-a-single-procedure-and-its-steps https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/procedures/{procedureUuid} Deletes one procedure and its steps from the agent. Use this when the workflow is obsolete or should no longer guide conversations. Other procedures remain unchanged. # Delete a single training row Source: https://developers.mihu.ai/api-reference/agents/delete-a-single-training-row https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/training/{trainingUuid} Deletes one training row from the agent. Use this when an example or response is outdated, wrong, or no longer relevant. Other training rows are not changed. # Delete a webhook Source: https://developers.mihu.ai/api-reference/agents/delete-a-webhook https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/webhooks/{webhookUuid} Deletes one webhook from the agent. Use this to stop sending event notifications to that destination. Other webhooks on the same agent are not changed. # Delete an intent Source: https://developers.mihu.ai/api-reference/agents/delete-an-intent https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/intents/{intentUuid} Deletes a custom intent and its parameters. Use this when an action or integration should no longer be available to the agent. System intents cannot be deleted. # Get all voice settings Source: https://developers.mihu.ai/api-reference/agents/get-all-voice-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/voice Returns the agent's full voice settings block: interaction messages, interruption tuning, voice profile, voice advanced tuning, call behavior, compliance, and phone normalizers. Identical to the `settings.voice` object inside GET /api/v1/agents/{uuid}. # Get call behavior Source: https://developers.mihu.ai/api-reference/agents/get-call-behavior https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/call-behavior Returns recording, background sound (on/off + ambience + volume), noise cancellation, silence timeout, and max call duration settings. # Get compliance settings Source: https://developers.mihu.ai/api-reference/agents/get-compliance-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/compliance Returns the EU GDPR and HIPAA compliance flags for the voice agent. # Get interaction settings Source: https://developers.mihu.ai/api-reference/agents/get-interaction-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/interaction Returns the conversation opening/closing messages and silence prompts used by the voice agent. # Get interruption settings Source: https://developers.mihu.ai/api-reference/agents/get-interruption-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/interruption Returns the interruption mode and the advance-mode overrides (endpointing delays, interruption windows, false-interruption handling). The advanced block is always populated, normalized to the active mode. # Get one agent Source: https://developers.mihu.ai/api-reference/agents/get-one-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid} Returns the full API representation of one agent, including profile fields, voice/text settings, guidelines, notes, procedures, training, schedules, routing rules, guard rules, intents, webhooks, and channel bindings. Use this before updating the agent or before wiring the agent into a campaign or call flow. # Get one intent Source: https://developers.mihu.ai/api-reference/agents/get-one-intent https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/intents/{intentUuid} Returns one intent with its trigger description, confidence threshold, webhook configuration, and parameters. Use this before updating an intent or inspecting the tool schema the agent can call. # Get one webhook Source: https://developers.mihu.ai/api-reference/agents/get-one-webhook https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/webhooks/{webhookUuid} Returns one agent webhook by UUID, including URL, subscribed events, active state, and whether a signing secret exists. The secret value is never returned. # Get phone normalizers Source: https://developers.mihu.ai/api-reference/agents/get-phone-normalizers https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/normalizers Returns the outbound and inbound phone-number normalizer rules (default prefix, condition length, condition prefix). # Get supported voice tuning fields Source: https://developers.mihu.ai/api-reference/agents/get-supported-voice-tuning-fields https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/voice-advanced Returns the voice tuning fields supported by the agent's currently selected voice, each with its type, bounds/options, and current value. The supported set depends on the selected voice, so always fetch this before sending a voice-advanced update. Returns an empty field list when no voice is selected. # Get the agent's email signature Source: https://developers.mihu.ai/api-reference/agents/get-the-agents-email-signature https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/email-signature Returns the email signature for this agent (the same value shown in the agent's Text Settings). It is appended automatically to emails the agent sends — replies, single sends, and email tasks/campaigns that don't already include it. # Get the intent's action (event) Source: https://developers.mihu.ai/api-reference/agents/get-the-intents-action-event https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/intents/{intentUuid}/event Returns the single action the intent performs when it fires. `event_type` is null when no action is configured. For `app` events the `app.is_builtin` flag tells you whether a connection is required. # Get voice profile Source: https://developers.mihu.ai/api-reference/agents/get-voice-profile https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/voice-profile Returns the agent's spoken language and the selected voice (uuid + display name). # List agents Source: https://developers.mihu.ai/api-reference/agents/list-agents https://app.mihu.ai/docs/api-docs.json get /api/v1/agents Returns paginated agents with their configured settings, knowledge, rules, channels, and related resources. Use this endpoint to browse agents, filter by lifecycle status, or search by name, company, or role before selecting an agent for calls, campaigns, messaging, or configuration updates. # List intents for an agent Source: https://developers.mihu.ai/api-reference/agents/list-intents-for-an-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/intents Returns all intents configured for an agent. Intents define actions or integrations the agent can trigger when a conversation matches a goal, such as booking an appointment, collecting details, or calling a webhook. # List webhooks for an agent Source: https://developers.mihu.ai/api-reference/agents/list-webhooks-for-an-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/webhooks Returns webhooks configured for one agent. Use this to see which event notifications are delivered for the agent and whether each webhook is active. Each agent can have up to 5 webhooks. # Phone numbers owned by an agent Source: https://developers.mihu.ai/api-reference/agents/phone-numbers-owned-by-an-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/phone-numbers Returns the full phone-number records bound to this agent on any channel (call, SMS, WhatsApp). Same shape as /api/v1/phone-numbers, scoped to the agent. Only includes numbers in your owned inventory — for external numbers (e.g. WhatsApp Business lines), use /api/v1/agents/{uuid}/channels. # Provision call channel for an agent Source: https://developers.mihu.ai/api-reference/agents/provision-call-channel-for-an-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/call/provision Connects a purchased phone number to the agent's call channel and performs the required telephony provisioning. Use this after buying a number and before placing or receiving calls with the agent. The response returns the updated agent and provisioning result, including call_setting_uuid when created. # Publish the intent's action (make it live) Source: https://developers.mihu.ai/api-reference/agents/publish-the-intents-action-make-it-live https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/intents/{intentUuid}/event/publish Sets the configured event's status to `deployed` so the agent will run it at runtime. The event must already be configured (PUT the event first). # Replace agent appointment settings and schedule assignments Source: https://developers.mihu.ai/api-reference/agents/replace-agent-appointment-settings-and-schedule-assignments https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/appointments Configures which schedules an agent uses for booking and how the runtime AI should pick between them. Each entry in `schedule_assignments` should include both `name` (a short label the AI sees, e.g. 'Service Appointment') and `description` (when to use it, e.g. 'When the customer requires routine maintenance'). These two fields are how the runtime agent decides which schedule to offer a contact — assignments created without them will be ignored by the AI's selection logic. # Replace agent guidelines Source: https://developers.mihu.ai/api-reference/agents/replace-agent-guidelines https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/guidelines Replaces all guidelines for the agent. Guidelines are short behavioral rules that shape how the agent should respond. Use this endpoint for bulk edits or external syncs; use POST /guidelines to append one guideline without replacing the existing list. # Replace agent notes Source: https://developers.mihu.ai/api-reference/agents/replace-agent-notes https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/notes Replaces all notes for the agent. Notes are reference facts the agent can use during conversations, such as product details, company policies, or context that does not need step-by-step structure. Use this for bulk replacement; use POST /notes for one-off additions. # Replace agent procedures Source: https://developers.mihu.ai/api-reference/agents/replace-agent-procedures https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/procedures Replaces all procedures for the agent, including their ordered steps. Procedures are multi-step instructions the agent can follow during conversations. Use this endpoint for complete procedure syncs; use POST /procedures to add one procedure without replacing the full set. # Replace agent training data Source: https://developers.mihu.ai/api-reference/agents/replace-agent-training-data https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/training Replaces all training rows for the agent. Training rows are examples or knowledge snippets that help the agent map customer language to appropriate responses. Use this endpoint for full training imports; use POST /training to append one row. # Replace/sync an agent Source: https://developers.mihu.ai/api-reference/agents/replacesync-an-agent https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid} Synchronizes the agent with the supplied payload. This has the same behavior as PATCH: scalar fields are updated, settings are merged, and included collection sections replace that section for the agent. Use this for full external sync jobs or configuration import flows. # Set the intent's action (event) Source: https://developers.mihu.ai/api-reference/agents/set-the-intents-action-event https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/intents/{intentUuid}/event Sets (replaces) the single action the intent performs. Pick `event_type` and provide its fields: - `webhook` → `webhook.url` (+ optional `webhook.auth_token`). - `app` → `app_uid` + `action_key` (+ `config`). Built-in apps need no connection (omit `app_connection_uuid`). External apps require `app_connection_uuid` — an already-connected, active account; the API cannot create/authenticate connections (that's done in the dashboard). If the app isn't connected or the connection isn't active, the call returns 422 telling you to connect it in the dashboard. - `scenario` → `flow_uuid` of a DEPLOYED flow. Draft flows are rejected with 422 — deploy via POST /api/v1/flow/{uuid}/deploy first. - `agent` → `agent_uuid` (+ optional `channel` of `call`|`whatsapp` and `channel_action_name`). References are by uuid/key (never numeric ids). Discover apps/actions via GET /flow/apps and /flow/apps/{uid}/actions; connections via GET /flow/connections; flows via GET /flows. # Soft-delete an agent Source: https://developers.mihu.ai/api-reference/agents/soft-delete-an-agent https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid} Soft-deletes the agent. Child records (notes, guidelines, training, intents, etc.) remain in the database for recoverability but are no longer reachable via the API. Provider-side resources (phone numbers, WhatsApp etc.) are NOT torn down — release/unbind phone numbers separately first. # Test the intent's app action Source: https://developers.mihu.ai/api-reference/agents/test-the-intents-app-action https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/intents/{intentUuid}/event/test Runs the configured app action and returns the result — the same engine and safe-list the Studio/Flow tests use. Read-only actions (get_record, query_records, ai_query, Zoho search via live, …) execute live; write actions dry-run (validate the resolved config without calling the third party). Pass `live: true` to force real execution, `dry_run: true` to force validation-only, and `config_override` to test a different config without saving it. Only `app` events are testable here — `webhook` is exercised via its URL, `scenario` via the Flow step-test endpoint, and `agent` handoff has nothing to execute. # Unpublish the intent's action (back to draft) Source: https://developers.mihu.ai/api-reference/agents/unpublish-the-intents-action-back-to-draft https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/intents/{intentUuid}/event/unpublish Sets the event's status back to `draft` so the agent no longer runs it, without deleting the configuration. # Update a single guideline Source: https://developers.mihu.ai/api-reference/agents/update-a-single-guideline https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/guidelines/{guidelineUuid} Updates one guideline on the agent. Use this to adjust a behavior rule or its ordering without replacing the full guideline list. Only supplied fields are changed. # Update a single note Source: https://developers.mihu.ai/api-reference/agents/update-a-single-note https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/notes/{noteUuid} Updates one note on the agent. Use this for small edits to reference facts without replacing the full notes collection. Only supplied fields are changed. # Update a single procedure (and replace its steps if provided) Source: https://developers.mihu.ai/api-reference/agents/update-a-single-procedure-and-replace-its-steps-if-provided https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/procedures/{procedureUuid} Updates one procedure on the agent. Use this to rename a workflow, revise its description, or replace the ordered steps that guide the agent during conversations. If a steps array is included, it replaces the procedure's existing steps; other procedures are not changed. # Update a single training row Source: https://developers.mihu.ai/api-reference/agents/update-a-single-training-row https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/training/{trainingUuid} Updates one training row on the agent. Use this to refine an example, intent label, or response without replacing the full training set. Only supplied fields are changed. # Update a webhook Source: https://developers.mihu.ai/api-reference/agents/update-a-webhook https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/webhooks/{webhookUuid} Updates one agent webhook. Use this to change the destination URL, event subscriptions, signing secret, or active state. Only supplied fields are changed; sending an empty secret clears the stored secret. # Update an agent Source: https://developers.mihu.ai/api-reference/agents/update-an-agent https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid} Updates core agent fields, voice/text settings, and any included collection sections. Use PATCH for partial changes to the agent profile or settings. If a collection section such as notes, guidelines, procedures, training, routing_rules, or guard_rules is included, that section replaces the existing section. # Update an intent Source: https://developers.mihu.ai/api-reference/agents/update-an-intent https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/intents/{intentUuid} Updates a custom intent. Use this to change trigger wording, confidence threshold, webhook target, response handling, or collected parameters. If `parameters` is included, it replaces the full parameter list. System intents cannot be modified. # Update call behavior Source: https://developers.mihu.ai/api-reference/agents/update-call-behavior https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/call-behavior Partial update of recording, background sound (on/off, ambience, volume), noise cancellation, silence timeout, and max call duration. background_sound_ambience must be one of: office, call_center, lobby_ambiance, calm_office, street, restaurant, restaurant_ambience, building_lobby_ambience, bank_lobby_ambience. background_sound_volume is 0.1–1.0. noise_cancellation is a boolean (true = on, false = off) and is propagated to the agent's connections automatically. # Update compliance settings Source: https://developers.mihu.ai/api-reference/agents/update-compliance-settings https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/compliance Partial update of the EU GDPR and HIPAA compliance flags. # Update interaction settings Source: https://developers.mihu.ai/api-reference/agents/update-interaction-settings https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/interaction Partial update of the agent's first/greeting/voicemail/end-call/silence messages. Only supplied fields are changed. # Update interruption settings Source: https://developers.mihu.ai/api-reference/agents/update-interruption-settings https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/interruption Updates the interruption mode (sensitive|balanced|never_stop|advance) and/or the advance-mode overrides. Changing the mode alone does not overwrite stored overrides — the advanced block is always read back layered over the selected mode's defaults, and only takes effect while mode is 'advance'. To change the overrides, send the `advanced` object explicitly. Out-of-range values are clamped. # Update phone normalizers Source: https://developers.mihu.ai/api-reference/agents/update-phone-normalizers https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/normalizers Partial update of the outbound and inbound phone-number normalizer rules. Each side accepts default_prefix, condition_length, condition_prefix. # Update the agent's email signature Source: https://developers.mihu.ai/api-reference/agents/update-the-agents-email-signature https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/email-signature Sets the email signature appended to this agent's outgoing emails (same value as the agent's Text Settings). Accepts HTML, which is sanitized before saving. Send an empty string to clear it. The agent must have a connected email address (Mails channel). # Update voice profile Source: https://developers.mihu.ai/api-reference/agents/update-voice-profile https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/voice-profile Updates the spoken language and/or the selected voice. The voice is chosen by its uuid from the voice library; changing it changes which fields GET /voice-advanced returns. # Update voice tuning Source: https://developers.mihu.ai/api-reference/agents/update-voice-tuning https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/voice-advanced Updates the voice tuning fields. The accepted fields depend on the agent's selected voice — call GET /api/v1/agents/{uuid}/voice-advanced first to learn them. A body containing fields the current voice does not support returns 422 with the supported field list. Out-of-range values are clamped. Returns the refreshed supported-fields shape. # Aggregated call metrics for a time window (authoritative call count) Source: https://developers.mihu.ai/api-reference/analytics/aggregated-call-metrics-for-a-time-window-authoritative-call-count https://app.mihu.ai/docs/api-docs.json get /api/v1/analytics/calls Returns volume, direction split, AI vs human handling, durations (seconds), outcomes, and cost for calls within [from, to). This endpoint is the authoritative source for call counts; /api/v1/analytics/conversations totals exclude calls without a resolvable channel via conversations.call_id, so the two counts may differ slightly. Channel filter restricts to call-bearing channels. # Appointment lifecycle metrics (event-in-period semantics) Source: https://developers.mihu.ai/api-reference/analytics/appointment-lifecycle-metrics-event-in-period-semantics https://app.mihu.ai/docs/api-docs.json get /api/v1/analytics/appointments Counters reflect events whose state transitioned during [from, to). created uses appointments.created_at; scheduled uses start_time; completed/cancelled use updated_at on rows in that status. by_source_channel attributes appointments via the linked conversation; appointments with no conversation appear as 'other' (only when no channel filter is supplied). # Cross-channel conversation-session metrics Source: https://developers.mihu.ai/api-reference/analytics/cross-channel-conversation-session-metrics https://app.mihu.ai/docs/api-docs.json get /api/v1/analytics/sessions Returns volume, voice/text split, completion/timeout/active breakdowns, evaluation coverage, average duration, messages per session, and p50/p95 latency (voice only). # Cursor-paginated raw message export Source: https://developers.mihu.ai/api-reference/analytics/cursor-paginated-raw-message-export https://app.mihu.ai/docs/api-docs.json get /api/v1/analytics/messages Returns one row per message in [from, to). Subject to workspace policy: when ANALYTICS_MESSAGES_EXPORT=disabled the endpoint returns 403; when 'masked' the content field is replaced with '***'. Sort order is (created_at ASC, message_uuid ASC). # Distribution of AI evaluations across sentiment, emotion, satisfaction, outcome, escalation, and knowledge gap Source: https://developers.mihu.ai/api-reference/analytics/distribution-of-ai-evaluations-across-sentiment-emotion-satisfaction-outcome-escalation-and-knowledge-gap https://app.mihu.ai/docs/api-docs.json get /api/v1/analytics/evaluations Returns aggregate evaluation distributions for sessions in a time range. Use this endpoint to understand conversation quality trends across sentiment, emotions, satisfaction score, outcome, human escalation, and knowledge gaps. Filter by channel, agent, or campaign and optionally include the previous period for comparison. # Intent breakdown with outcome and per-channel distribution Source: https://developers.mihu.ai/api-reference/analytics/intent-breakdown-with-outcome-and-per-channel-distribution https://app.mihu.ai/docs/api-docs.json get /api/v1/analytics/intents Returns one entry per detected intent, sorted by count desc. Each entry carries success/fail outcome counts, average confidence, and channel breakdown. # Per-channel conversation rollup Source: https://developers.mihu.ai/api-reference/analytics/per-channel-conversation-rollup https://app.mihu.ai/docs/api-docs.json get /api/v1/analytics/conversations Returns one entry per active channel with totals, direction split, durations (call-bearing channels only), and short/long buckets. duration_sec is null for non-call channels. For call-bearing channels (call, whatsapp_call), totals.conversations equals inbound + outbound from the calls table — orphaned conversations without a call_id are not counted; use /api/v1/analytics/calls for the authoritative call total. # Cancel an appointment request Source: https://developers.mihu.ai/api-reference/appointment-requests/cancel-an-appointment-request https://app.mihu.ai/docs/api-docs.json post /api/v1/appointment-requests/{uuid}/cancel Cancels a pending appointment request without creating an appointment. Use this when the requester withdraws the booking or the proposed time should no longer be considered. Only requests with pending status can be cancelled. # Create a new appointment request Source: https://developers.mihu.ai/api-reference/appointment-requests/create-a-new-appointment-request https://app.mihu.ai/docs/api-docs.json post /api/v1/appointment-requests Creates a proposed booking for a schedule. Use this when the requested time should be reviewed before becoming a confirmed appointment. Provide an existing contact_uuid, or provide contact details so the API can find or create the contact automatically. # Get a specific appointment request Source: https://developers.mihu.ai/api-reference/appointment-requests/get-a-specific-appointment-request https://app.mihu.ai/docs/api-docs.json get /api/v1/appointment-requests/{uuid} Returns one appointment request by UUID, including requested time, contact details, schedule reference, status, and notes. Use this before approving, rejecting, cancelling, or displaying the request in a scheduling workflow. # Get available time slots for a schedule Source: https://developers.mihu.ai/api-reference/appointment-requests/get-available-time-slots-for-a-schedule https://app.mihu.ai/docs/api-docs.json get /api/v1/appointment-requests/available-slots Returns available time slots for one schedule on a specific date. Use this before creating an appointment request so callers can offer valid start times based on the schedule's booking rules and existing appointments. # Get list of appointment requests Source: https://developers.mihu.ai/api-reference/appointment-requests/get-list-of-appointment-requests https://app.mihu.ai/docs/api-docs.json get /api/v1/appointment-requests Returns appointment requests ordered for review and scheduling workflows. Use this endpoint to find pending booking requests, filter requests by schedule or date range, and decide which requests should be approved, rejected, cancelled, or converted into appointments. # Create a new appointment Source: https://developers.mihu.ai/api-reference/appointments/create-a-new-appointment https://app.mihu.ai/docs/api-docs.json post /api/v1/appointments Creates an appointment on a schedule. Use this when booking a time slot directly through the API. Provide schedule_uuid, title, start_time, and end_time; optionally attach a contact, status, notes, and custom question answers. **Timezones.** start_time and end_time follow the global 'Dates and times' rule: send them WITHOUT an offset (`2026-08-08 10:00:00`) to mean YOUR timezone — the member's profile timezone for a per-user token, the workspace's for a workspace token, or whatever `X-Timezone` you set — or WITH an offset (`2026-08-08T10:00:00+02:00`) to name the exact instant yourself. Either way the response echoes the appointment back in your timezone, so the time you send is the time you read. # Delete an appointment Source: https://developers.mihu.ai/api-reference/appointments/delete-an-appointment https://app.mihu.ai/docs/api-docs.json delete /api/v1/appointments/{uuid} Deletes an appointment by UUID. Use this when a booked time slot should be removed from the calendar. If you only need to change approval state, use POST /api/v1/appointments/{uuid}/status instead. # Get a specific appointment Source: https://developers.mihu.ai/api-reference/appointments/get-a-specific-appointment https://app.mihu.ai/docs/api-docs.json get /api/v1/appointments/{uuid} Returns full details for one appointment, including schedule, contact, status, notes, custom answers, and timestamps. Use this to inspect a booking before editing or changing its status. # Get all appointments (calendar) Source: https://developers.mihu.ai/api-reference/appointments/get-all-appointments-calendar https://app.mihu.ai/docs/api-docs.json get /api/v1/appointments Returns appointments ordered by start time. Per-user JWTs only receive appointments on shared schedules or schedules assigned to that user. Workspace API tokens retain workspace-wide access. Each result includes schedule, assigned schedule users, appointment user, and contact details when available. # Update an appointment Source: https://developers.mihu.ai/api-reference/appointments/update-an-appointment https://app.mihu.ai/docs/api-docs.json put /api/v1/appointments/{uuid} Updates an existing appointment. Use this to reschedule, change title or notes, update custom answers, or change status. If end_time is supplied, it must be after start_time. **Timezones.** start_time and end_time follow the global 'Dates and times' rule: no offset means your timezone, an explicit offset names the exact instant. The response echoes the appointment back in your timezone. # Update appointment status Source: https://developers.mihu.ai/api-reference/appointments/update-appointment-status https://app.mihu.ai/docs/api-docs.json post /api/v1/appointments/{uuid}/status Changes only the appointment status. Use this to approve, move back to pending, or reject an appointment without modifying the time, schedule, contact, notes, or custom answers. # Assign a WhatsApp number to a user's assistant Source: https://developers.mihu.ai/api-reference/assistant-channels/assign-a-whatsapp-number-to-a-users-assistant https://app.mihu.ai/docs/api-docs.json post /api/v1/assistant-channels/whatsapp Detaches the number from whatever Agent currently owns it — a number serves one consumer at a time. # Assign an email address to a user's assistant Source: https://developers.mihu.ai/api-reference/assistant-channels/assign-an-email-address-to-a-users-assistant https://app.mihu.ai/docs/api-docs.json post /api/v1/assistant-channels/email Detaches the address from whatever Agent currently owns it — an address serves one consumer at a time. # Assign an SMS-enabled number to a user's assistant Source: https://developers.mihu.ai/api-reference/assistant-channels/assign-an-sms-enabled-number-to-a-users-assistant https://app.mihu.ai/docs/api-docs.json post /api/v1/assistant-channels/sms Unlike email/WhatsApp, SMS routing isn't resolved from a database lookup per message — this makes a LIVE call to the telephony provider to repoint the number's messaging profile webhook. Detaches the number from whatever Agent currently owns it. # Configure 2FA for a channel Source: https://developers.mihu.ai/api-reference/assistant-channels/configure-2fa-for-a-channel https://app.mihu.ai/docs/api-docs.json put /api/v1/assistant-channels/{channel}/security Static PIN is the only verification method today. Enabling 2FA without ever having set a PIN fails — set one first (or in the same request). # Get a user's assistant email channel config Source: https://developers.mihu.ai/api-reference/assistant-channels/get-a-users-assistant-email-channel-config https://app.mihu.ai/docs/api-docs.json get /api/v1/assistant-channels/email # Get a user's assistant SMS channel config Source: https://developers.mihu.ai/api-reference/assistant-channels/get-a-users-assistant-sms-channel-config https://app.mihu.ai/docs/api-docs.json get /api/v1/assistant-channels/sms # Get a user's assistant WhatsApp channel config Source: https://developers.mihu.ai/api-reference/assistant-channels/get-a-users-assistant-whatsapp-channel-config https://app.mihu.ai/docs/api-docs.json get /api/v1/assistant-channels/whatsapp # List email addresses assignable to an assistant Source: https://developers.mihu.ai/api-reference/assistant-channels/list-email-addresses-assignable-to-an-assistant https://app.mihu.ai/docs/api-docs.json get /api/v1/assistant-channels/email/addresses Same address inventory the Mails Studio app manages. Excludes addresses already claimed by a different user's assistant. # List numbers already set up for SMS via an agent that can also feed an assistant Source: https://developers.mihu.ai/api-reference/assistant-channels/list-numbers-already-set-up-for-sms-via-an-agent-that-can-also-feed-an-assistant https://app.mihu.ai/docs/api-docs.json get /api/v1/assistant-channels/sms/numbers Only numbers with an existing agent SMS binding are returned, not every SMS-capable number on the account. Excludes numbers already claimed by a different user's assistant. # List WhatsApp numbers assignable to an assistant Source: https://developers.mihu.ai/api-reference/assistant-channels/list-whatsapp-numbers-assignable-to-an-assistant https://app.mihu.ai/docs/api-docs.json get /api/v1/assistant-channels/whatsapp/numbers Same inventory the WhatsApp Studio/Channels app manages. Excludes numbers already claimed by a different user's assistant. # Release a user's assigned email inbox Source: https://developers.mihu.ai/api-reference/assistant-channels/release-a-users-assigned-email-inbox https://app.mihu.ai/docs/api-docs.json delete /api/v1/assistant-channels/email # Release a user's assigned SMS number Source: https://developers.mihu.ai/api-reference/assistant-channels/release-a-users-assigned-sms-number https://app.mihu.ai/docs/api-docs.json delete /api/v1/assistant-channels/sms Does not revert the provider webhook to any agent — there's no way to know which one should reclaim it. Inbound SMS to the number is a no-op until it's assigned to something again. # Release a user's assigned WhatsApp number Source: https://developers.mihu.ai/api-reference/assistant-channels/release-a-users-assigned-whatsapp-number https://app.mihu.ai/docs/api-docs.json delete /api/v1/assistant-channels/whatsapp # Set 'Your email' and send the confirmation link Source: https://developers.mihu.ai/api-reference/assistant-channels/set-your-email-and-send-the-confirmation-link https://app.mihu.ai/docs/api-docs.json post /api/v1/assistant-channels/email/personal-contact A one-time confirmation link is emailed to this address. It only starts reaching the assistant after that link is clicked. Calling this again resends the link. # Set 'Your number' — verified immediately, no link to click Source: https://developers.mihu.ai/api-reference/assistant-channels/set-your-number-—-verified-immediately-no-link-to-click https://app.mihu.ai/docs/api-docs.json post /api/v1/assistant-channels/whatsapp/personal-contact WhatsApp already authenticates the sending number at the transport level before its webhook ever reaches this app, so there's no separate confirmation step like email's. # Set 'Your number' — verified immediately, no link to click Source: https://developers.mihu.ai/api-reference/assistant-channels/set-your-number-—-verified-immediately-no-link-to-click-1 https://app.mihu.ai/docs/api-docs.json post /api/v1/assistant-channels/sms/personal-contact The telephony provider already authenticates the sending number at the transport level before its webhook ever reaches this app, so there's no separate confirmation step like email's. # Delete an availability type Source: https://developers.mihu.ai/api-reference/availability-types/delete-an-availability-type https://app.mihu.ai/docs/api-docs.json delete /api/v1/availability-types/{uuid} Deletes an availability type by UUID. Use this only after confirming it is no longer needed by schedules. Once deleted, it is no longer available for new schedule creation. # Get a specific availability type Source: https://developers.mihu.ai/api-reference/availability-types/get-a-specific-availability-type https://app.mihu.ai/docs/api-docs.json get /api/v1/availability-types/{uuid} Returns one availability type by UUID, including booking duration, buffers, working-hours configuration, approval behavior, and resource limits. Use this before editing a schedule or before updating the availability type itself. # Get all availability types Source: https://developers.mihu.ai/api-reference/availability-types/get-all-availability-types https://app.mihu.ai/docs/api-docs.json get /api/v1/availability-types Returns every availability type in the workspace, ordered by name. Use this endpoint before creating schedules so you can choose the availability_type_uuid that controls duration, buffers, booking rules, and approval behavior. # Update an availability type Source: https://developers.mihu.ai/api-reference/availability-types/update-an-availability-type https://app.mihu.ai/docs/api-docs.json put /api/v1/availability-types/{uuid} Updates an existing availability type. Use this to change shared booking rules for schedules that depend on this type, such as duration, buffer time, required approval, double-booking behavior, or working-hours settings. Only supplied fields are changed. # Answer the build conversation Source: https://developers.mihu.ai/api-reference/builders/answer-the-build-conversation https://app.mihu.ai/docs/api-docs.json post /api/v1/builder-agents/{uuid}/answers Reply to the questions the builder asked while in `gathering`. Send everything as one free-text `message` — you can answer several questions in a single sentence (e.g. 'Use stored Zoho credentials, EU region, every 5 minutes, always-on'). **This is step 4 of the conversation loop** (see POST /api/v1/builder-agents): - Only valid while the conversation is `gathering`. Answering a `processing` conversation is rejected (it's still working on the previous turn); a `deployed` one is rejected (already finished). - The call returns **immediately** with `status: processing` — your answer is queued and the builder resumes in the background. - Then **poll** `GET /api/v1/builder-agents/{uuid}` (~2-3s) again: it returns either the next `gathering` round (more `message` + `questions`) or a terminal `deployed`/`failed`. Repeat answer → poll until the status is `deployed` (the `builder` field has the live app + preview URL) or `failed`. **After it's deployed:** the conversation isn't locked — to change the live app, send your request to POST /api/v1/builder-agents/{uuid}/rebuild (this endpoint only handles the question phase and returns 409 once deployed). # Approve a build conversation Source: https://developers.mihu.ai/api-reference/builders/approve-a-build-conversation https://app.mihu.ai/docs/api-docs.json post /api/v1/builder-agents/{uuid}/approve The builder pauses once at `status: awaiting_approval` and asks you to confirm building, deploying and running QA. Call this to give the one-time go-ahead. It returns immediately with `status: processing`; poll GET /api/v1/builder-agents/{uuid} until `deployed`/`failed`. (Pass `auto_approve: true` on create to skip this gate.) # Change a deployed build (rebuild) Source: https://developers.mihu.ai/api-reference/builders/change-a-deployed-build-rebuild https://app.mihu.ai/docs/api-docs.json post /api/v1/builder-agents/{uuid}/rebuild A build conversation does not lock once `deployed` — you can keep refining it. Because /answers is only for the question phase and rejects a finished conversation, send post-deploy change requests here instead. **When to use which:** - `status: gathering` → use POST /answers (you're still answering the builder's questions). - `status: deployed` or `failed` → use this endpoint. It replaces the running app with a corrected version, preserving the original intent unless your request changes it. Like the rest of the flow it returns immediately with `status: processing`; poll GET /api/v1/builder-agents/{uuid} until it is `deployed` again (the `builder` field carries the updated app + preview URL) or `failed`. Rejected with 409 while a rebuild is already `processing`. # Create a builder from your own code Source: https://developers.mihu.ai/api-reference/builders/create-a-builder-from-your-own-code https://app.mihu.ai/docs/api-docs.json post /api/v1/builders Deploys the supplied files to a cloud sandbox and starts your app. Returns the running builder with a public URL. To build from a description instead, use POST /api/v1/builder-agents. # Create SSH access Source: https://developers.mihu.ai/api-reference/builders/create-ssh-access https://app.mihu.ai/docs/api-docs.json post /api/v1/builders/{uuid}/ssh Creates time-limited SSH access to the builder's sandbox and returns a ready-to-run `ssh_command`, a `token`, and `expires_at`. The builder must be running. # Delete a build conversation Source: https://developers.mihu.ai/api-reference/builders/delete-a-build-conversation https://app.mihu.ai/docs/api-docs.json delete /api/v1/builder-agents/{uuid} Removes a build conversation from history. Any builder it already deployed is kept — delete that separately via DELETE /api/v1/builders/{uuid} if you also want the running app gone. # Delete a builder Source: https://developers.mihu.ai/api-reference/builders/delete-a-builder https://app.mihu.ai/docs/api-docs.json delete /api/v1/builders/{uuid} Deletes the sandbox VM. For code builders the source history is retained on the platform. # Generate and run tests Source: https://developers.mihu.ai/api-reference/builders/generate-and-run-tests https://app.mihu.ai/docs/api-docs.json post /api/v1/builders/{uuid}/test Generates and runs tests (unit + HTTP/acceptance) against the live builder and returns the results. Set `fix=true` to apply one automatic fix round if tests fail. # Get a build conversation Source: https://developers.mihu.ai/api-reference/builders/get-a-build-conversation https://app.mihu.ai/docs/api-docs.json get /api/v1/builder-agents/{uuid} The polling endpoint that drives the whole conversation. Call it repeatedly (~every 2-3 seconds) after starting a conversation or sending an answer. **Read `status` to decide what to do next:** - `processing` — the builder is still working. Keep polling, do nothing else. - `gathering` — it needs input. Show `message` and `questions` to the user, then POST to /answers. - `deployed` — done. The `builder` field holds the running app (with `preview_url`). Stop polling. - `failed` — done unsuccessfully. Stop polling; start a new conversation with a revised prompt. # Get a builder Source: https://developers.mihu.ai/api-reference/builders/get-a-builder https://app.mihu.ai/docs/api-docs.json get /api/v1/builders/{uuid} # Get builder logs Source: https://developers.mihu.ai/api-reference/builders/get-builder-logs https://app.mihu.ai/docs/api-docs.json get /api/v1/builders/{uuid}/logs Returns the app's recent combined stdout/stderr. # Get the latest QA report Source: https://developers.mihu.ai/api-reference/builders/get-the-latest-qa-report https://app.mihu.ai/docs/api-docs.json get /api/v1/builders/{uuid}/qa Returns the most recent stored QA report for the builder (code review + tests). # Get total spending Source: https://developers.mihu.ai/api-reference/builders/get-total-spending https://app.mihu.ai/docs/api-docs.json get /api/v1/builders/spending Total spend across all the tenant's builders plus a per-builder breakdown. Cost accrues while a builder runs and freezes when stopped. # List build conversations Source: https://developers.mihu.ai/api-reference/builders/list-build-conversations https://app.mihu.ai/docs/api-docs.json get /api/v1/builder-agents Returns all AI build conversations for the tenant, newest first. # List builders Source: https://developers.mihu.ai/api-reference/builders/list-builders https://app.mihu.ai/docs/api-docs.json get /api/v1/builders Returns all builders for the tenant (deployed code and AI-generated apps), newest first. # List files in the builder Source: https://developers.mihu.ai/api-reference/builders/list-files-in-the-builder https://app.mihu.ai/docs/api-docs.json get /api/v1/builders/{uuid}/files Lists files and folders in the builder's live filesystem. # Read a file from the builder Source: https://developers.mihu.ai/api-reference/builders/read-a-file-from-the-builder https://app.mihu.ai/docs/api-docs.json get /api/v1/builders/{uuid}/files/read # Recreate SSH access Source: https://developers.mihu.ai/api-reference/builders/recreate-ssh-access https://app.mihu.ai/docs/api-docs.json post /api/v1/builders/{uuid}/ssh/recreate Revokes the current SSH access and issues a fresh token + command. The builder must be running. # Revoke SSH access Source: https://developers.mihu.ai/api-reference/builders/revoke-ssh-access https://app.mihu.ai/docs/api-docs.json delete /api/v1/builders/{uuid}/ssh Revokes all SSH access to the builder's sandbox. # Run a command in the builder Source: https://developers.mihu.ai/api-reference/builders/run-a-command-in-the-builder https://app.mihu.ai/docs/api-docs.json post /api/v1/builders/{uuid}/exec Executes a shell command inside the builder's sandbox, from the app root, and returns its exit code and output. # Run an AI code review Source: https://developers.mihu.ai/api-reference/builders/run-an-ai-code-review https://app.mihu.ai/docs/api-docs.json post /api/v1/builders/{uuid}/review Runs an AI review of the builder's code and returns the report (issues + verdict). Report only — it does not change the running service. # Set idle auto-stop Source: https://developers.mihu.ai/api-reference/builders/set-idle-auto-stop https://app.mihu.ai/docs/api-docs.json post /api/v1/builders/{uuid}/auto-stop Sets the idle minutes before the builder auto-stops. Use 0 to keep it always-on. # Start a build conversation Source: https://developers.mihu.ai/api-reference/builders/start-a-build-conversation https://app.mihu.ai/docs/api-docs.json post /api/v1/builder-agents Describe what you want in one sentence and the AI builder takes it from there. This is the entry point of an asynchronous, multi-turn conversation. **How it works (the full loop):** 1. `POST /api/v1/builder-agents` with your `prompt`. It returns **immediately** with `status: processing` and a `uuid` — the build does not run inline (that would exceed request timeouts), it runs in the background. 2. **Poll** `GET /api/v1/builder-agents/{uuid}` every ~2-3 seconds. While the builder is thinking it stays `processing`; keep polling. 3. When it needs input the status becomes `gathering`: read `message` (what it's asking) and `questions` (the list to answer). Typical questions: which credentials to use, region/fields, VM size, one-time vs always-on, backup frequency. 4. Reply with `POST /api/v1/builder-agents/{uuid}/answers` (a single `message`). That call also returns `processing` — poll again (step 2). The loop repeats until the builder has everything. 5. The conversation ends in one of two terminal states: - `deployed` — the app was generated and is running. The `builder` field holds the live builder (with `preview_url`). Operate it via the /api/v1/builders endpoints. - `failed` — generation could not complete. Start a new conversation with an adjusted prompt. **When it 'works':** a simple agent is usually `deployed` after 1-2 question rounds; each round is a few seconds of `processing`, plus ~1 minute for the final deploy. There is no fixed limit on rounds — keep answering until terminal. **Example:** prompt 'Watch my Zoho CRM leads every 5 minutes' → `processing` → `gathering` ('Use stored Zoho credentials or paste new ones? Which region?') → answer → `processing` → `deployed` with a preview URL. # Start (wake) a builder Source: https://developers.mihu.ai/api-reference/builders/start-wake-a-builder https://app.mihu.ai/docs/api-docs.json post /api/v1/builders/{uuid}/start # Stop a builder Source: https://developers.mihu.ai/api-reference/builders/stop-a-builder https://app.mihu.ai/docs/api-docs.json post /api/v1/builders/{uuid}/stop Halts the app; disk is kept. Start it again to resume. # Write a file to the builder Source: https://developers.mihu.ai/api-reference/builders/write-a-file-to-the-builder https://app.mihu.ai/docs/api-docs.json put /api/v1/builders/{uuid}/files Creates or overwrites a file in the builder's live filesystem. Optionally restart the app to apply code changes. # Forward (warm-transfer) the live call to another phone number Source: https://developers.mihu.ai/api-reference/call-actions/forward-warm-transfer-the-live-call-to-another-phone-number https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/forward Transfers the active call to another E.164 phone number. Use this when the caller needs a human representative, department, or external destination. The agent announces the transfer before the call is connected to the target number. # Hang up the live call (the agent speaks a goodbye message, then ends) Source: https://developers.mihu.ai/api-reference/call-actions/hang-up-the-live-call-the-agent-speaks-a-goodbye-message-then-ends https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/hangup Ends the active call after the agent speaks a closing message. Use this for manual live-call termination or when your system has decided the conversation is complete. If no message is provided, the configured end-of-call message is used. # Make the agent say a message in the live call Source: https://developers.mihu.ai/api-reference/call-actions/make-the-agent-say-a-message-in-the-live-call https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/say Makes the active call agent speak a text-to-speech message immediately. Use this for live operator interventions such as a short instruction, clarification, or closing line. Set end_call_after_spoken=true when the spoken message should be followed by hangup. # Mute the agent in the live call Source: https://developers.mihu.ai/api-reference/call-actions/mute-the-agent-in-the-live-call https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/mute Temporarily stops the agent from speaking on the active call. Use this when a human operator needs to take over, listen privately, or prevent the agent from responding while another action is happening. Call /unmute to let the agent speak again. # Unmute the agent in the live call Source: https://developers.mihu.ai/api-reference/call-actions/unmute-the-agent-in-the-live-call https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/unmute Allows the muted agent to speak again on the active call. Use this after a temporary human intervention or private listening period when the agent should resume normal conversation handling. # Get call details by UUID Source: https://developers.mihu.ai/api-reference/call/get-call-details-by-uuid https://app.mihu.ai/docs/api-docs.json get /api/v1/calls/{uuid} Returns one call by UUID with its status, direction, participant details, agent/contact/campaign context, timing, recording or live-monitoring URLs when available, and provider identifiers. Use this to inspect a completed call or monitor a recent call after creation. # Get paginated list of calls Source: https://developers.mihu.ai/api-reference/call/get-paginated-list-of-calls https://app.mihu.ai/docs/api-docs.json get /api/v1/calls Returns call records with pagination and optional filters. Use this endpoint to monitor inbound and outbound calls, review call status and duration, find calls for a contact or agent, and locate the UUID needed for detailed call inspection. # Initiate a new call Source: https://developers.mihu.ai/api-reference/call/initiate-a-new-call https://app.mihu.ai/docs/api-docs.json post /api/v1/call Initiates a call if the specified agent exists, has valid call settings, and the participant's phone number is provided. The call can include a custom greeting message, a prompt to guide the agent, and optional details about the participant. This endpoint is used to trigger outbound calls with specific configurations for agents and participants. # Assign or replace the rule attached to a campaign Source: https://developers.mihu.ai/api-reference/campaigns/assign-or-replace-the-rule-attached-to-a-campaign https://app.mihu.ai/docs/api-docs.json put /api/v1/campaigns/{uuid}/rule Attaches a rule (cadence, retry interval, working hours, escalation) to the campaign. The underlying schema is many-to-many but every code path treats it as one-rule-per-campaign, so this endpoint REPLACES any previously attached rule via sync(). Important caveat: changing the rule on a running ('In Process') campaign does NOT retroactively rebuild already-scheduled tasks — they still reflect the OLD cadence. New tasks created after the change (via add-contacts-to-pool, attach-pool, or republish) will use the new rule. For a hard reset on running campaigns, the safe sequence is: stop the campaign → assign new rule → publish again. # Attach one or more pools to a campaign Source: https://developers.mihu.ai/api-reference/campaigns/attach-one-or-more-pools-to-a-campaign https://app.mihu.ai/docs/api-docs.json post /api/v1/campaigns/{uuid}/pools Pools are additive (not replace). UUIDs already attached are silently skipped, UUIDs that don't resolve to a pool are returned in pool_uuids_not_found. If the campaign status is 'In Process', tasks are immediately created for every Pending ContactPoolItem in the newly attached pools, and ProcessWhatsAppCampaign is dispatched for text/sms campaigns. The attach + task creation are wrapped in a single DB transaction so a partial failure rolls back both the pivot rows and any tasks that were inserted. # Create a new campaign Source: https://developers.mihu.ai/api-reference/campaigns/create-a-new-campaign https://app.mihu.ai/docs/api-docs.json post /api/v1/campaigns Creates the campaign shell: name, channel type, agent, status, date window, and optional message settings. Use this when you want fine-grained control over setup. After creation, attach a rule and one or more pools, then publish the campaign to schedule work. # Delete a campaign Source: https://developers.mihu.ai/api-reference/campaigns/delete-a-campaign https://app.mihu.ai/docs/api-docs.json delete /api/v1/campaigns/{uuid} Soft-deletes a campaign by UUID. Use this when the campaign should no longer appear in normal campaign lists. Historical records remain available, and already-created tasks are not automatically removed by this endpoint. # Detach a pool from a campaign Source: https://developers.mihu.ai/api-reference/campaigns/detach-a-pool-from-a-campaign https://app.mihu.ai/docs/api-docs.json delete /api/v1/campaigns/{uuid}/pools/{pool_uuid} Removes the pool↔campaign association. Side effect: cancels any scheduled/queued/pending tasks created for THIS specific pool in THIS specific campaign. Cancellation is keyed on contact_pool_item_id (stored in tasks.task_data) — so if the same contact exists in another pool also attached to this campaign, those tasks are NOT affected. The pool itself and its contacts remain intact and can be reattached later. # Detach the rule from a campaign Source: https://developers.mihu.ai/api-reference/campaigns/detach-the-rule-from-a-campaign https://app.mihu.ai/docs/api-docs.json delete /api/v1/campaigns/{uuid}/rule Removes the rule association from the campaign. The rule itself is NOT deleted — it remains available to attach to other campaigns. Without a rule, future tasks fall back to system defaults (max 3 calls/day, 10 total, 09:00–18:00). Already-scheduled tasks are unaffected. # Get campaign details Source: https://developers.mihu.ai/api-reference/campaigns/get-campaign-details https://app.mihu.ai/docs/api-docs.json get /api/v1/campaigns/{uuid} Returns one campaign by UUID, including campaign configuration, agent reference, status, date window, attached rule and related campaign data when available. Use this before updating, publishing, attaching pools, or troubleshooting scheduled outreach. # Get paginated list of campaigns Source: https://developers.mihu.ai/api-reference/campaigns/get-paginated-list-of-campaigns https://app.mihu.ai/docs/api-docs.json get /api/v1/campaigns Returns campaigns ordered by creation date with optional filters for status and search text. Use this endpoint to monitor outreach programs, find draft campaigns that still need pools or rules, and review completed or archived campaigns. # Publish (activate) a campaign — schedule tasks and start processing Source: https://developers.mihu.ai/api-reference/campaigns/publish-activate-a-campaign-—-schedule-tasks-and-start-processing https://app.mihu.ai/docs/api-docs.json post /api/v1/campaigns/{uuid}/publish Transitions the campaign from Active/Draft/Paused/Failed to 'In Process' AND creates tasks for every pending ContactPoolItem in attached pools. The status change and task creation happen inside a single DB transaction — if task creation throws, the status flip is rolled back. For text/sms campaigns, also dispatches ProcessWhatsAppCampaign post-commit so the coordinator can sync delivery webhooks. Preconditions checked before doing any work: (1) campaign exists, (2) status is one of Active/Draft/Paused/Failed, (3) at least one pool is attached, (4) the agent has a channel binding, (5) at least one ContactPoolItem with status='Pending' exists across attached pools. Note: tasks_created may legitimately be 0 if all pending contacts are blacklisted, already completed, or already at max attempts — that's still a successful publish. # Update a campaign Source: https://developers.mihu.ai/api-reference/campaigns/update-a-campaign https://app.mihu.ai/docs/api-docs.json put /api/v1/campaigns/{uuid} Updates campaign metadata and configuration before or during its lifecycle. Use this to rename a campaign, change dates, adjust status, update the assigned agent, or modify channel-specific fields. Existing scheduled tasks are not automatically rebuilt unless a separate publish or pool operation creates work. # Create a coaching agent Source: https://developers.mihu.ai/api-reference/coaching-agents/create-a-coaching-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/coaching-agents Creates a coaching agent. Leave out `coaching_templates` and `training_examples` to start with ready-made samples you can edit later. Your first coaching agent automatically becomes the default. # Delete a coaching agent Source: https://developers.mihu.ai/api-reference/coaching-agents/delete-a-coaching-agent https://app.mihu.ai/docs/api-docs.json delete /api/v1/coaching-agents/{uuid} Deletes a coaching agent. Past coaching feedback is kept. The default coaching agent cannot be deleted — set another agent as default first. # Get one coaching agent Source: https://developers.mihu.ai/api-reference/coaching-agents/get-one-coaching-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/coaching-agents/{uuid} Returns one coaching agent with its full configuration — tone, thresholds, guidelines, templates, training examples, and resource library. # List coaching agents Source: https://developers.mihu.ai/api-reference/coaching-agents/list-coaching-agents https://app.mihu.ai/docs/api-docs.json get /api/v1/coaching-agents Returns your coaching agents, default agent first. Example: `GET /api/v1/coaching-agents?search=support&per_page=10`. # Set a coaching agent as default Source: https://developers.mihu.ai/api-reference/coaching-agents/set-a-coaching-agent-as-default https://app.mihu.ai/docs/api-docs.json post /api/v1/coaching-agents/{uuid}/set-default Makes this coaching agent the default coach. The previous default is switched off automatically — there is always exactly one default. No request body needed. # Update a coaching agent Source: https://developers.mihu.ai/api-reference/coaching-agents/update-a-coaching-agent https://app.mihu.ai/docs/api-docs.json patch /api/v1/coaching-agents/{uuid} Updates a coaching agent — only the fields you send are changed. The `coaching_templates`, `training_examples`, and `resource_library` lists replace the existing ones when you include them. Note: the current default agent stays default until you set another one as default. # Update a coaching agent (same as PATCH) Source: https://developers.mihu.ai/api-reference/coaching-agents/update-a-coaching-agent-same-as-patch https://app.mihu.ai/docs/api-docs.json put /api/v1/coaching-agents/{uuid} Works exactly like PATCH /api/v1/coaching-agents/{uuid}. # Bulk update analyzers Source: https://developers.mihu.ai/api-reference/contact-analyzers/bulk-update-analyzers https://app.mihu.ai/docs/api-docs.json put /api/v1/analyzers/bulk Updates multiple analyzers in one request. Each item uses `internal_id` to choose the analyzer and may include `update_behavior`, `analysis_goals`, and `example_values`. The request is all-or-nothing: if any row is invalid, no analyzer is changed and the response explains which row failed. # Get a single analyzer Source: https://developers.mihu.ai/api-reference/contact-analyzers/get-a-single-analyzer https://app.mihu.ai/docs/api-docs.json get /api/v1/analyzers/{internal_id} Returns one analyzer configuration by internal_id. Use this to inspect what the AI extracts, where the extracted value is applied, and whether the value is ignored, saved, or routed through approval. # List analyzer configurations Source: https://developers.mihu.ai/api-reference/contact-analyzers/list-analyzer-configurations https://app.mihu.ai/docs/api-docs.json get /api/v1/analyzers Returns analyzer settings. An analyzer tells the AI what to look for in a conversation and what to do when a value is found. The `internal_id` prefix shows the analyzer type: `b_` means a built-in contact field such as `b_name`, `b_email`, or `b_phone_number`; `f_` means a custom contact field such as `f_order_number` or `f_call_reason`; `p_` means a pipeline stage rule such as `p_initial_contact` or `p_closed_won`. Use `update_behavior` to decide whether the extracted value should be ignored, saved automatically, or require approval. # Update an analyzer configuration Source: https://developers.mihu.ai/api-reference/contact-analyzers/update-an-analyzer-configuration https://app.mihu.ai/docs/api-docs.json put /api/v1/analyzers/{internal_id} Updates how one analyzer behaves. `update_behavior` controls what happens when the AI finds a value: `dont_update` ignores it, `update_if_empty` saves only if the field is empty, `ask_approval_if_existing` asks for approval when replacing an existing value, `manual_approval` always requires approval, and `automatic_update` saves automatically. `analysis_goals` explains what the AI should extract. `example_values` gives sample values for better extraction. For built-in `b_*` contact fields, only `update_behavior` can be changed. For `pipeline` analyzers, `example_values` is not used. # Approve a pending field update Source: https://developers.mihu.ai/api-reference/contact-approvals/approve-a-pending-field-update https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/approvals/{uuid}/approve Approves a pending AI-suggested contact update and applies it to the target contact, custom field, or pipeline stage. Use this when a suggested value has been reviewed and should become the saved contact data. The approval history records who approved it and what changed. # Get a single approval by uuid Source: https://developers.mihu.ai/api-reference/contact-approvals/get-a-single-approval-by-uuid https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/approvals/{uuid} Returns one contact field approval with current value, suggested value, confidence, AI notes, status, reviewer notes, and related contact/conversation identifiers. Use this before approving, rejecting, or editing the suggestion. # Get the history of an approval Source: https://developers.mihu.ai/api-reference/contact-approvals/get-the-history-of-an-approval https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/approvals/{uuid}/history Returns paginated history for one contact field approval, newest first. Use this to audit approval, rejection, and value-change events, including reviewer notes and the values before and after each decision. # List pending contact field approvals Source: https://developers.mihu.ai/api-reference/contact-approvals/list-pending-contact-field-approvals https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/approvals Returns paginated AI-suggested contact updates. Use this queue to review values the agent extracted from conversations before applying them to contacts, custom fields, or pipeline stages. Defaults to status=Pending. # Reject a pending field update Source: https://developers.mihu.ai/api-reference/contact-approvals/reject-a-pending-field-update https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/approvals/{uuid}/reject Rejects a pending AI-suggested contact update and records reviewer notes. Use this when the extracted value should not be applied to the contact, custom field, or pipeline stage. # Soft-delete an approval Source: https://developers.mihu.ai/api-reference/contact-approvals/soft-delete-an-approval https://app.mihu.ai/docs/api-docs.json delete /api/v1/contacts/approvals/{uuid} Soft-deletes an approval suggestion without applying it to the contact. Use this to remove stale or irrelevant suggestions from the review queue while preserving audit history. # Update the suggested value of a pending approval Source: https://developers.mihu.ai/api-reference/contact-approvals/update-the-suggested-value-of-a-pending-approval https://app.mihu.ai/docs/api-docs.json put /api/v1/contacts/approvals/{uuid} Edits the suggested value on an approval before it is applied. Use this when the AI found the right field but the suggested value needs correction. Editing resets status to Pending and records a history entry. # Create a new custom contact field Source: https://developers.mihu.ai/api-reference/contact-fields/create-a-new-custom-contact-field https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/fields Generates a unique snake_case `key` from the supplied `name`, appending a numeric suffix if needed. New fields are appended to the end of the list. # Delete a custom contact field Source: https://developers.mihu.ai/api-reference/contact-fields/delete-a-custom-contact-field https://app.mihu.ai/docs/api-docs.json delete /api/v1/contacts/fields/{key} Deletes a custom contact field definition by key. Use this when the field should no longer be available on contacts. Existing values for that field are no longer part of the active contact schema. # Get a custom contact field by key Source: https://developers.mihu.ai/api-reference/contact-fields/get-a-custom-contact-field-by-key https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/fields/{key} Returns one custom contact field definition by key. Use this before updating the field, validating import payloads, or deciding which custom attributes contacts can store. # List custom contact fields Source: https://developers.mihu.ai/api-reference/contact-fields/list-custom-contact-fields https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/fields Returns custom contact fields for the workspace. By default only active fields are returned. Use include=all when syncing field configuration, or include=inactive when reviewing fields that should no longer be used for new contact data. # Update a custom contact field (name, is_active, etc.) Source: https://developers.mihu.ai/api-reference/contact-fields/update-a-custom-contact-field-name-is_active-etc https://app.mihu.ai/docs/api-docs.json put /api/v1/contacts/fields/{key} Updates only the fields you supply. The `key` is immutable — to use a different identifier, delete this field and create a new one. # Create a new pipeline stage Source: https://developers.mihu.ai/api-reference/contact-pipeline/create-a-new-pipeline-stage https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/pipeline Creates a pipeline stage that can be assigned to contacts. Use this to add a new lifecycle step such as Lead, Qualified, Customer, or Closed. If order is omitted, the stage is appended to the end of the current stage list. # Delete a pipeline stage Source: https://developers.mihu.ai/api-reference/contact-pipeline/delete-a-pipeline-stage https://app.mihu.ai/docs/api-docs.json delete /api/v1/contacts/pipeline/{uuid} Deletes a pipeline stage and detaches it from contacts that were assigned to it. Use this only when the stage should be removed completely. To keep history while preventing new use, update is_active=false instead. # Get a pipeline stage by uuid Source: https://developers.mihu.ai/api-reference/contact-pipeline/get-a-pipeline-stage-by-uuid https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/pipeline/{uuid} Returns one pipeline stage by UUID with its name, order, and active state. Use this before updating the stage or before assigning contacts to a specific pipeline position. # List pipeline stages Source: https://developers.mihu.ai/api-reference/contact-pipeline/list-pipeline-stages https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/pipeline Returns pipeline stages ordered by their display order. By default only active stages are returned. Use include=all when syncing a full configuration list, or include=inactive when reviewing stages that are no longer used for new contacts. # Update a pipeline stage Source: https://developers.mihu.ai/api-reference/contact-pipeline/update-a-pipeline-stage https://app.mihu.ai/docs/api-docs.json put /api/v1/contacts/pipeline/{uuid} Updates one pipeline stage. Use this to rename a stage, change its order, or mark it inactive. Only supplied fields are changed; contacts already assigned to the stage keep their association. # Enable or disable a contact setting Source: https://developers.mihu.ai/api-reference/contact-settings/enable-or-disable-a-contact-setting https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/settings/{key} Updates one contact setting by key. Use this to enable or disable contact data behavior for the workspace. The request body only needs `is_enabled`. # Get a contact setting by key Source: https://developers.mihu.ai/api-reference/contact-settings/get-a-contact-setting-by-key https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/settings/{key} Returns one contact setting by key, including whether it is currently enabled. Use this before toggling a setting or adapting client behavior to workspace policy. # List contact settings Source: https://developers.mihu.ai/api-reference/contact-settings/list-contact-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/settings Returns workspace-level contact settings. Use this to inspect which contact data behaviors are enabled before reading or updating contact records. # Create a new contact tag Source: https://developers.mihu.ai/api-reference/contact-tags/create-a-new-contact-tag https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/tags Creates a reusable tag for contacts. Use tags to segment contacts for filtering, targeting, and organization. Tags can later be assigned to contacts with POST /api/v1/contacts/{uuid}/add-tag. # Delete a tag Source: https://developers.mihu.ai/api-reference/contact-tags/delete-a-tag https://app.mihu.ai/docs/api-docs.json delete /api/v1/contacts/tags/{uuid} Deletes one contact tag and detaches it from contacts that had it assigned. Use this when the segment should be removed completely. To keep the tag for history while preventing new use, update it as inactive instead. # Get a tag by uuid Source: https://developers.mihu.ai/api-reference/contact-tags/get-a-tag-by-uuid https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/tags/{uuid} Returns one contact tag by UUID. Use this to inspect tag name, color, description, and active state before assigning it to contacts or updating it. # List contact tags Source: https://developers.mihu.ai/api-reference/contact-tags/list-contact-tags https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/tags Returns reusable contact tags for segmentation and filtering. By default only active tags are returned. Use include=all when syncing tag configuration, or include=inactive when reviewing tags no longer available for new assignments. # Update a tag Source: https://developers.mihu.ai/api-reference/contact-tags/update-a-tag https://app.mihu.ai/docs/api-docs.json put /api/v1/contacts/tags/{uuid} Updates one contact tag. Use this to rename a tag, change its color or description, or mark it inactive. Only supplied fields are changed, and existing contact assignments remain attached to the tag. # Add a contact to the blacklist Source: https://developers.mihu.ai/api-reference/contacts/add-a-contact-to-the-blacklist https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/{uuid}/blacklist Marks the contact as Blacklisted and records the blacklist entry. If the contact is already blacklisted, the existing entry is updated. # Add a note to a contact Source: https://developers.mihu.ai/api-reference/contacts/add-a-note-to-a-contact https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/{uuid}/notes Adds one note to the contact without changing existing notes. A contact can have any number of notes. # Assign or change the contact's current pipeline stage Source: https://developers.mihu.ai/api-reference/contacts/assign-or-change-the-contacts-current-pipeline-stage https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/{uuid}/assign-stage Sets the contact's current pipeline stage. Use this for the first assignment as well as to move the contact to a different stage — both cases are handled by the same endpoint. # Assign (or re-assign) a tag to a contact Source: https://developers.mihu.ai/api-reference/contacts/assign-or-re-assign-a-tag-to-a-contact https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/{uuid}/add-tag Assigns a tag to a contact. The operation is idempotent: if the tag is already assigned, the contact is left unchanged; if the tag was previously removed, the assignment is restored. # Create a new contact Source: https://developers.mihu.ai/api-reference/contacts/create-a-new-contact https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts Creates a contact record that agents and campaigns can use for conversations, calls, SMS, WhatsApp, and segmentation. Provide profile fields such as name, email, phone number, country code, timezone, language, preferred channel, and status. The response returns the created contact with its UUID for future API calls. **Custom fields:** any custom field key registered via POST /api/v1/contacts/fields can be sent as a top-level body property (string value). Use GET /api/v1/contacts/fields to discover available keys. Unknown keys return 422 with the offending key listed. In responses, every active custom field is returned as a top-level key — fields with no value appear as an empty string. # Delete a contact Source: https://developers.mihu.ai/api-reference/contacts/delete-a-contact https://app.mihu.ai/docs/api-docs.json delete /api/v1/contacts/{uuid} Soft-deletes a contact by UUID. Use this when the contact should no longer appear in normal contact lists or outreach flows. Existing historical conversations and activity records remain available for audit context. # Delete a contact note Source: https://developers.mihu.ai/api-reference/contacts/delete-a-contact-note https://app.mihu.ai/docs/api-docs.json delete /api/v1/contacts/{uuid}/notes/{noteUuid} Deletes one note from the contact. Other notes are not changed. # Get contact details Source: https://developers.mihu.ai/api-reference/contacts/get-contact-details https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/{uuid} Returns one contact with base fields, custom fields, tags, and timestamps. Use this before updating a contact, assigning tags, changing pipeline stage, or inspecting the contact profile for outreach. Every active custom field is returned as a top-level key on the response — fields with no value for this contact appear as an empty string. Use GET /api/v1/contacts/fields to discover the registered keys. # Get paginated list of blacklisted contacts Source: https://developers.mihu.ai/api-reference/contacts/get-paginated-list-of-blacklisted-contacts https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/blacklisted Returns contacts currently on the blacklist (status=Blacklisted with an active blacklist record). Supports search and pagination. # Get paginated list of contacts Source: https://developers.mihu.ai/api-reference/contacts/get-paginated-list-of-contacts https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts Returns a paginated contact list with filters for search, status, contact channel, pipeline stage, campaign, tag, pool, and creation date. Use this endpoint to find contacts before adding them to pools, campaigns, listings, or conversation workflows. # List a contact's notes Source: https://developers.mihu.ai/api-reference/contacts/list-a-contacts-notes https://app.mihu.ai/docs/api-docs.json get /api/v1/contacts/{uuid}/notes Returns all notes attached to the contact, newest first. A contact can have any number of notes. Use notes for free-form context about the contact, such as call outcomes, preferences, or follow-up reminders. # Remove a contact from the blacklist Source: https://developers.mihu.ai/api-reference/contacts/remove-a-contact-from-the-blacklist https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/{uuid}/unblacklist Removes the blacklist entry and restores the contact's status to Active. Idempotent — succeeds even if the contact is not currently blacklisted. # Remove a tag from a contact Source: https://developers.mihu.ai/api-reference/contacts/remove-a-tag-from-a-contact https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/{uuid}/remove-tag Removes a tag assignment from a contact without deleting the tag itself. Use this when a contact no longer belongs in a segment, label, or campaign targeting group. # Remove the contact from the pipeline Source: https://developers.mihu.ai/api-reference/contacts/remove-the-contact-from-the-pipeline https://app.mihu.ai/docs/api-docs.json post /api/v1/contacts/{uuid}/remove-stage Clears the contact's current pipeline stage. Use this when the contact should no longer appear in any stage until a new stage is assigned. The contact record and historical activity remain unchanged. # Update a contact Source: https://developers.mihu.ai/api-reference/contacts/update-a-contact https://app.mihu.ai/docs/api-docs.json put /api/v1/contacts/{uuid} Updates base contact fields and custom field values. Use this to correct contact identity, phone/email, timezone, language, preferred channel, or status. Only supplied fields are changed. **Custom fields:** any custom field key registered via POST /api/v1/contacts/fields can be sent as a top-level body property (string value). Sending an empty string or null clears that field for the contact. Use GET /api/v1/contacts/fields to discover available keys. Unknown keys return 422 with the offending key listed. In responses, every active custom field is returned as a top-level key — fields with no value appear as an empty string. # Update a contact note Source: https://developers.mihu.ai/api-reference/contacts/update-a-contact-note https://app.mihu.ai/docs/api-docs.json patch /api/v1/contacts/{uuid}/notes/{noteUuid} Updates the content of one note on the contact. Other notes are not changed. # Send a human reply to a conversation Source: https://developers.mihu.ai/api-reference/conversation-replies/send-a-human-reply-to-a-conversation https://app.mihu.ai/docs/api-docs.json post /api/v1/conversations/{uuid}/reply Sends the reply to the customer over the conversation's channel and records it as a human reply in the conversation history. Text replies work on WhatsApp, SMS, Email, Instagram, and Messenger. Files work everywhere except SMS — each file goes out as the channel's native message type (picture, playable audio, downloadable document, ...) on WhatsApp/Instagram/Messenger, and as real attachments of one email on Email. On WhatsApp the message becomes the first file's caption; Instagram and Messenger cannot caption media, so the message is delivered as a separate text after the files. Set take_over=true to also hand the conversation over to the replying member — the AI stops answering until the takeover is released. # Activity events of a conversation Source: https://developers.mihu.ai/api-reference/conversations/activity-events-of-a-conversation https://app.mihu.ai/docs/api-docs.json get /api/v1/conversations/{uuid}/events The AI's activity trail: intent/tool calls, knowledge-base retrievals, transfers, escalations, handovers, callbacks and approval requests. Interleave into the timeline using message_id/created_at; the same feed drives the Activity side panel. Live updates arrive as `conversation.event` on the conversation's realtime channel with the identical shape. # Approve a pending action — it runs NOW Source: https://developers.mihu.ai/api-reference/conversations/approve-a-pending-action-—-it-runs-now https://app.mihu.ai/docs/api-docs.json put /api/v1/conversations/{uuid}/events/{event}/approve Resolves a pending approval_request event: the queued tool/intent executes with its stored arguments, the event becomes approved, and an action_completed/action_failed event records the outcome. Idempotent-safe: a non-pending event returns 409. # Choose who answers: AI, Co-Pilot or Human Source: https://developers.mihu.ai/api-reference/conversations/choose-who-answers:-ai-co-pilot-or-human https://app.mihu.ai/docs/api-docs.json put /api/v1/conversations/{uuid}/mode Decides who writes the next reply on this one conversation. - **ai** — the AI answers by itself, no operator involved. - **copilot** — the AI stops answering and instead writes drafts the operator reviews and sends (`POST /conversations/{uuid}/drafts`). - **human** — the AI stops answering and writes nothing; the operator types the reply. **When to use it.** When an operator takes a conversation off the AI — a complaint, a negotiation, anything the AI should not be handling alone — and again when they hand it back. Sending `ai` returns the thread to automatic answering. **Why it is stored server-side.** The next operator to open the conversation sees the same mode, on any device: the state belongs to the conversation, not to one browser tab. **Relationship to take_over.** `copilot` and `human` both set `take_over` to true — the flag every channel checks before letting the AI reply — and `ai` clears it. Both fields are returned on the conversation object. **Starting value.** A new conversation follows the mode of its queue's channel assignment (`autopilot` / `copilot` / `human_first`). This endpoint is the per-conversation override; it does not change the queue. **Who can call it.** A workspace API token, or a per-user JWT holding `loop.conversations.mode`. JWTs only reach conversations in their active queues (404 otherwise). A JWT is attributed to its own user; a workspace token carries no identity, so pass `user_email` to record who switched the mode. # Conversation counts per label Source: https://developers.mihu.ai/api-reference/conversations/conversation-counts-per-label https://app.mihu.ai/docs/api-docs.json get /api/v1/conversations/label-counts One call for the inbox tab badges: every catalog label with its conversation count. Unlabeled conversations are counted under the label named 'Open'. Optional filters: queue_uuid (a specific queue — JWT callers must be a member of it), status, channel. JWT callers without queue_uuid get counts over their active-queue conversations only. # Get conversation details Source: https://developers.mihu.ai/api-reference/conversations/get-conversation-details https://app.mihu.ai/docs/api-docs.json get /api/v1/conversations/{uuid} Returns one conversation with contact, channel, agent, sessions, message context, and voice-call metadata when available. Use this before retrieving messages or session history for the conversation. # Get paginated list of conversations Source: https://developers.mihu.ai/api-reference/conversations/get-paginated-list-of-conversations https://app.mihu.ai/docs/api-docs.json get /api/v1/conversations Returns paginated conversations across voice and text channels. Use filters to find conversations by contact, phone, agent, campaign, task, channel, status, or sort order. Voice conversations may include call, campaign, listing, and task identifiers. # Get paginated messages of a conversation Source: https://developers.mihu.ai/api-reference/conversations/get-paginated-messages-of-a-conversation https://app.mihu.ai/docs/api-docs.json get /api/v1/conversations/{uuid}/messages Returns paginated messages for one conversation, including AI, human, and contact-authored messages. Use this to display the conversation transcript, audit agent behavior, or retrieve message history before evaluating a conversation. # Hand a conversation to a specific operator Source: https://developers.mihu.ai/api-reference/conversations/hand-a-conversation-to-a-specific-operator https://app.mihu.ai/docs/api-docs.json put /api/v1/conversations/{uuid}/assign Names the team member who owns this conversation. The assignee comes back on the conversation object as `assigned_to`, so the inbox can show who is on it. **When to use it.** Escalating to a colleague, handing over at the end of a shift, or claiming a conversation so two operators do not answer the same contact at once. Send `user_email: null` to release it back to the queue. **What it does not do.** Assigning does not move the conversation to another queue, does not change who is allowed to see it, and does not stop the AI — use `PUT /conversations/{uuid}/mode` for that. It is an ownership marker, not a permission. **Identifying the member.** By email, the way members are addressed throughout this API. The address must belong to an existing member of the workspace; an unknown address answers 404 rather than creating anyone. **Who can call it.** A workspace API token, or a per-user JWT holding `loop.conversations.assign`. JWTs only reach conversations in their active queues (404 otherwise). # List a queue's conversations Source: https://developers.mihu.ai/api-reference/conversations/list-a-queues-conversations https://app.mihu.ai/docs/api-docs.json get /api/v1/conversations/by-queue/{uuid} Returns the conversations routed to one queue, newest first, in the same shape as GET /conversations. Accepts a workspace API token (any queue) or a per-user JWT — with a JWT the user must be a member of the queue (admins and the workspace owner may read any queue), otherwise 404. # Mark a conversation read for the acting member Source: https://developers.mihu.ai/api-reference/conversations/mark-a-conversation-read-for-the-acting-member https://app.mihu.ai/docs/api-docs.json post /api/v1/conversations/{uuid}/read Moves the member's read cursor to now, so the conversation's unread_count becomes 0 for them. Call it when the operator opens the room. Idempotent, needs no body, and is per member: it never changes what anyone else sees. Requires a member token — a workspace API token has no member to mark for. # Mark a conversation unread again for the acting member Source: https://developers.mihu.ai/api-reference/conversations/mark-a-conversation-unread-again-for-the-acting-member https://app.mihu.ai/docs/api-docs.json post /api/v1/conversations/{uuid}/unread Moves the member's read cursor backwards. With no body every inbound message counts as unread again — the 'I want to come back to this' action. With message_uuid the cursor lands just before that message, so THAT message and everything after it are unread (the 'mark unread from here' action on a bubble). Per member, and the twin of the notifications mark-unread endpoint. # Mark every visible conversation read for the acting member Source: https://developers.mihu.ai/api-reference/conversations/mark-every-visible-conversation-read-for-the-acting-member https://app.mihu.ai/docs/api-docs.json post /api/v1/conversations/read-all Clears the member's unread badges in one call — the inbox twin of the notifications mark-all-read action, and the way to dismiss the backlog that exists before anyone has opened a room. Narrow it with contact_uuid (one customer's rooms) or queue_uuid (one queue). Per member: nobody else's badges change. Requires a member token. # Messages and activity events as ONE interleaved timeline Source: https://developers.mihu.ai/api-reference/conversations/messages-and-activity-events-as-one-interleaved-timeline https://app.mihu.ai/docs/api-docs.json get /api/v1/conversations/{uuid}/timeline Pages over the conversation's messages (same pagination as /messages) and rides the activity events along in the right spots, so a client renders the whole thread from a single call. Each item carries kind: message | event. # Open or close a conversation Source: https://developers.mihu.ai/api-reference/conversations/open-or-close-a-conversation https://app.mihu.ai/docs/api-docs.json put /api/v1/conversations/{uuid}/status Moves a conversation between the two lifecycle states: **Active** (in the inbox, being worked) and **Closed** (finished). **When to use it.** When the operator is done with a thread, or to reopen one closed too early. Reopening on a new customer message does not depend on this call — the contact writing again puts the conversation back in front of the operator either way. **What it is not.** This is not the state chip in the conversation header (Open, Waiting on customer, Escalated, Resolved, …). Those are labels, set with `PUT /conversations/{uuid}/label`, and they describe *where the work stands*. Status only answers *is this thread still open at all* — a conversation can be Active and labelled Escalated at the same time. **Who can call it.** A workspace API token, or a per-user JWT holding `loop.conversations.status`. A JWT only reaches conversations routed to one of its active queues; anything else answers 404 rather than 403, so a token cannot probe for conversations it may not see. # Reject a pending action — it never runs Source: https://developers.mihu.ai/api-reference/conversations/reject-a-pending-action-—-it-never-runs https://app.mihu.ai/docs/api-docs.json put /api/v1/conversations/{uuid}/events/{event}/reject # Route a conversation to another queue Source: https://developers.mihu.ai/api-reference/conversations/route-a-conversation-to-another-queue https://app.mihu.ai/docs/api-docs.json put /api/v1/conversations/{uuid}/transfer Moves the conversation to a different queue — the team that should carry it from here. **When to use it.** The operator picks a queue in the transfer dialog: wrong team, needs a specialist, escalating out of hours. The customer sees nothing; only who is responsible changes. **What it does not do.** It does not change the number the customer writes to, and it does not change the AI agent — that follows the number, not the queue. It also releases any individual assignee (`assigned_to`), because the conversation now belongs to a team rather than a person. **It sticks.** The queue a conversation arrived on is decided by its number, but a transfer overrides that for the rest of the conversation: the next inbound message will not pull it back. Only moving the number itself to another queue in the designer, or the conversation closing, resets that. **The note** is optional and, when given, is recorded in the thread as a system line so the receiving team can see why it arrived. **Who can call it.** A workspace API token, or a per-user JWT holding `loop.conversations.assign`. JWTs are limited to conversations of their active queues (404 otherwise), but may transfer INTO any queue — handing work to another team is the point. # Set a conversation's label Source: https://developers.mihu.ai/api-reference/conversations/set-a-conversations-label https://app.mihu.ai/docs/api-docs.json put /api/v1/conversations/{uuid}/label Sets the conversation's label — the single-check picker in the conversation header (Open, Waiting on customer, Follow-up, …). Labels come from the shared catalog (GET /api/v1/session-labels); send null to clear (the conversation then counts as the default label). Accepts a workspace API token, or a per-user JWT with the Label Conversations permission; JWTs are limited to conversations of their active queues (404 otherwise). # Assign an agent to an email address Source: https://developers.mihu.ai/api-reference/email-addresses/assign-an-agent-to-an-email-address https://app.mihu.ai/docs/api-docs.json post /api/v1/email/addresses/{uuid}/assign Routes inbound mail for this address to the given agent and lets the agent reply. Also makes the address selectable as the Email campaign channel. Reassigning moves it from any previous agent. Each agent may have only one email address — assigning to an agent that already has one returns 422. # Create an email address Source: https://developers.mihu.ai/api-reference/email-addresses/create-an-email-address https://app.mihu.ai/docs/api-docs.json post /api/v1/email/addresses type=subdomain creates an instant address on the shared sending domain (requires slug). type=custom_domain or custom_email connects your own address (requires address); custom_domain returns DNS records to add, custom_email sends a verification link. Limits: each agent may have only one email address, and the number of connected addresses is capped per plan (Freemium 0, Starter 1, Growth 3, Pro 5, Premium 10, Enterprise 20) — exceeding either returns 422. # Delete an email address Source: https://developers.mihu.ai/api-reference/email-addresses/delete-an-email-address https://app.mihu.ai/docs/api-docs.json delete /api/v1/email/addresses/{uuid} Removes the address so it no longer receives or sends mail. Existing conversations are kept; the address is freed up. # Disable an email address Source: https://developers.mihu.ai/api-reference/email-addresses/disable-an-email-address https://app.mihu.ai/docs/api-docs.json post /api/v1/email/addresses/{uuid}/disable Turns the address off — it stops receiving and sending mail until re-enabled. The address and its settings are kept. # Enable an email address Source: https://developers.mihu.ai/api-reference/email-addresses/enable-an-email-address https://app.mihu.ai/docs/api-docs.json post /api/v1/email/addresses/{uuid}/enable Re-activates a disabled address so it can send and receive mail again. # Get a single email address Source: https://developers.mihu.ai/api-reference/email-addresses/get-a-single-email-address https://app.mihu.ai/docs/api-docs.json get /api/v1/email/addresses/{uuid} Returns one email address by uuid, including its mode, status, verification state, from name, signature, verify method, and assigned agent. # Get DNS records for a connected domain Source: https://developers.mihu.ai/api-reference/email-addresses/get-dns-records-for-a-connected-domain https://app.mihu.ai/docs/api-docs.json get /api/v1/email/addresses/{uuid}/dns Returns the records to add at your DNS provider, each with the exact host and value to enter. Only available for connected-domain addresses. # List email addresses Source: https://developers.mihu.ai/api-reference/email-addresses/list-email-addresses https://app.mihu.ai/docs/api-docs.json get /api/v1/email/addresses Returns every email address on the tenant — shared (@partners.mail.mihu.ai) and connected-domain — with its mode, status, verification state, from name, signature, and assigned agent. # Unassign the agent from an email address Source: https://developers.mihu.ai/api-reference/email-addresses/unassign-the-agent-from-an-email-address https://app.mihu.ai/docs/api-docs.json post /api/v1/email/addresses/{uuid}/unassign Clears the handling agent. The address stays active and keeps receiving mail, but no agent replies until one is assigned again. # Update an email address Source: https://developers.mihu.ai/api-reference/email-addresses/update-an-email-address https://app.mihu.ai/docs/api-docs.json patch /api/v1/email/addresses/{uuid} Update the from name, signature, or auto-reply for an address. # Verify an email address Source: https://developers.mihu.ai/api-reference/email-addresses/verify-an-email-address https://app.mihu.ai/docs/api-docs.json post /api/v1/email/addresses/{uuid}/verify Checks whether the connected domain (or single address) is verified yet and returns the result. Once verified, the address starts sending from your own domain. Subdomain addresses are always verified. # Forward an email conversation to a third party Source: https://developers.mihu.ai/api-reference/email-messages/forward-an-email-conversation-to-a-third-party https://app.mihu.ai/docs/api-docs.json post /api/v1/email/conversations/{uuid}/forward Forwards the conversation to another recipient with an optional note. Uses the conversation's agent and address. # Reply within an email conversation Source: https://developers.mihu.ai/api-reference/email-messages/reply-within-an-email-conversation https://app.mihu.ai/docs/api-docs.json post /api/v1/email/conversations/{uuid}/reply Sends a reply in an existing email thread (channel 3), threaded correctly so it groups in the recipient's client. Uses the conversation's agent and address; the agent's signature is appended automatically. # Send a new email Source: https://developers.mihu.ai/api-reference/email-messages/send-a-new-email https://app.mihu.ai/docs/api-docs.json post /api/v1/email/messages Sends from one of your email addresses (identified by its uuid). The agent assigned to that address is used; the address must have an agent. # Create an override for an agent (clones current default) Source: https://developers.mihu.ai/api-reference/evaluate/create-an-override-for-an-agent-clones-current-default https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/evaluate/assign Creates agent-specific evaluate settings by copying the current global default. After this, the agent stops inheriting from the global default and can be updated with PUT /api/v1/agents/{uuid}/evaluate. Returns 409 if an override already exists; use PUT to update or POST /reassign to overwrite from default. # Force-overwrite the agent's override with a fresh copy of the current default Source: https://developers.mihu.ai/api-reference/evaluate/force-overwrite-the-agents-override-with-a-fresh-copy-of-the-current-default https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/evaluate/reassign Use when the global default has changed and you want this agent to pick up the new defaults while keeping its override row. Wipes all customizations on the agent's override. # List the 10 analyzer feature ids Source: https://developers.mihu.ai/api-reference/evaluate/list-the-10-analyzer-feature-ids https://app.mihu.ai/docs/api-docs.json get /api/v1/evaluate/features Static catalog of feature ids you can toggle or edit under `text.*` and `voice.*` in any update call. Useful for discovering supported feature ids dynamically. # Read effective evaluate settings for one agent Source: https://developers.mihu.ai/api-reference/evaluate/read-effective-evaluate-settings-for-one-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/evaluate If the agent has an override, returns it (source=agent). Otherwise returns the global default (source=default, agent_uuid=null). Always inspect the source field to know what you are looking at. # Read the global default evaluate settings Source: https://developers.mihu.ai/api-reference/evaluate/read-the-global-default-evaluate-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/evaluate/default Returns the workspace-wide default. Every agent without an override inherits from this. Response always has source=default and agent_uuid=null. # Remove the agent's override (revert to global default) Source: https://developers.mihu.ai/api-reference/evaluate/remove-the-agents-override-revert-to-global-default https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/evaluate Deletes the agent-specific evaluate settings so subsequent reads return the global default. Idempotent: a second call returns `data.deleted: false`. # Reset the agent's override to factory defaults Source: https://developers.mihu.ai/api-reference/evaluate/reset-the-agents-override-to-factory-defaults https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/evaluate/reset Like /default/reset but scoped to one agent. Keeps the override row in place; just rewrites every field to factory values. Use when you want this agent to ignore the current global default and start fresh. # Reset the global default to factory values Source: https://developers.mihu.ai/api-reference/evaluate/reset-the-global-default-to-factory-values https://app.mihu.ai/docs/api-docs.json post /api/v1/evaluate/default/reset Replaces every field on the global default with the built-in factory presets (workspace-language-aware). Destructive: any custom descriptions or prompts you set are lost. Does not touch per-agent overrides. # Update an agent's evaluate settings Source: https://developers.mihu.ai/api-reference/evaluate/update-an-agents-evaluate-settings https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/evaluate Partial update. If the agent has no override yet, one is auto-created from the current global default before applying changes (so you do not need to call /assign first). Only the keys you send are touched. # Update the global default evaluate settings Source: https://developers.mihu.ai/api-reference/evaluate/update-the-global-default-evaluate-settings https://app.mihu.ai/docs/api-docs.json put /api/v1/evaluate/default Partial update; any unsent key is left alone. Changes here cascade to every agent without its own override at next read time. Use sparingly. # Get a single evaluation Source: https://developers.mihu.ai/api-reference/evaluations/get-a-single-evaluation https://app.mihu.ai/docs/api-docs.json get /api/v1/evaluations/{uuid} Returns one session evaluation by UUID, including scores, labels, reasons, and related session/conversation/contact identifiers. Use this to inspect the AI analysis for a specific session. # Get paginated list of session evaluations Source: https://developers.mihu.ai/api-reference/evaluations/get-paginated-list-of-session-evaluations https://app.mihu.ai/docs/api-docs.json get /api/v1/evaluations Retrieves a paginated list of session evaluations with optional filtering by session/conversation/contact UUID and creation date range. # Reply within a Messenger conversation Source: https://developers.mihu.ai/api-reference/facebook-messenger/reply-within-a-messenger-conversation https://app.mihu.ai/docs/api-docs.json post /api/v1/facebook/conversations/{uuid}/reply Channel-scoped variant of the conversation reply: sends a human reply into a Facebook Messenger conversation. Same request and response as POST /api/v1/conversations/{uuid}/reply; the conversation must be a Messenger conversation (422 otherwise). Text and files are supported — Messenger cannot caption media, so the message is delivered as a separate text after the files. # Fetch dynamic dropdown options for a step's field Source: https://developers.mihu.ai/api-reference/flow-catalog/fetch-dynamic-dropdown-options-for-a-steps-field https://app.mihu.ai/docs/api-docs.json post /api/v1/flow/apps/{uid}/options Mirrors every 'Refresh' dropdown in the Studio Setup tab. Used to resolve human references like '#general' or 'Contacts module' into the actual identifiers the action config requires. **Always ask the user to pick from the response — never silently auto-select**, even when only one option exists. **Per-app supported `kind` values:** - Slack: `channels`, `private_channels`, `users` - Zoho CRM / Freshworks / Salesforce / Microsoft Dynamics: `modules`, `module_fields` (params.module), `records` (params.module) - Airtable: `bases`, `tables` (params.base_id), `fields` (params.base_id, table_id), `records` (params.base_id, table_id) - Apify: `actors`, `tasks` - Gmail: `labels`, `messages` - Google Calendar: `calendars`, `events` (params.calendar_id) - Google Sheet: `spreadsheets`, `worksheets` (params.spreadsheet_id), `columns` (params.spreadsheet_id, worksheet_title) - Notion: `databases`, `pages`, `database_properties` (params.database_id), `users` - Twilio: `phone_numbers` - Logic (builtin, no connection needed): `operators`, `joiners`, `delay_units` - Tables (builtin, no connection needed): `tables`, `columns` (params.table_id), `operators`, `operators_for_type` (params.type), `aggregates`, `order_directions` - Other builtin apps (Contacts, Campaigns, Tasks, Listings, Agents, Calls…): `agents`, `campaigns`, `listings`, `tags`, `stages`, `channels`, `whatsapp_templates`, `task_types`, `contact_statuses`, `languages`, `timezones` — no connection needed - Telegram: returns 422 — Bot API has no list endpoint # Flat list of every OAuth connection the tenant has, across all apps Source: https://developers.mihu.ai/api-reference/flow-catalog/flat-list-of-every-oauth-connection-the-tenant-has-across-all-apps https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/connections Each row carries the connection uuid + label and the inlined app it belongs to. Useful for an MCP server building a 'pick which account' prompt without iterating per-app first. # List all Studio integrations (apps) Source: https://developers.mihu.ai/api-reference/flow-catalog/list-all-studio-integrations-apps https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/apps The full set of integrations the Studio supports — both mihu builtins (Calls, Texts, Contacts, Logic, …) and connect apps (Slack, Zoho, Notion, Twilio, …). Filter by `category` to scope to one bucket, or by `search` for a substring match. Use `/flow/apps/supports/triggers` or `/supports/actions` to pre-filter to apps eligible at a given step position. # List apps eligible as a flow's action (step 2+) Source: https://developers.mihu.ai/api-reference/flow-catalog/list-apps-eligible-as-a-flows-action-step-2+ https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/apps/supports/actions Same shape as /flow/apps but pre-filtered to apps with at least one action. Use this when offering the user the action picker for any non-first step. # List apps eligible as a flow's trigger (step 1) Source: https://developers.mihu.ai/api-reference/flow-catalog/list-apps-eligible-as-a-flows-trigger-step-1 https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/apps/supports/triggers Same shape as /flow/apps but pre-filtered to apps with at least one trigger. Use this when offering the user the trigger picker for step 1 of a new flow. # List tenant's agents available for Agents-app actions Source: https://developers.mihu.ai/api-reference/flow-catalog/list-tenants-agents-available-for-agents-app-actions https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/agents Returns the agents the user can pick when configuring an Agents-app action (Make Call, Send WhatsApp, etc.). Limited to agents with status=ready. The MCP server uses this when the user says e.g. 'have my sales agent call the lead'. # List the actions an app exposes Source: https://developers.mihu.ai/api-reference/flow-catalog/list-the-actions-an-app-exposes https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/apps/{uid}/actions Each action has a `key` (used in step config: `action_key`) plus name, description, and config schema hints. # List the tenant's connections (OAuth accounts) for one app Source: https://developers.mihu.ai/api-reference/flow-catalog/list-the-tenants-connections-oauth-accounts-for-one-app https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/apps/{uid}/connections Returns each `app_connection` the tenant has set up for this app — typically zero or one for a fresh tenant, more if the user connected multiple workspaces. Builtin apps always return an empty array (they don't need OAuth). On an empty result for a connect app, the client should redirect the user to /oauth/{provider} to create one. # List the trigger events an app exposes Source: https://developers.mihu.ai/api-reference/flow-catalog/list-the-trigger-events-an-app-exposes https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/apps/{uid}/triggers Each trigger has a `key` (used in step config: `trigger_key`) plus name, description, and config schema hints. # Read a single app by its uid Source: https://developers.mihu.ai/api-reference/flow-catalog/read-a-single-app-by-its-uid https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/apps/{uid} # List run history of a flow Source: https://developers.mihu.ai/api-reference/flow-executions/list-run-history-of-a-flow https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/{uuid}/executions Paginated list of every time this flow fired on a real event. Each execution captures status, duration, and a preview of the trigger payload. Use GET /executions/{exec_uuid} to drill into per-step request/response/error. # Read one execution with per-step request/response/error Source: https://developers.mihu.ai/api-reference/flow-executions/read-one-execution-with-per-step-requestresponseerror https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/{uuid}/executions/{exec_uuid} Returns the full trigger payload that fired this run plus a `steps[]` array — for each step: status, duration, the resolved input, the handler's output, and any error message. Use this to debug a failed flow run. # Add a step to a flow (trigger as step 1, actions as step 2+) Source: https://developers.mihu.ai/api-reference/flow-steps/add-a-step-to-a-flow-trigger-as-step-1-actions-as-step-2+ https://app.mihu.ai/docs/api-docs.json post /api/v1/flow/{uuid}/steps Creates either a trigger (only one allowed, must be step 1) or an action. The server picks the position: by default appends to the end, but `insert_after_step_uuid` puts it mid-chain (downstream steps shift up + their `{{stepN.field}}` references are rewritten), and `parent_step_uuid` + `branch_key` makes it a child of an `if_condition` branch. **Validation rules:** - `kind=trigger` → flow must not already have a trigger; app must support_trigger=true. - `kind=action` → flow must already have a trigger; app must support_action=true. - `app.category=connect` → `app_connection_uuid` is required and must belong to this tenant + this app. - `app.category=builtin` → `app_connection_uuid` must be null. - Agents app actions → `agent_uuid` required. - Branch child → `parent_step_uuid` must point to an `if_condition` step. **Cannot edit a deployed flow** — returns 409 unless you `POST /undeploy` first. # Delete a step (and its branch children if any) Source: https://developers.mihu.ai/api-reference/flow-steps/delete-a-step-and-its-branch-children-if-any https://app.mihu.ai/docs/api-docs.json delete /api/v1/flow/{uuid}/steps/{step} Removes the step. Subsequent steps are renumbered down by 1. `{{stepN.field}}` references in remaining steps' configs are rewritten — references to the deleted step become `` so the UI/MCP can flag dangling refs. Cannot delete the trigger step (returns 409). Cannot edit a deployed flow. # Read one step Source: https://developers.mihu.ai/api-reference/flow-steps/read-one-step https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/{uuid}/steps/{step} # Test a step — kind-aware behavior (trigger samples vs action exec) Source: https://developers.mihu.ai/api-reference/flow-steps/test-a-step-—-kind-aware-behavior-trigger-samples-vs-action-exec https://app.mihu.ai/docs/api-docs.json post /api/v1/flow/{uuid}/steps/{step}/test **For trigger steps:** auto-fetches recent records from the trigger's source (e.g. recent calls for Calls/call_started) and uses the latest as the persisted sample. The chosen sample's `data` is what every downstream step's `{{stepN.field}}` resolves against. Pass `data: {...}` to skip the auto-fetch and use a manual payload. Pass `sample_uuid` to pick a specific record from `samples[]`. Returns 404 with `samples:[]` if the source has no matching records — the MCP should then prompt the user to either generate a real event or supply manual data. **For action steps:** resolves the step's `config` against upstream `last_test.data`, then either dry-runs (validates config without external calls) or executes live. Default behavior uses a safe-list — read-only actions execute live, destructive actions (post message, create record) dry-run. Pass `live: true` to force real execution; pass `dry_run: true` to force validation-only. Call actions (end_call, transfer_call) always dry-run since they need a live call's control_url. **Side effect on success when `persist=true`:** step status flips from `draft` → `active` (this is what unlocks `POST /deploy`). # Update any subset of a step's fields Source: https://developers.mihu.ai/api-reference/flow-steps/update-any-subset-of-a-steps-fields https://app.mihu.ai/docs/api-docs.json patch /api/v1/flow/{uuid}/steps/{step} **Order of operations matters.** Switching `app_uid` clears trigger/action/config/connection (forces re-selection — same as the Studio UI). After that, `trigger_key`/`action_key`/`agent_uuid`/`app_connection_uuid`/`config` apply in order. Cannot edit a deployed flow — returns 409 unless you `POST /undeploy` first. # Get a trigger's config field schema (what to ask) Source: https://developers.mihu.ai/api-reference/flow/get-a-triggers-config-field-schema-what-to-ask https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/apps/{uid}/triggers/{trigger_key}/config-schema Like the action config-schema, but for a trigger. Returns the fields a trigger needs (e.g. Tables record_created needs a `table_uuid`; Zoho new_or_update_module_entry needs a `module`). Triggers with no config (e.g. Webhooks catch_webhook, Zoho fixed-module triggers) return an empty `fields` array with a `note`. select fields carry `options_kind`/`options_params` resolved via POST /flow/apps/{uid}/options. # Get an action's config field schema (what to ask) Source: https://developers.mihu.ai/api-reference/flow/get-an-actions-config-field-schema-what-to-ask https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/apps/{uid}/actions/{action_key}/config-schema Returns the fields an action's config needs — which are required, their type, and where to resolve options — so a client/MCP can ask the right questions instead of hard-coding each action. select/multi_select fields carry an `options_kind` (resolve via POST /flow/apps/{uid}/options with any `options_params`); `options_kind=intent_parameters` is resolved from the intent's parameters. `requires_connection` indicates whether an `app_connection_uuid` is needed. Use `?context=intent` (default) or `?context=scenario`. # Create an empty flow (draft) Source: https://developers.mihu.ai/api-reference/flows/create-an-empty-flow-draft https://app.mihu.ai/docs/api-docs.json post /api/v1/flow Creates a flow with no steps. Both `name` and `description` are optional — when name is omitted the server assigns 'Flow {id}'. Add a trigger step next via POST /flow/{uuid}/steps with kind=trigger. # Delete a flow Source: https://developers.mihu.ai/api-reference/flows/delete-a-flow https://app.mihu.ai/docs/api-docs.json delete /api/v1/flow/{uuid} Soft-delete (per project convention). Pending executions are not auto-cancelled — undeploy first if you want clean cancellation. The flow is removed from `GET /flows` immediately and a fresh GET on its uuid returns 404. # Deploy a flow — flips it from draft to live Source: https://developers.mihu.ai/api-reference/flows/deploy-a-flow-—-flips-it-from-draft-to-live https://app.mihu.ai/docs/api-docs.json post /api/v1/flow/{uuid}/deploy Validates the flow has a trigger, every step is configured (app + trigger/action set), every connect-app step has a valid connection, every step is `active` (set by a successful test), and no `` references remain. On success the flow becomes eligible to fire on real events. Returns 422 with an `errors[]` list of every blocker on failure. # List flows (paginated, filterable) Source: https://developers.mihu.ai/api-reference/flows/list-flows-paginated-filterable https://app.mihu.ai/docs/api-docs.json get /api/v1/flows Returns the tenant's flows with each one's compact app/agent/step counts and last-updated timestamps. Use the filters to narrow by status, search term, or change the sort. # Read a flow with its full ordered step list Source: https://developers.mihu.ai/api-reference/flows/read-a-flow-with-its-full-ordered-step-list https://app.mihu.ai/docs/api-docs.json get /api/v1/flow/{uuid} Steps are returned flat — branch children of an `if_condition` appear in the array with `parent_step_uuid` and `branch_key` populated. Each step's `last_test.data` is what downstream steps' `{{stepN.field}}` references resolve against. # Undeploy — flip a deployed flow back to draft Source: https://developers.mihu.ai/api-reference/flows/undeploy-—-flip-a-deployed-flow-back-to-draft https://app.mihu.ai/docs/api-docs.json post /api/v1/flow/{uuid}/undeploy Stops the flow from firing on real events and unlocks it for editing (PATCH/POST/DELETE on its steps). Idempotent — calling on a draft flow is a no-op. # Update flow name or description Source: https://developers.mihu.ai/api-reference/flows/update-flow-name-or-description https://app.mihu.ai/docs/api-docs.json patch /api/v1/flow/{uuid} Only `name` and `description` are mutable here. To change the structure (steps), use the step endpoints. Allowed even on a deployed flow (no undeploy required) since name/description don't affect runtime. # Answer a ringing Human First inbound call (first member wins) and get the room token Source: https://developers.mihu.ai/api-reference/human-calls/answer-a-ringing-human-first-inbound-call-first-member-wins-and-get-the-room-token https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/answer # Dial a number as a human operator Source: https://developers.mihu.ai/api-reference/human-calls/dial-a-number-as-a-human-operator https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/human # End the call from the human side (no AI goodbye) Source: https://developers.mihu.ai/api-reference/human-calls/end-the-call-from-the-human-side-no-ai-goodbye https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/end # Hand the call back to the AI Source: https://developers.mihu.ai/api-reference/human-calls/hand-the-call-back-to-the-ai https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/release # Mint a Mihu Stream token to enter the live call's room (barge) Source: https://developers.mihu.ai/api-reference/human-calls/mint-a-mihu-stream-token-to-enter-the-live-calls-room-barge https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/join # Silence the AI and hand the customer to the operator Source: https://developers.mihu.ai/api-reference/human-calls/silence-the-ai-and-hand-the-customer-to-the-operator https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/takeover # Silence the AI but keep it listening; the operator talks and both sides are transcribed Source: https://developers.mihu.ai/api-reference/human-calls/silence-the-ai-but-keep-it-listening;-the-operator-talks-and-both-sides-are-transcribed https://app.mihu.ai/docs/api-docs.json post /api/v1/calls/action/{uuid}/copilot # Reply within an Instagram conversation Source: https://developers.mihu.ai/api-reference/instagram/reply-within-an-instagram-conversation https://app.mihu.ai/docs/api-docs.json post /api/v1/instagram/conversations/{uuid}/reply Channel-scoped variant of the conversation reply: sends a human reply into an Instagram DM conversation. Same request and response as POST /api/v1/conversations/{uuid}/reply; the conversation must be an Instagram conversation (422 otherwise). Text and files are supported — Instagram cannot caption media, so the message is delivered as a separate text after the files. # Introduction Source: https://developers.mihu.ai/api-reference/introduction Complete API reference for the Mihu platform ## Welcome The Mihu API enables you to build AI-powered voice and text conversation experiences. This section contains automatically generated documentation for all available endpoints. There are two ways to access API documentation: 1. **Auto-generated Reference** - Browse the endpoints in the sidebar (generated from our OpenAPI specification) 2. **Interactive Guides** - Check our [Quickstart Guide](/quickstart) for step-by-step examples View the complete OpenAPI specification file ## Base URL All API requests should be made to your workspace-specific URL: ``` https://{subdomain}.mihu.ai/api/v1 ``` Replace `{subdomain}` with your workspace identifier. For example, if your workspace URL is `https://abc.mihu.ai`, then your API base URL is `https://abc.mihu.ai/api/v1`. ## Authentication All API endpoints require authentication using Bearer tokens. ### How to Get Your API Token Navigate to your Mihu workspace at `https://your-subdomain.mihu.ai` Click on your profile icon (top right) and select **"Developer"** In the Developer section, click **"Create New API Token"** or **"Generate Token"** Copy the generated token immediately. You won't be able to see it again after closing the dialog. Store it securely in environment variables or a secrets manager. Never share your API token or commit it to version control. Treat it like a password. ### Using Your Token Include your token in the `Authorization` header of every request: ```bash cURL Example theme={null} curl -X GET https://your-subdomain.mihu.ai/api/v1/calls \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```javascript JavaScript Example theme={null} const response = await fetch('https://your-subdomain.mihu.ai/api/v1/calls', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` ```python Python Example theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://your-subdomain.mihu.ai/api/v1/calls", headers=headers ) ``` For detailed authentication setup, see our [Authentication Guide](/authentication). ## API Capabilities The Mihu API provides the following functionality: Initiate AI-powered outbound calls and manage call status Create and manage multi-channel communication campaigns Manage contact information and custom fields Send template-based WhatsApp messages Access conversation transcripts and analytics Receive real-time event notifications ## Getting Started Make your first API call in minutes Set up your API token Configure real-time notifications Handle errors gracefully ## Response Format All API responses follow a consistent JSON structure: **Success Response:** ```json theme={null} { "success": true, "message": "Operation completed successfully", "data": { // Response data here } } ``` **Error Response:** ```json theme={null} { "success": false, "message": "Error description", "error": { "code": "ERROR_CODE", "details": "Additional error information" } } ``` ## Rate Limits * **API Requests:** 1000 requests per minute * **Concurrent Calls:** 50 simultaneous calls * **Webhook Deliveries:** 100 events per second See the [Monitoring Guide](/monitoring) for tracking your usage. ## Support Need help? We're here for you: * **Documentation:** Browse our [comprehensive guides](/introduction) * **API Reference:** Explore endpoints in the sidebar * **Email Support:** [support@mihu.ai](mailto:support@mihu.ai) * **Monitoring:** Track requests in your [dashboard](https://app.mihu.ai) ## Explore the API Browse the endpoints in the sidebar to see detailed documentation for each API call, including: * Request parameters and body schemas * Response formats * Authentication requirements * Code examples * Error codes # List supported languages Source: https://developers.mihu.ai/api-reference/language/list-supported-languages https://app.mihu.ai/docs/api-docs.json get /api/v1/language Returns the supported language catalog for agent configuration. Use the returned codes for agent.language and settings.voice.voice_profile.language when creating or updating agents, and use the display names for user-facing language selection. # Add contacts to an existing listing Source: https://developers.mihu.ai/api-reference/listings/add-contacts-to-an-existing-listing https://app.mihu.ai/docs/api-docs.json post /api/v1/listings/{uuid}/contacts Adds one or more contacts to the listing's pool. Existing contacts are matched by phone number first, then email; matched contacts are updated, and new contacts are created. Additional fields are stored as custom contact fields. If the listing is running, tasks are created for newly added eligible contacts. # Create a new listing with rule and bulk contacts Source: https://developers.mihu.ai/api-reference/listings/create-a-new-listing-with-rule-and-bulk-contacts https://app.mihu.ai/docs/api-docs.json post /api/v1/listings Creates a listing workflow in one request: campaign, contact pool, optional rule, and initial contacts. Use this when you want to start from a list of contacts instead of manually creating a campaign, pool, and pool memberships separately. Contacts are matched by phone number first, then email; new contacts are created when no match exists. # Delete a listing Source: https://developers.mihu.ai/api-reference/listings/delete-a-listing https://app.mihu.ai/docs/api-docs.json delete /api/v1/listings/{uuid} Deletes the listing campaign, detaches its pool and rule, and cancels pending campaign tasks. Use this when the listing workflow should be removed rather than paused. Contacts themselves are not deleted. # Get all listings (campaigns with pools) Source: https://developers.mihu.ai/api-reference/listings/get-all-listings-campaigns-with-pools https://app.mihu.ai/docs/api-docs.json get /api/v1/listings Returns campaigns that have contact pools and are managed as listings. Use this endpoint to monitor outreach lists, filter by status, search by name or description, and paginate through listing campaigns. # Get listing details with contacts Source: https://developers.mihu.ai/api-reference/listings/get-listing-details-with-contacts https://app.mihu.ai/docs/api-docs.json get /api/v1/listings/{uuid} Returns one listing with its campaign settings, agent/channel binding, rule, attached pool, and contacts. Use this endpoint before starting, stopping, deleting, or adding contacts to a listing. # Remove a contact from a listing and cancel their tasks Source: https://developers.mihu.ai/api-reference/listings/remove-a-contact-from-a-listing-and-cancel-their-tasks https://app.mihu.ai/docs/api-docs.json delete /api/v1/listings/{uuid}/contacts/{contact_uuid} Removes one contact from the listing's pool and cancels that contact's pending tasks for the listing campaign. Use this when a contact should no longer receive outreach from this listing. The contact record itself is not deleted. # Start/resume a listing campaign Source: https://developers.mihu.ai/api-reference/listings/startresume-a-listing-campaign https://app.mihu.ai/docs/api-docs.json post /api/v1/listings/{uuid}/run Starts or resumes a listing by moving it to In Process and creating tasks for eligible contacts. Use this after the listing has contacts, an agent/channel, and a rule. Returns a conflict if the listing is already running, still importing, completed, or in a status that cannot start. # Stop/pause a running listing campaign Source: https://developers.mihu.ai/api-reference/listings/stoppause-a-running-listing-campaign https://app.mihu.ai/docs/api-docs.json post /api/v1/listings/{uuid}/stop Pauses a running listing and cancels pending tasks for that campaign. Use this when you need to stop outreach without deleting the listing, contacts, pool, or rule. Only listings currently In Process can be stopped. # Get full detail for a single action execution Source: https://developers.mihu.ai/api-reference/logs/get-full-detail-for-a-single-action-execution https://app.mihu.ai/docs/api-docs.json get /api/v1/logs/actions/{type}/{uuid} Returns the full request/response payload, related agent and contact, and per-type extras (intent: the call it happened in, the related conversation, and any webhook delivery; task: the campaign and channel context; workflow: per-step execution log). The combination `{type}/{uuid}` uniquely identifies any execution row. # Get full detail for a single API request log Source: https://developers.mihu.ai/api-reference/logs/get-full-detail-for-a-single-api-request-log https://app.mihu.ai/docs/api-docs.json get /api/v1/logs/api/{uuid} Returns the full request and response bodies for one logged API request. Tokens, passwords and other secrets in the bodies and the calling token are masked. # Get full detail for a single webhook delivery Source: https://developers.mihu.ai/api-reference/logs/get-full-detail-for-a-single-webhook-delivery https://app.mihu.ai/docs/api-docs.json get /api/v1/logs/webhooks/{uuid} Returns the full payload, request/response headers and response body for one webhook delivery. Signatures, authorization headers, cookies and any inline tokens/passwords are masked. # List action executions across tasks, workflows, and intents Source: https://developers.mihu.ai/api-reference/logs/list-action-executions-across-tasks-workflows-and-intents https://app.mihu.ai/docs/api-docs.json get /api/v1/logs/actions Returns a chronologically merged stream of three kinds of agent activity: (1) `task` — a queued action against a contact such as an outbound call attempt or message send, typically spawned by a campaign; (2) `workflow` — a multi-step automation triggered by an event (each row is one full run); (3) `intent` — an action the AI took during a call. Each item carries a `type` discriminator and a stable `uuid` you can use as a row key and to drill into the detail endpoint. Useful for audit, debugging, and building external monitoring on top of agent activity. # List inbound API request logs Source: https://developers.mihu.ai/api-reference/logs/list-inbound-api-request-logs https://app.mihu.ai/docs/api-docs.json get /api/v1/logs/api Returns a paginated feed of requests made against this tenant's API, newest first. Each row records the HTTP method, path, status code, and the calling token (masked). Secrets in request/response bodies are masked; bodies themselves are only returned by the detail endpoint. # List outbound webhook delivery logs Source: https://developers.mihu.ai/api-reference/logs/list-outbound-webhook-delivery-logs https://app.mihu.ai/docs/api-docs.json get /api/v1/logs/webhooks Returns a paginated feed of webhook deliveries this tenant sent to registered endpoints, newest first. Each row records the event, destination, HTTP status, and execution time. Payloads, headers and bodies are only returned by the detail endpoint, with secrets masked. # Get a media file by uuid Source: https://developers.mihu.ai/api-reference/medias/get-a-media-file-by-uuid https://app.mihu.ai/docs/api-docs.json get /api/v1/medias/{uuid} Returns one media library entry by `uuid`, including its public `url` (use that URL wherever a media/file URL is expected) and, when linked, the message it belongs to. # List media files Source: https://developers.mihu.ai/api-reference/medias/list-media-files https://app.mihu.ai/docs/api-docs.json get /api/v1/medias Returns the workspace media library, newest first, paginated. Use this to find an already-uploaded file and reuse its `url` instead of uploading again: search by name or original file name (`search`), filter by media type (`type`), or narrow to media linked to one message (`message_uuid`). Every item in `data` carries the public `url` ready to use. # Upload a media file Source: https://developers.mihu.ai/api-reference/medias/upload-a-media-file https://app.mihu.ai/docs/api-docs.json post /api/v1/medias Uploads one file into the workspace media library and returns its public URL. Send the request as multipart/form-data with the raw file in the `file` field (max 50 MB) — do NOT send JSON, a URL, or base64 content. On success (201) read `data.url` from the response and use it directly wherever a media/file URL is expected — e.g. WhatsApp template media (header image, video, document) or a media message attachment. Keep `data.uuid` if you need to look the file up again later. Executable file types are rejected with 422. Optionally link the media to an existing message via `message_uuid`. # Bulk-toggle contact field flags for an agent Source: https://developers.mihu.ai/api-reference/memorize/bulk-toggle-contact-field-flags-for-an-agent https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/memorize/bulk Same body shape as the default bulk endpoint. If the agent does not yet have its own memorize settings, they are created automatically from the global default on the first edit. # Bulk-toggle contact field flags on the default settings Source: https://developers.mihu.ai/api-reference/memorize/bulk-toggle-contact-field-flags-on-the-default-settings https://app.mihu.ai/docs/api-docs.json patch /api/v1/memorize/default/bulk Send a list of contact-field toggles. Each item must include `field_id` plus any subset of the 5 allowed flags. Only the keys you send are touched — other fields and other flags stay as they were. # Catalog merged with the agent's toggles (or default if no override) Source: https://developers.mihu.ai/api-reference/memorize/catalog-merged-with-the-agents-toggles-or-default-if-no-override https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/memorize/contact-fields Returns all available contact fields with the agent's effective memorize toggles. If the agent has no override, the response is merged with the global default and source is returned as default. # Catalog merged with the global default's toggle state Source: https://developers.mihu.ai/api-reference/memorize/catalog-merged-with-the-global-defaults-toggle-state https://app.mihu.ai/docs/api-docs.json get /api/v1/memorize/default/contact-fields Returns all available contact fields with the global default memorize toggles applied. Use this to see which fields agents inherit for memory extraction when they do not have agent-specific memorize settings. # Create custom memorize settings for an agent, copied from the global default Source: https://developers.mihu.ai/api-reference/memorize/create-custom-memorize-settings-for-an-agent-copied-from-the-global-default https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/memorize/assign Creates an agent-specific memorize override by copying the current global default. Use this before customizing one agent's memory behavior independently. Returns 409 if the agent already has custom memorize settings. # Get an agent's memorize settings (falls back to default) Source: https://developers.mihu.ai/api-reference/memorize/get-an-agents-memorize-settings-falls-back-to-default https://app.mihu.ai/docs/api-docs.json get /api/v1/agents/{uuid}/memorize Returns the agent's effective memorize settings. If the agent has a custom override, source is agent; otherwise the response returns the global default with source default. # Get the global default memorize settings Source: https://developers.mihu.ai/api-reference/memorize/get-the-global-default-memorize-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/memorize/default Returns the workspace-wide default memorize settings. Agents without their own override inherit these settings for contact field memory, conversation memory, channel behavior, and summary cadence. # List contact fields available for memorize settings Source: https://developers.mihu.ai/api-reference/memorize/list-contact-fields-available-for-memorize-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/memorize/contact-fields Returns every contact field that can be toggled in memorize settings: built-in base fields plus all active custom fields. # Remove an agent's specific memorize settings (reverts to default) Source: https://developers.mihu.ai/api-reference/memorize/remove-an-agents-specific-memorize-settings-reverts-to-default https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/memorize Deletes the agent-specific memorize override. After deletion, the agent inherits the global default memorize settings again. The operation is idempotent. # Replace the agent's memorize settings with a fresh copy of the global default Source: https://developers.mihu.ai/api-reference/memorize/replace-the-agents-memorize-settings-with-a-fresh-copy-of-the-global-default https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/memorize/reassign Overwrites the agent's memorize settings with a new copy of the current global default. Use this when the default changed and the agent should discard its custom memory configuration. # Reset an agent's memorize settings to factory defaults Source: https://developers.mihu.ai/api-reference/memorize/reset-an-agents-memorize-settings-to-factory-defaults https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/memorize/reset Resets the agent's memorize settings to factory defaults. If the agent has no override, one is created before resetting. Use this when a single agent should return to baseline memory behavior without changing the global default. # Reset the global default memorize settings to factory defaults Source: https://developers.mihu.ai/api-reference/memorize/reset-the-global-default-memorize-settings-to-factory-defaults https://app.mihu.ai/docs/api-docs.json post /api/v1/memorize/default/reset Resets the global default memorize settings to factory defaults. Use this when default memory behavior should return to the built-in baseline. Agent-specific overrides are not changed. # Update an agent's memorize settings (creates them from the global default if the agent has none yet) Source: https://developers.mihu.ai/api-reference/memorize/update-an-agents-memorize-settings-creates-them-from-the-global-default-if-the-agent-has-none-yet https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/memorize Updates one agent's memorize settings. If the agent does not already have custom settings, they are created from the global default first, then the supplied changes are applied. # Update the global default memorize settings Source: https://developers.mihu.ai/api-reference/memorize/update-the-global-default-memorize-settings https://app.mihu.ai/docs/api-docs.json put /api/v1/memorize/default Updates the workspace-wide default memorize settings. Use this to control what future and non-overridden agents remember from conversations. Only supplied settings are changed. # Allocate a SIP connector server Source: https://developers.mihu.ai/api-reference/pbx-extension-connectors/allocate-a-sip-connector-server https://app.mihu.ai/docs/api-docs.json post /api/v1/pbx_extension_connectors/sip_server Picks a random active server from the configured pool and allocates its IP to your account. Idempotent: if a server is already assigned the existing one is returned. # Create a PBX extension connector Source: https://developers.mihu.ai/api-reference/pbx-extension-connectors/create-a-pbx-extension-connector https://app.mihu.ai/docs/api-docs.json post /api/v1/pbx_extension_connectors Registers a PBX extension to an AI voice agent. This endpoint configures the PBX end only — it does not provision a SIP trunk. Use it when you want to connect a number purchased through this platform to your existing PBX extension; if you already have a SIP trunk from a provider, use the SIP trunk endpoints directly instead. # Delete a PBX extension connector Source: https://developers.mihu.ai/api-reference/pbx-extension-connectors/delete-a-pbx-extension-connector https://app.mihu.ai/docs/api-docs.json delete /api/v1/pbx_extension_connectors/{uuid} Deletes a PBX extension connector and deregisters its SIP customer entry. Use this when an extension should no longer route calls through the connected PBX. The linked agent and phone number are not deleted. # Get a single PBX extension connector Source: https://developers.mihu.ai/api-reference/pbx-extension-connectors/get-a-single-pbx-extension-connector https://app.mihu.ai/docs/api-docs.json get /api/v1/pbx_extension_connectors/{uuid} Returns one PBX extension connector by UUID, including the linked agent, phone number, extension payload, and connector status. Use this before updating external PBX configuration or deleting the connector. # Get the SIP connector server assigned to your account Source: https://developers.mihu.ai/api-reference/pbx-extension-connectors/get-the-sip-connector-server-assigned-to-your-account https://app.mihu.ai/docs/api-docs.json get /api/v1/pbx_extension_connectors/sip_server Returns the SIP connector server currently allocated to your account. You need one allocated before any PBX extension connector can be created — connectors are pushed to that server. If `assigned` is `false` (no server has ever been allocated for you), call `POST /api/v1/pbx_extension_connectors/sip_server` first to have one assigned, then create your connectors. # List PBX extension connectors Source: https://developers.mihu.ai/api-reference/pbx-extension-connectors/list-pbx-extension-connectors https://app.mihu.ai/docs/api-docs.json get /api/v1/pbx_extension_connectors Returns paginated PBX extension connectors. Use this to audit extension routing from agents and phone numbers to the allocated SIP connector server, with optional filters for agent, phone number, or status. # Release the allocated SIP connector server Source: https://developers.mihu.ai/api-reference/pbx-extension-connectors/release-the-allocated-sip-connector-server https://app.mihu.ai/docs/api-docs.json delete /api/v1/pbx_extension_connectors/sip_server Unassigns the workspace SIP connector server after all PBX extension connectors have been deleted. Use this when PBX extension routing is no longer needed. Returns 409 if any connector still depends on the server. # Assign a number to an agent Source: https://developers.mihu.ai/api-reference/phone-numbers/assign-a-number-to-an-agent https://app.mihu.ai/docs/api-docs.json put /api/v1/phone-numbers/{uuid}/bindings/{channel} Connects this number to one of your agents on a specific channel (call, SMS, or WhatsApp). The agent must already have that channel configured. For SMS, this also provisions the messaging profile and inbound webhook and fails if that setup cannot be completed. A number can only serve one agent per channel — disconnect the existing assignment first if you're switching. # Assign or reassign an external trunk to an agent Source: https://developers.mihu.ai/api-reference/phone-numbers/assign-or-reassign-an-external-trunk-to-an-agent https://app.mihu.ai/docs/api-docs.json put /api/v1/phone-numbers/trunks/assign Reassigns an existing external trunk (created via POST /trunks) to a different agent on the same channel. The phone number, SIP credentials, and channel settings are preserved — only the agent on the binding changes. Returns the same `channels` payload as GET /phone-numbers/channels. # Buy a phone number Source: https://developers.mihu.ai/api-reference/phone-numbers/buy-a-phone-number https://app.mihu.ai/docs/api-docs.json post /api/v1/phone-numbers Purchases a number returned by the search endpoint. If the country/type requires compliance, include an address (when needed) and a list of requirement values — text answers and document IDs from /api/v1/phone-numbers/documents. # Channels for a phone number (look up by number) Source: https://developers.mihu.ai/api-reference/phone-numbers/channels-for-a-phone-number-look-up-by-number https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/channels Same as the by-UUID version, but you only need the phone number itself. Works for both owned numbers and external ones (numbers your agents use but didn't buy through us). The leading + is optional. # Channels for one phone number Source: https://developers.mihu.ai/api-reference/phone-numbers/channels-for-one-phone-number https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/{uuid}/channels A trimmed-down view focused on what each channel (call, SMS, WhatsApp, inbound) can do for this number: what it supports, whether it's enabled, and which agent it's connected to. # Compliance requirements for a country Source: https://developers.mihu.ai/api-reference/phone-numbers/compliance-requirements-for-a-country https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/search/requirements Some countries require documents (proof of ID, business license, local address) before a number can be activated. Use this to find out exactly what's needed for the country and number type you're targeting, so you can prepare them before purchase. # Delete an external trunk Source: https://developers.mihu.ai/api-reference/phone-numbers/delete-an-external-trunk https://app.mihu.ai/docs/api-docs.json delete /api/v1/phone-numbers/trunks Removes an external trunk binding identified by `phone_number` + `channel`. The phone number itself is not in your purchased inventory, so nothing is billed or released externally — this only removes the agent binding. If the resulting AgentApp has no remaining bindings, it (and its connection) are cleaned up too. # Get one phone number Source: https://developers.mihu.ai/api-reference/phone-numbers/get-one-phone-number https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/{uuid} Returns full details for a single number — capabilities, channel settings, billing, compliance status, and which agents are using it on each channel. # List external trunks (BYO numbers) Source: https://developers.mihu.ai/api-reference/phone-numbers/list-external-trunks-byo-numbers https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/trunks Lists every external trunk you've registered — phone numbers you own elsewhere that are bound to your agents but not in your purchased inventory. All rows come back with `source: external`. Filter by channel, agent, or number substring. # List your phone numbers Source: https://developers.mihu.ai/api-reference/phone-numbers/list-your-phone-numbers https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers Returns every phone number connected to your workspace — both numbers you've purchased and external trunks (BYO numbers your agents use that weren't bought through us). Each row carries `source: purchased|external`. Pass `only_include=purchased` for purchased-only, or `only_include=external` for trunks-only. # Outbound call rates Source: https://developers.mihu.ai/api-reference/phone-numbers/outbound-call-rates https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/rates Per-minute pricing for outbound calls, broken down by destination country and prefix. Useful for estimating campaign costs before you launch. These rates are charged on top of the plan's voice usage rate, and only for calls that go through our telephony — connect your own carrier or SIP trunk and that provider bills you instead, in which case nothing here applies. # Phone number summary Source: https://developers.mihu.ai/api-reference/phone-numbers/phone-number-summary https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/stats A quick snapshot for dashboards: how many numbers you have, how many need attention (e.g. compliance pending), your total monthly spend, and breakdowns by country and number type. # Phone numbers for one agent Source: https://developers.mihu.ai/api-reference/phone-numbers/phone-numbers-for-one-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/by-agent/{uuid} Returns the phone numbers an agent serves on, with the channels in use on each number. Same shape as one entry from /by-agent. # Phone numbers grouped by agent Source: https://developers.mihu.ai/api-reference/phone-numbers/phone-numbers-grouped-by-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/by-agent Same data as /used-channels-and-accounts, but pivoted: one row per agent, listing the phone numbers they answer on and which channels they use on each. Useful for building agent-centric views. # Register an external SIP trunk / BYO number Source: https://developers.mihu.ai/api-reference/phone-numbers/register-an-external-sip-trunk-byo-number https://app.mihu.ai/docs/api-docs.json post /api/v1/phone-numbers/trunks Connects a phone number you already own elsewhere (your own SIP trunk, an existing WhatsApp Business line, a number on another carrier) to one of your agents on a specific channel. The number is registered as `source: external` — it will not be billed, and inventory operations like /release do not apply. SIP credentials, when provided, are stored encrypted. # Release a phone number Source: https://developers.mihu.ai/api-reference/phone-numbers/release-a-phone-number https://app.mihu.ai/docs/api-docs.json delete /api/v1/phone-numbers/{uuid} Removes a number from your active inventory. If any agent is still using the number on call, SMS, or WhatsApp, the request is rejected — disconnect those agents first. # Release a phone number Source: https://developers.mihu.ai/api-reference/phone-numbers/release-a-phone-number-1 https://app.mihu.ai/docs/api-docs.json post /api/v1/phone-numbers/{uuid}/release Action-style alias for DELETE /api/v1/phone-numbers/{uuid}. Soft-deletes a number after checking that it has no active agent bindings. # Remove a number from an agent Source: https://developers.mihu.ai/api-reference/phone-numbers/remove-a-number-from-an-agent https://app.mihu.ai/docs/api-docs.json delete /api/v1/phone-numbers/{uuid}/bindings/{channel} Disconnects this number from whichever agent currently uses it on the given channel. The number stays in your inventory and is free to reassign. # Search numbers available to buy Source: https://developers.mihu.ai/api-reference/phone-numbers/search-numbers-available-to-buy https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/search Browse phone numbers available for purchase in a given country. You can filter by type (local, toll-free, mobile, national), area code, or pattern. Results include pricing and whether compliance steps will be required before activation. # Update an external trunk Source: https://developers.mihu.ai/api-reference/phone-numbers/update-an-external-trunk https://app.mihu.ai/docs/api-docs.json patch /api/v1/phone-numbers/trunks Updates an existing external trunk (registered via POST /trunks). Identify the trunk by `phone_number` + `channel`. Any field omitted is left untouched. SIP fields set to empty string clear that credential. # Update channel settings Source: https://developers.mihu.ai/api-reference/phone-numbers/update-channel-settings https://app.mihu.ai/docs/api-docs.json patch /api/v1/phone-numbers/{uuid} Turn voice, SMS, or inbound on or off, set per-channel concurrency limits, and choose which destination countries are allowed for outbound traffic. Channels can't be turned on while compliance is still pending for the number. # Upload a compliance document Source: https://developers.mihu.ai/api-reference/phone-numbers/upload-a-compliance-document https://app.mihu.ai/docs/api-docs.json post /api/v1/phone-numbers/documents Uploads a document (e.g. proof of ID, business license, address proof) needed for compliance on a phone number purchase. Returns a document ID you then pass into the purchase endpoint under requirements[].document_id. # Which agents use which numbers Source: https://developers.mihu.ai/api-reference/phone-numbers/which-agents-use-which-numbers https://app.mihu.ai/docs/api-docs.json get /api/v1/phone-numbers/used-channels-and-accounts A summary of every active phone number and the agents using it, grouped by channel. Includes both numbers you've purchased and external ones (e.g. WhatsApp Business). Powers the 'Used Channels & Accounts' dashboard. # Add existing contacts to a pool Source: https://developers.mihu.ai/api-reference/pools/add-existing-contacts-to-a-pool https://app.mihu.ai/docs/api-docs.json post /api/v1/pools/{uuid}/contacts Adds one or more existing contacts (by UUID) to the pool, creating ContactPoolItem rows with status=Pending. Contacts already present in the pool are silently skipped (no error). UUIDs that don't resolve to a contact are returned in contact_uuids_not_found rather than failing the whole call. Side effect: if the pool is attached to ONE OR MORE campaigns currently in 'In Process' status, tasks are auto-created for the newly added contacts in EVERY running campaign — and ProcessWhatsAppCampaign is dispatched for text/sms campaigns. The whole operation is transactional: pool inserts and task creation succeed together or roll back together. # Create a contact pool Source: https://developers.mihu.ai/api-reference/pools/create-a-contact-pool https://app.mihu.ai/docs/api-docs.json post /api/v1/pools Creates an empty pool. After creation, populate it with POST /api/v1/pools/{uuid}/contacts and attach it to a campaign with POST /api/v1/campaigns/{uuid}/pools. # Delete a pool Source: https://developers.mihu.ai/api-reference/pools/delete-a-pool https://app.mihu.ai/docs/api-docs.json delete /api/v1/pools/{uuid} Deletes the pool. Refuses with 409 if the pool is attached to any campaign in 'In Process' or 'Importing' status — pause/stop those campaigns first or detach the pool from them. Pool items (contacts) inside the pool are deleted along with the pool. # Duplicate a pool, optionally copying its contacts Source: https://developers.mihu.ai/api-reference/pools/duplicate-a-pool-optionally-copying-its-contacts https://app.mihu.ai/docs/api-docs.json post /api/v1/pools/{uuid}/duplicate Creates a new pool with the same configuration as the source (type, max_parallel_items, max_retries, is_active, description). The new pool gets a fresh UUID and is NOT attached to any campaign — attach it explicitly with POST /api/v1/campaigns/{uuid}/pools. By default, all pool items are copied with status reset to Pending; pass copy_contacts=false to create an empty duplicate. Useful for splitting a successful pool template across multiple campaigns. # Get pool details, including attached campaigns and pool item status counts Source: https://developers.mihu.ai/api-reference/pools/get-pool-details-including-attached-campaigns-and-pool-item-status-counts https://app.mihu.ai/docs/api-docs.json get /api/v1/pools/{uuid} Returns the full pool resource plus a status_counts breakdown (Pending/Processing/Completed/Failed/etc.) and the list of campaigns this pool is attached to. For paginated contact lists inside the pool, use GET /api/v1/pools/{uuid}/contacts instead. # List contact pools Source: https://developers.mihu.ai/api-reference/pools/list-contact-pools https://app.mihu.ai/docs/api-docs.json get /api/v1/pools Returns a paginated list of pools. Each pool is a named bucket of contacts that one or more campaigns can draw from. Pool 'type' (FIFO/LIFO/Parallel) controls the order pool items are processed when a campaign runs. # List contacts in a pool Source: https://developers.mihu.ai/api-reference/pools/list-contacts-in-a-pool https://app.mihu.ai/docs/api-docs.json get /api/v1/pools/{uuid}/contacts Returns paginated ContactPoolItem rows in the pool, each enriched with the underlying Contact's name/email/phone and the item's processing state (status, retry_count, started_at, etc.). Sorted by most recently updated first. Supports search and status filtering for triage workflows. # Remove a contact from a pool Source: https://developers.mihu.ai/api-reference/pools/remove-a-contact-from-a-pool https://app.mihu.ai/docs/api-docs.json delete /api/v1/pools/{uuid}/contacts/{contact_uuid} Removes the specified contact from this pool. Side effect: cancels (status='cancelled') any scheduled/queued/pending tasks tied to THIS pool item. Tasks for the same contact in OTHER pools attached to the same campaign are NOT affected — cancellation is keyed by contact_pool_item_id, not by contact_id. # Update a pool Source: https://developers.mihu.ai/api-reference/pools/update-a-pool https://app.mihu.ai/docs/api-docs.json put /api/v1/pools/{uuid} Partial update. Send only the fields you want to change. Use the is_active flag to activate/deactivate — there is no separate toggle endpoint. Updates do not affect contact membership; pool items are unchanged. # Create a QA agent Source: https://developers.mihu.ai/api-reference/qa-agents/create-a-qa-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/qa-agents Creates a QA agent with its scorecard. Send `skills` to define your own scorecard (weights must total 100%), or leave it out to start with the standard one: Greeting 15%, Empathy 20%, Compliance 25%, Resolution 25%, Sales 15%. Your first QA agent automatically becomes the default. # Delete a QA agent Source: https://developers.mihu.ai/api-reference/qa-agents/delete-a-qa-agent https://app.mihu.ai/docs/api-docs.json delete /api/v1/qa-agents/{uuid} Deletes a QA agent and its scorecard. Past evaluation results are kept. The default QA agent cannot be deleted — set another agent as default first. # Get one QA agent Source: https://developers.mihu.ai/api-reference/qa-agents/get-one-qa-agent https://app.mihu.ai/docs/api-docs.json get /api/v1/qa-agents/{uuid} Returns one QA agent with its full scorecard — skills, weights, AI prompts, and scoring items. The skill `uuid` values you get here are what you send back when updating skills in place. # List QA agents Source: https://developers.mihu.ai/api-reference/qa-agents/list-qa-agents https://app.mihu.ai/docs/api-docs.json get /api/v1/qa-agents Returns your QA agents, default agent first. Example: `GET /api/v1/qa-agents?search=support&evaluates_agent_type=human&per_page=10`. # Replace the scorecard skills Source: https://developers.mihu.ai/api-reference/qa-agents/replace-the-scorecard-skills https://app.mihu.ai/docs/api-docs.json put /api/v1/qa-agents/{uuid}/skills Replaces the scorecard without touching other settings. Include a skill's `uuid` to keep and update it, omit the uuid to add a new skill — any skill you leave out is removed. Weights must total 100%. # Set a QA agent as default Source: https://developers.mihu.ai/api-reference/qa-agents/set-a-qa-agent-as-default https://app.mihu.ai/docs/api-docs.json post /api/v1/qa-agents/{uuid}/set-default Makes this QA agent the default evaluator. The previous default is switched off automatically — there is always exactly one default. No request body needed. # Update a QA agent Source: https://developers.mihu.ai/api-reference/qa-agents/update-a-qa-agent https://app.mihu.ai/docs/api-docs.json patch /api/v1/qa-agents/{uuid} Updates a QA agent — only the fields you send are changed. When you include `skills`, the list replaces the whole scorecard: include a skill's `uuid` to keep and update it, omit the uuid to add a new skill, and any skill you leave out is removed. Weights must total 100%. Note: the current default agent stays default until you set another one as default. # Update a QA agent (same as PATCH) Source: https://developers.mihu.ai/api-reference/qa-agents/update-a-qa-agent-same-as-patch https://app.mihu.ai/docs/api-docs.json put /api/v1/qa-agents/{uuid} Works exactly like PATCH /api/v1/qa-agents/{uuid}. # Add a human agent to the queue Source: https://developers.mihu.ai/api-reference/queues/add-a-human-agent-to-the-queue https://app.mihu.ai/docs/api-docs.json post /api/v1/queues/{uuid}/members # Assign a number/account to the queue Source: https://developers.mihu.ai/api-reference/queues/assign-a-numberaccount-to-the-queue https://app.mihu.ai/docs/api-docs.json post /api/v1/queues/{uuid}/channels # Create a queue Source: https://developers.mihu.ai/api-reference/queues/create-a-queue https://app.mihu.ai/docs/api-docs.json post /api/v1/queues # Create a routing for the queue Source: https://developers.mihu.ai/api-reference/queues/create-a-routing-for-the-queue https://app.mihu.ai/docs/api-docs.json post /api/v1/queues/{uuid}/routings A routing is a named, ordered list of rules. Each rule is IF (a trigger on one of the queue's channels) THEN (transfer to an AI agent). Rules run top-down; the first match wins. # Delete a queue Source: https://developers.mihu.ai/api-reference/queues/delete-a-queue https://app.mihu.ai/docs/api-docs.json delete /api/v1/queues/{uuid} Deletes the queue and releases all of its numbers/accounts so they can be assigned to another queue. # Delete a routing Source: https://developers.mihu.ai/api-reference/queues/delete-a-routing https://app.mihu.ai/docs/api-docs.json delete /api/v1/queues/{uuid}/routings/{routing} # Get one queue with its full configuration Source: https://developers.mihu.ai/api-reference/queues/get-one-queue-with-its-full-configuration https://app.mihu.ai/docs/api-docs.json get /api/v1/queues/{uuid} Accepts a workspace API token or a per-user JWT (mihu scope `numbers` / Loop scope `loop.conversations.view`). # List numbers/accounts not yet assigned to any queue Source: https://developers.mihu.ai/api-reference/queues/list-numbersaccounts-not-yet-assigned-to-any-queue https://app.mihu.ai/docs/api-docs.json get /api/v1/queues/available-endpoints Per channel, the endpoints that can still be assigned to a queue. Use the returned `id` when assigning. Accepts a workspace API token or a per-user JWT (mihu scope `numbers` / Loop scope `loop.conversations.view`). # List queues Source: https://developers.mihu.ai/api-reference/queues/list-queues https://app.mihu.ai/docs/api-docs.json get /api/v1/queues Returns every queue with its channel assignments (mode, AI agent, SLA, knowledge gap, callback, overflow, escalation, working hours), human members and routings — the complete configuration, exactly as shown in the Queues screen. Accepts a workspace API token (all queues) or a per-user JWT (mihu scope `numbers` / Loop scope `loop.conversations.view`) — with a JWT only the queues the user is a member of are returned. # Remove a human agent from the queue Source: https://developers.mihu.ai/api-reference/queues/remove-a-human-agent-from-the-queue https://app.mihu.ai/docs/api-docs.json delete /api/v1/queues/{uuid}/members/{email} # Remove a number/account from the queue Source: https://developers.mihu.ai/api-reference/queues/remove-a-numberaccount-from-the-queue https://app.mihu.ai/docs/api-docs.json delete /api/v1/queues/{uuid}/channels/{assignment} # Update a channel assignment's settings Source: https://developers.mihu.ai/api-reference/queues/update-a-channel-assignments-settings https://app.mihu.ai/docs/api-docs.json put /api/v1/queues/{uuid}/channels/{assignment} Updates any of the per-number settings, exactly as on the Queues screen: mode, AI agent, SLA, knowledge gap (enabled/threshold/hand_off_to), callback (enabled/user_email/prompt), overflow, escalation, working hours. Only the keys you send are changed. # Update a queue (name, color, active state, default SLA) Source: https://developers.mihu.ai/api-reference/queues/update-a-queue-name-color-active-state-default-sla https://app.mihu.ai/docs/api-docs.json put /api/v1/queues/{uuid} # Update a routing Source: https://developers.mihu.ai/api-reference/queues/update-a-routing https://app.mihu.ai/docs/api-docs.json put /api/v1/queues/{uuid}/routings/{routing} # Create a new campaign contact rule Source: https://developers.mihu.ai/api-reference/rules/create-a-new-campaign-contact-rule https://app.mihu.ai/docs/api-docs.json post /api/v1/rules Creates a standalone rule that can later be attached to one or more campaigns via PUT /api/v1/campaigns/{uuid}/rule. The rule's `type` (call vs text) governs which fields are honored and which defaults are applied. # Delete a rule Source: https://developers.mihu.ai/api-reference/rules/delete-a-rule https://app.mihu.ai/docs/api-docs.json delete /api/v1/rules/{uuid} Deletes the rule and detaches it from any campaigns it was attached to. Refuses with 409 if the rule is currently attached to a campaign with status Active, In Process, or Importing — pause/stop those campaigns first or assign a different rule to them. # Get a single rule by UUID Source: https://developers.mihu.ai/api-reference/rules/get-a-single-rule-by-uuid https://app.mihu.ai/docs/api-docs.json get /api/v1/rules/{uuid} Returns one campaign contact rule by UUID, including type, retry limits, retry interval, allowed working hours, escalation behavior, and active state. Use this before attaching a rule to a campaign or before updating cadence settings. # List campaign contact rules Source: https://developers.mihu.ai/api-reference/rules/list-campaign-contact-rules https://app.mihu.ai/docs/api-docs.json get /api/v1/rules Returns a paginated list of contact rules used by campaigns to control call/message cadence (max attempts, retry interval, allowed working hours, escalation policy). # Update an existing rule Source: https://developers.mihu.ai/api-reference/rules/update-an-existing-rule https://app.mihu.ai/docs/api-docs.json put /api/v1/rules/{uuid} Partial update — only fields you send are changed. Important: changing `type` from 'call' to 'text' automatically nulls call-only fields (retry_interval_minutes, end_time, escalation_*) regardless of what you send for them. Updates do NOT retroactively rebuild already-scheduled tasks on running campaigns; new tasks created after the update use the new values. # Create a new schedule Source: https://developers.mihu.ai/api-reference/schedules/create-a-new-schedule https://app.mihu.ai/docs/api-docs.json post /api/v1/schedules Creates a bookable schedule and links it to an availability type. Use this after creating or selecting an availability type. The schedule can then be assigned to agents for appointment booking and can collect custom question answers during booking. # Delete a schedule Source: https://developers.mihu.ai/api-reference/schedules/delete-a-schedule https://app.mihu.ai/docs/api-docs.json delete /api/v1/schedules/{uuid} Deletes a schedule by UUID. Use this when a calendar should no longer be offered for appointment booking. Existing appointment records may still reference their historical schedule data. # Get a specific schedule Source: https://developers.mihu.ai/api-reference/schedules/get-a-specific-schedule https://app.mihu.ai/docs/api-docs.json get /api/v1/schedules/{uuid} Returns one schedule by UUID with its availability type, assigned agent metadata, custom questions, and display color. Use this before updating a schedule or when showing calendar details for appointment booking. # Get all schedules Source: https://developers.mihu.ai/api-reference/schedules/get-all-schedules https://app.mihu.ai/docs/api-docs.json get /api/v1/schedules Returns schedules with their attached availability type. Per-user JWTs only receive shared schedules or schedules assigned to that user. Workspace API tokens retain workspace-wide access. # Update a schedule Source: https://developers.mihu.ai/api-reference/schedules/update-a-schedule https://app.mihu.ai/docs/api-docs.json put /api/v1/schedules/{uuid} Updates schedule metadata such as name, type, color, availability type, assigned agents, or custom questions. Use this to change how an existing calendar is presented and which booking rules it uses. Only supplied fields are changed. # The identities this workspace can send from, on any channel Source: https://developers.mihu.ai/api-reference/senders/the-identities-this-workspace-can-send-from-on-any-channel https://app.mihu.ai/docs/api-docs.json get /api/v1/senders One list of everything an outbound conversation can leave from: WhatsApp numbers, SMS numbers, outbound caller IDs and email addresses. Every entry has the same shape — only `identifier` changes meaning (a phone number, or an email address). **When to use it.** Before starting a new outbound conversation, so the operator chooses what the customer sees. A workspace usually owns several numbers, they need not belong to the same WhatsApp Business Account, and contacting somebody from a number they have never seen — while an open thread sits on another one — is how outbound goes wrong. **What to send with.** `agent_uuid` is the send identity for `whatsapp`, `sms` and `call`: it is what `POST /whatsapp/template` takes as `agentId`, and what `GET /whatsapp/templates?agent_uuid=` narrows the catalogue by. Email is the exception — there the send identity is the mailbox itself, so pass `endpoint_uuid` as `from` to `POST /email/messages`. Both fields are always present, so a caller can hold one field per channel without special-casing the rest of the object. **Why WhatsApp needs the number chosen first.** Templates are approved per WABA. Picking the number and then listing templates for that same `agent_uuid` is what stops a send being rejected by Meta after the operator has already written the message. **sendable.** True when the sender can actually originate: it is bound to an agent, has what the provider needs (a Meta phone number id, a number, an address), and is not in a state that blocks sending. A receive-only endpoint comes back `sendable: false` with `agent_uuid: null` — show it disabled rather than hiding it, so the gap stays visible to whoever administers the workspace. Statuses we do not recognise count as sendable, so an unfamiliar provider value never hides a working sender. **Channels covered.** `whatsapp`, `sms`, `call`, `email`. Facebook and Instagram are deliberately absent — the sender there is a page identity, not something an operator picks. **Who can call it, and how much of it they see.** A workspace API token, or a per-user JWT holding `loop.templates.send`. A workspace token gets every sender, and so does an admin or the workspace owner on an app JWT. A Loop JWT (`loop_scopes`) is an operator: admins and the owner included, it gets only the senders routed to an ACTIVE queue that user is a member of — an admin who is a member of no queue at all keeps the full list. Every other per-user JWT gets only the senders routed to an ACTIVE queue that user is a member of: the same membership rule the inbox reads by, so an operator is never offered a number whose replies would land in somebody else's queue. A sender routed to no queue at all is workspace/admin-only, exactly like an unassigned conversation. # Create a session label Source: https://developers.mihu.ai/api-reference/session-labels/create-a-session-label https://app.mihu.ai/docs/api-docs.json post /api/v1/session-labels With a workspace API token: omit user_email to create a default label available to everyone, or pass a member's email to create it just for them. With a per-user token: the label is always created for the token's own user — this is how a member adds their personal labels from Loop. # Delete a session label Source: https://developers.mihu.ai/api-reference/session-labels/delete-a-session-label https://app.mihu.ai/docs/api-docs.json delete /api/v1/session-labels/{uuid} Deletes a label. With a workspace API token any label can be deleted; with a per-user token only the member's own labels. # List session labels Source: https://developers.mihu.ai/api-reference/session-labels/list-session-labels https://app.mihu.ai/docs/api-docs.json get /api/v1/session-labels With a workspace API token, returns every label, optionally filtered by owner. With a per-user token, returns what that member can use: the defaults plus their own labels — exactly what a label picker should show. # Set a session's labels Source: https://developers.mihu.ai/api-reference/session-labels/set-a-sessions-labels https://app.mihu.ai/docs/api-docs.json put /api/v1/sessions/{uuid}/labels Replaces the session's labels with the given set — the multi-select picker in Loop sends its full current selection. Pass an empty array to remove every label from the session. With a per-user token only the defaults and the member's own labels can be used; a workspace API token can use any label. # Update a session label Source: https://developers.mihu.ai/api-reference/session-labels/update-a-session-label https://app.mihu.ai/docs/api-docs.json put /api/v1/session-labels/{uuid} Updates name, color, and/or assignment. Only supplied fields change. Assignment (workspace token only): pass user_email with a member's email to assign the label to them, or with null to make it a default for everyone. A per-user token can only rename/recolor its own labels. # Get paginated list of conversation sessions Source: https://developers.mihu.ai/api-reference/sessions/get-paginated-list-of-conversation-sessions https://app.mihu.ai/docs/api-docs.json get /api/v1/sessions Returns paginated conversation sessions. Sessions group messages or voice activity into reviewable interaction windows. Use filters to find sessions by conversation, contact, agent, campaign, task, status, type, or date ordering. # Get paginated messages of a session Source: https://developers.mihu.ai/api-reference/sessions/get-paginated-messages-of-a-session https://app.mihu.ai/docs/api-docs.json get /api/v1/sessions/{uuid}/messages Returns paginated messages that belong to one conversation session. Use this to inspect exactly which AI, human, and contact messages were included in the session window before reading its summary or evaluation. # Get paginated sessions of a conversation Source: https://developers.mihu.ai/api-reference/sessions/get-paginated-sessions-of-a-conversation https://app.mihu.ai/docs/api-docs.json get /api/v1/conversations/{uuid}/sessions Returns sessions that belong to one conversation. Use this to navigate from a conversation to its grouped text or voice sessions, then fetch messages or evaluations for a specific session. # Get session details Source: https://developers.mihu.ai/api-reference/sessions/get-session-details https://app.mihu.ai/docs/api-docs.json get /api/v1/sessions/{uuid} Returns one conversation session with contact, conversation, agent, campaign/listing/task references, summary fields, timestamps, and evaluation status. Use this before fetching session messages or evaluation details. # Get the evaluation of a session Source: https://developers.mihu.ai/api-reference/sessions/get-the-evaluation-of-a-session https://app.mihu.ai/docs/api-docs.json get /api/v1/sessions/{uuid}/evaluation Returns the evaluation record for one conversation session when analysis exists. Each dimension includes value, confidence, and reason fields. Use this to inspect the AI quality analysis for a specific session without fetching the full evaluation list. # Accept a proposed improvement (updates the agent's fields) Source: https://developers.mihu.ai/api-reference/simulations/accept-a-proposed-improvement-updates-the-agents-fields https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations/{uuid}/optimize/accept Applies the change set to the AGENT — exactly like editing it in the Skills/Advanced editor — and this changes how it answers real customers. It does NOT write a raw prompt. Specifically: `changes.fields` overwrite the agent columns (role, objective→purpose, company_service→company offer, interest_of_product→interacting with, tone→writing style, length_detail→response length, negative_response→action if no answer); `changes.guidelines_add` create new Response Guideline records; `changes.notes_add` create Note records; `changes.training_add` create Training Data records. Then the agent's prompt is regenerated from those fields (same builder as Skills) and any custom_prompt override is cleared. Works from a 'proposed' attempt (no trial needed) or a 'ready' one. Reversible with /optimize/revert. # Create a simulation Source: https://developers.mihu.ai/api-reference/simulations/create-a-simulation https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations Creates a draft. Personas may be omitted — they are generated from the test cases when the simulation first runs. Set run=true to queue it immediately. # Creation catalog: channels, agents per channel, caller lines and the per-message rate Source: https://developers.mihu.ai/api-reference/simulations/creation-catalog:-channels-agents-per-channel-caller-lines-and-the-per-message-rate https://app.mihu.ai/docs/api-docs.json get /api/v1/simulations/options # Delete a simulation Source: https://developers.mihu.ai/api-reference/simulations/delete-a-simulation https://app.mihu.ai/docs/api-docs.json delete /api/v1/simulations/{uuid} # Generate customer personas for an assistant Source: https://developers.mihu.ai/api-reference/simulations/generate-customer-personas-for-an-assistant https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations/generate-personas Builds realistic customers of the assistant's actual business (profile, guidelines, training rules, scenarios and prompt are all considered). Nothing is saved — use the result in create/update. # Generate test cases for an assistant Source: https://developers.mihu.ai/api-reference/simulations/generate-test-cases-for-an-assistant https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations/generate-test-cases Builds test cases with success criteria from the assistant's prompt and its configured activities (intents). Nothing is saved — use the result in create/update. # Get one conversation with its full transcript Source: https://developers.mihu.ai/api-reference/simulations/get-one-conversation-with-its-full-transcript https://app.mihu.ai/docs/api-docs.json get /api/v1/simulations/{uuid}/runs/{runUuid} Transcript entries: who=customer (the persona), who=assistant, who=tool (a real intent/tool execution with its request and response). Real calls include record_url. While the run is in progress the transcript grows on every read. # Get one simulation with its full configuration and run summaries Source: https://developers.mihu.ai/api-reference/simulations/get-one-simulation-with-its-full-configuration-and-run-summaries https://app.mihu.ai/docs/api-docs.json get /api/v1/simulations/{uuid} # Get the aggregated report Source: https://developers.mihu.ai/api-reference/simulations/get-the-aggregated-report https://app.mihu.ai/docs/api-docs.json get /api/v1/simulations/{uuid}/report Available once the batch has finished at least once: overall score, per-criterion verdicts (met when passed in the majority of runs), deduplicated issues by severity, improvement suggestions, and averages. Per-conversation detail lives under /runs. # List simulations Source: https://developers.mihu.ai/api-reference/simulations/list-simulations https://app.mihu.ai/docs/api-docs.json get /api/v1/simulations # List the simulation's conversations (current batch) Source: https://developers.mihu.ai/api-reference/simulations/list-the-simulations-conversations-current-batch https://app.mihu.ai/docs/api-docs.json get /api/v1/simulations/{uuid}/runs # Propose field changes to improve the assistant (review before test/apply) Source: https://developers.mihu.ai/api-reference/simulations/propose-field-changes-to-improve-the-assistant-review-before-testapply https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations/{uuid}/optimize From the finished report, proposes changes to the agent's fields (data.optimizations[].changes: {fields, guidelines_add, notes_add, training_add}) plus a plain-language summary — nothing is applied yet. Then apply directly (POST /optimize/accept: writes the fields, rebuilds the prompt, clears custom_prompt), or test first (POST /optimize/trial: re-runs the simulation with the prompt those field changes would produce). The live assistant is NOT changed until accept. # Reject a proposed improvement (assistant keeps its current prompt) Source: https://developers.mihu.ai/api-reference/simulations/reject-a-proposed-improvement-assistant-keeps-its-current-prompt https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations/{uuid}/optimize/reject # Run a simulation Source: https://developers.mihu.ai/api-reference/simulations/run-a-simulation https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations/{uuid}/run Queues the batch: runs_per_case conversations per test case. Simulated assistant messages are billed at the plan's text rate; an empty wallet blocks the run. Poll GET /simulations/{uuid} until state becomes passed or failed, then read /report. # Stop a running simulation Source: https://developers.mihu.ai/api-reference/simulations/stop-a-running-simulation https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations/{uuid}/stop Ends any live call, closes unfinished conversations. Conversations that already finished keep their results; if none finished, the simulation returns to draft. # Test a proposed improvement before applying it Source: https://developers.mihu.ai/api-reference/simulations/test-a-proposed-improvement-before-applying-it https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations/{uuid}/optimize/trial Re-runs the simulation with the proposed candidate prompt (simulated, billed like a run) so you can see the new score. When it finishes (poll GET /{uuid}), the attempt becomes 'ready' with before/after scores. Optionally pass an edited prompt to test your own tweak of the candidate. # Undo an accepted improvement (restore the previous prompt) Source: https://developers.mihu.ai/api-reference/simulations/undo-an-accepted-improvement-restore-the-previous-prompt https://app.mihu.ai/docs/api-docs.json post /api/v1/simulations/{uuid}/optimize/revert Restores the prompt an accepted attempt replaced. Refused (409 'prompt_changed') if the assistant's prompt has changed since it was applied, so a revert never clobbers a newer intentional edit. # Update a simulation (full replace of its configuration) Source: https://developers.mihu.ai/api-reference/simulations/update-a-simulation-full-replace-of-its-configuration https://app.mihu.ai/docs/api-docs.json put /api/v1/simulations/{uuid} Same body as create. Rejected while the simulation is running — in-flight runs are judged against the test cases by position. # Add a new SIP trunk connection Source: https://developers.mihu.ai/api-reference/sip-trunk/add-a-new-sip-trunk-connection https://app.mihu.ai/docs/api-docs.json post /api/v1/channels/sip-trunk/connections Creates a SIP trunk connection. Once created, assign it to an agent via POST /api/v1/agents/{uuid}/channels/call/sip-trunk. # Assign a SIP trunk connection to an agent for calls Source: https://developers.mihu.ai/api-reference/sip-trunk/assign-a-sip-trunk-connection-to-an-agent-for-calls https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/channels/call/sip-trunk Assigns a SIP trunk connection to this agent for calls. If the agent was previously bound to a different number, the old binding is torn down. # Delete a SIP trunk connection Source: https://developers.mihu.ai/api-reference/sip-trunk/delete-a-sip-trunk-connection https://app.mihu.ai/docs/api-docs.json delete /api/v1/channels/sip-trunk/connections/{uuid} Deletes a SIP trunk connection and removes agent assignments that depend on it. Use this when the provider trunk is no longer valid or should stop routing calls through the platform. Related telephony trunk configuration for the number is also removed. # List all SIP trunk connections Source: https://developers.mihu.ai/api-reference/sip-trunk/list-all-sip-trunk-connections https://app.mihu.ai/docs/api-docs.json get /api/v1/channels/sip-trunk/connections Returns SIP trunk connections configured for the workspace. Use this before assigning a SIP trunk to an agent for calls. Authentication secrets are never returned; only connection metadata, phone number, gateway, and status are included. # Reply within an SMS conversation Source: https://developers.mihu.ai/api-reference/sms/reply-within-an-sms-conversation https://app.mihu.ai/docs/api-docs.json post /api/v1/sms/conversations/{uuid}/reply Channel-scoped variant of the conversation reply: sends a human SMS reply into an SMS conversation. Same request and response as POST /api/v1/conversations/{uuid}/reply; the conversation must be an SMS conversation (422 otherwise). SMS is text-only — files are rejected. # Send an SMS message Source: https://developers.mihu.ai/api-reference/sms/send-an-sms-message https://app.mihu.ai/docs/api-docs.json post /api/v1/sms/send Sends an SMS message to a phone number using the specified agent's SMS configuration. The agent must have an SMS channel configured with a valid phone number and messaging profile. # What sending a message costs, by country Source: https://developers.mihu.ai/api-reference/sms/what-sending-a-message-costs-by-country https://app.mihu.ai/docs/api-docs.json get /api/v1/sms/rates The price list for outbound SMS, per destination country. **Prices are per message part, not per message.** A message longer than a single SMS is split by the network into several parts and every part is charged, so a three-part message to Germany costs three times the German rate. The number of parts is decided by the network, not something you set. One price per country. Mobile networks within a country are priced the same, and in any case the sending side cannot know which network a number belongs to beforehand. These rates apply to traffic that goes through our numbers. If you connect your own messaging provider, that provider bills you directly and nothing here applies. The amounts shown cover standard mobile destinations. Messages to other number types can be charged differently, so treat this list as the price for ordinary traffic rather than a guarantee for every destination — the wallet transaction for a message always carries the exact amount. Inbound messages and MMS are charged but are not published here yet, so filtering by `direction=inbound` or `message_type=mms` returns an empty list rather than an error. # Add a column to a table Source: https://developers.mihu.ai/api-reference/tables/add-a-column-to-a-table https://app.mihu.ai/docs/api-docs.json post /api/v1/data/{uuid}/fields Adds a new column to a table schema. Use this when agents need another structured field available for lookup or when future records require a new value. Existing records keep an empty value for the new column until they are updated. # Assign imported data to an agent Source: https://developers.mihu.ai/api-reference/tables/assign-imported-data-to-an-agent https://app.mihu.ai/docs/api-docs.json post /api/v1/data/{uuid}/assign Assigns a data source or table to an agent and starts asynchronous synchronization. Use this after importing or creating data so the agent can search or query it during conversations. The response confirms the assignment and sync trigger. # Create a record for imported data Source: https://developers.mihu.ai/api-reference/tables/create-a-record-for-imported-data https://app.mihu.ai/docs/api-docs.json post /api/v1/data/{uuid}/records Creates a new record with values for the specified knowledge base. Provide either a values array (with column_id or column_name) or a record object keyed by field names. # Create an empty table with a column schema Source: https://developers.mihu.ai/api-reference/tables/create-an-empty-table-with-a-column-schema https://app.mihu.ai/docs/api-docs.json post /api/v1/data/tables Creates a new table that agents can use as a knowledge base or for real-time data lookups. The table is empty after creation; records are added via POST /api/v1/data/{uuid}/records. # Delete a column Source: https://developers.mihu.ai/api-reference/tables/delete-a-column https://app.mihu.ai/docs/api-docs.json delete /api/v1/data/{uuid}/fields/{field_uuid} Soft-deletes the column. Existing record values for this column are kept on disk but no longer surface in field/record listings. # Delete a record Source: https://developers.mihu.ai/api-reference/tables/delete-a-record https://app.mihu.ai/docs/api-docs.json delete /api/v1/data/{uuid}/records/{record} Deletes one table record and its stored field values. Use this when a row is obsolete, duplicated, or should no longer be available to agents during structured lookup. # Delete imported data Source: https://developers.mihu.ai/api-reference/tables/delete-imported-data https://app.mihu.ai/docs/api-docs.json delete /api/v1/data/{uuid} Soft-deletes a data source or table by UUID. Use this when the knowledge source should no longer be available for assignment or lookup. Agent sync state should be refreshed after removing data that was already assigned. # Get all imported data Source: https://developers.mihu.ai/api-reference/tables/get-all-imported-data https://app.mihu.ai/docs/api-docs.json get /api/v1/data Returns imported data sources and manually created tables for the workspace. Use this endpoint to find data UUIDs, inspect processing status, choose sources to assign to agents, or monitor whether imports are ready for sync. # Get data details by UUID Source: https://developers.mihu.ai/api-reference/tables/get-data-details-by-uuid https://app.mihu.ai/docs/api-docs.json get /api/v1/data/{uuid} Returns one data source or table by UUID, including metadata, type, processing state, and stored path information when applicable. Use this before assigning data to an agent, adding records, updating metadata, or deleting the source. # Get fields (columns) for imported data Source: https://developers.mihu.ai/api-reference/tables/get-fields-columns-for-imported-data https://app.mihu.ai/docs/api-docs.json get /api/v1/data/{uuid}/fields Returns the columns defined for a table or imported structured data source. Use this before adding records, mapping imported data, or building a form that writes row values by column_id or column_name. # Get records for imported data Source: https://developers.mihu.ai/api-reference/tables/get-records-for-imported-data https://app.mihu.ai/docs/api-docs.json get /api/v1/data/{uuid}/records Returns paginated table records with their field values. Use this to inspect imported rows, power external data review tools, or retrieve the records an agent can query during conversations. # Import data from a website URL Source: https://developers.mihu.ai/api-reference/tables/import-data-from-a-website-url https://app.mihu.ai/docs/api-docs.json post /api/v1/data/import/website Crawls a website URL and imports discovered page content into a knowledge source. Use this when an agent should answer from public documentation, help centers, service pages, or product pages. Crawling is limited in depth, and processing continues asynchronously after the response. # Import data via copy-paste text Source: https://developers.mihu.ai/api-reference/tables/import-data-via-copy-paste-text https://app.mihu.ai/docs/api-docs.json post /api/v1/data/import/copypaste Creates a table-like knowledge source from raw text. Use this for FAQs, policies, product notes, or any pasted content that an agent should search when answering questions. The response returns the data UUID immediately while processing continues asynchronously. # Import data via file upload Source: https://developers.mihu.ai/api-reference/tables/import-data-via-file-upload https://app.mihu.ai/docs/api-docs.json post /api/v1/data/import/file Uploads a file and starts asynchronous processing so the content can become agent knowledge or structured records. Use this for CSV, Excel, JSON, PDF, XML, text, and audio sources up to 128MB. The response returns the data UUID and processing status; assign and sync the data before relying on it in agent conversations. # Trigger a sync for data across all associated agents Source: https://developers.mihu.ai/api-reference/tables/trigger-a-sync-for-data-across-all-associated-agents https://app.mihu.ai/docs/api-docs.json post /api/v1/data/{uuid}/sync Starts a fresh synchronization for all agents assigned to the data source. Use this after changing table records, columns, imported content, or metadata so each assigned agent receives the latest searchable or queryable data. # Update a column (rename and/or change data_type) Source: https://developers.mihu.ai/api-reference/tables/update-a-column-rename-andor-change-data_type https://app.mihu.ai/docs/api-docs.json put /api/v1/data/{uuid}/fields/{field_uuid} Renames the column and/or changes its data_type. If data_type changes, all existing values for this column must coerce to the new type or the request is rejected. # Update record values Source: https://developers.mihu.ai/api-reference/tables/update-record-values https://app.mihu.ai/docs/api-docs.json put /api/v1/data/{uuid}/records/{record} Updates one or more values for a specific record. Provide either a values array (with column_id or column_name) or a record object keyed by field names. # Update table metadata (name and description) Source: https://developers.mihu.ai/api-reference/tables/update-table-metadata-name-and-description https://app.mihu.ai/docs/api-docs.json put /api/v1/data/{uuid} Updates table metadata without changing its columns or records. Use this to rename a knowledge source or clarify what the table contains after import or manual creation. Existing agent assignments remain in place. # Cancel a task Source: https://developers.mihu.ai/api-reference/tasks/cancel-a-task https://app.mihu.ai/docs/api-docs.json post /api/v1/tasks/{uuid}/cancel Cancels a task that has not finished. Use this when planned outreach should be stopped before it executes. Pending, scheduled, queued, and in-progress tasks can be cancelled; completed tasks remain unchanged. # Create a new task (Call, SMS, WhatsApp, or Email) Source: https://developers.mihu.ai/api-reference/tasks/create-a-new-task-call-sms-whatsapp-or-email https://app.mihu.ai/docs/api-docs.json post /api/v1/tasks Creates a one-off task for an agent. Use make_call for outbound calls and send_message with task_data.message_type=whatsapp_template for WhatsApp template sends. Provide contact_uuid for an existing contact, or provide contact details so the API can find or create the contact by phone or email. Campaigns can also create tasks automatically; use this endpoint when you need a direct single task. # Delete a task Source: https://developers.mihu.ai/api-reference/tasks/delete-a-task https://app.mihu.ai/docs/api-docs.json delete /api/v1/tasks/{uuid} Soft-deletes a task and removes it from normal task lists. Use this when the work should no longer run. If the task is pending, scheduled, queued, or in progress, it is cancelled before deletion. # Get a specific task Source: https://developers.mihu.ai/api-reference/tasks/get-a-specific-task https://app.mihu.ai/docs/api-docs.json get /api/v1/tasks/{uuid} Returns one task by UUID with its contact, campaign, agent, channel, schedule, status, retry information, and task payload. Use this to inspect why a task is pending, queued, completed, failed, cancelled, or waiting for retry. # Get paginated list of tasks Source: https://developers.mihu.ai/api-reference/tasks/get-paginated-list-of-tasks https://app.mihu.ai/docs/api-docs.json get /api/v1/tasks Returns scheduled and historical tasks with filters for type, status, executor (ai/human), assignee, contact, campaign, agent, priority, and scheduled time. With a workspace API token every task is returned; with a per-user token only that member's own tasks (assigned to or created by them) plus tasks of AI agents answering for queues the member belongs to. # Get the task types available for an executor Source: https://developers.mihu.ai/api-reference/tasks/get-the-task-types-available-for-an-executor https://app.mihu.ai/docs/api-docs.json get /api/v1/tasks/types Returns the task types a client may use when creating a task, plus the form rules for that executor. For 'human' (the default) the list includes the free-form To-do type and the contact and schedule fields are optional; for 'ai' only channel types are returned and both a contact and a scheduled time are required. # Queue a task for execution Source: https://developers.mihu.ai/api-reference/tasks/queue-a-task-for-execution https://app.mihu.ai/docs/api-docs.json post /api/v1/tasks/{uuid}/queue Queues a task for execution now or at the provided delay. Use this to manually start a pending or scheduled task without waiting for its original scheduled_at time. The response returns the updated task state. # Retry a failed task Source: https://developers.mihu.ai/api-reference/tasks/retry-a-failed-task https://app.mihu.ai/docs/api-docs.json post /api/v1/tasks/{uuid}/retry Retries a failed task when the task has remaining attempts. Use this after correcting the reason for failure, such as missing contact data, unavailable channel binding, or temporary provider error. The response returns the task with its updated attempt and queue state. # Update a task Source: https://developers.mihu.ai/api-reference/tasks/update-a-task https://app.mihu.ai/docs/api-docs.json put /api/v1/tasks/{uuid} Updates an existing task. Use this to change schedule time, priority, assignee, description, status, or payload before execution. If status or scheduled_at changes in a way that requires execution, the task can be queued again according to its updated state. # Create a rule (opens tickets automatically from matching conversations) Source: https://developers.mihu.ai/api-reference/ticket-rules/create-a-rule-opens-tickets-automatically-from-matching-conversations https://app.mihu.ai/docs/api-docs.json post /api/v1/ticket-rules Once active, every finished conversation that matches `condition` (with confidence ≥ min_confidence) opens a ticket with this rule's priority, sent to the chosen queue or member. Write the condition the way you would explain it to a colleague; one situation per rule. # Delete a rule (existing tickets are kept) Source: https://developers.mihu.ai/api-reference/ticket-rules/delete-a-rule-existing-tickets-are-kept https://app.mihu.ai/docs/api-docs.json delete /api/v1/ticket-rules/{uuid} # Get a rule Source: https://developers.mihu.ai/api-reference/ticket-rules/get-a-rule https://app.mihu.ai/docs/api-docs.json get /api/v1/ticket-rules/{uuid} # List the rules that open tickets automatically Source: https://developers.mihu.ai/api-reference/ticket-rules/list-the-rules-that-open-tickets-automatically https://app.mihu.ai/docs/api-docs.json get /api/v1/ticket-rules # Make an agent inherit the workspace rules again Source: https://developers.mihu.ai/api-reference/ticket-rules/make-an-agent-inherit-the-workspace-rules-again https://app.mihu.ai/docs/api-docs.json post /api/v1/ticket-rules/reset Scope: exactly ONE agent, the `agent_uuid` in the body — required, there is no bulk reset. Deletes that agent's own rules (soft delete; tickets already opened are kept) and removes its set, so the agent uses the workspace rules again. Other agents' rules and the workspace rules are never touched. Use it also to recover an agent whose own set was emptied (an empty set means no automatic tickets for that agent). # Update a rule Source: https://developers.mihu.ai/api-reference/ticket-rules/update-a-rule https://app.mihu.ai/docs/api-docs.json put /api/v1/ticket-rules/{uuid} # Get the automation settings Source: https://developers.mihu.ai/api-reference/ticket-settings/get-the-automation-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/ticket-settings # Update the automation settings Source: https://developers.mihu.ai/api-reference/ticket-settings/update-the-automation-settings https://app.mihu.ai/docs/api-docs.json put /api/v1/ticket-settings # Create a status Source: https://developers.mihu.ai/api-reference/ticket-statuses/create-a-status https://app.mihu.ai/docs/api-docs.json post /api/v1/ticket-statuses # Delete a status Source: https://developers.mihu.ai/api-reference/ticket-statuses/delete-a-status https://app.mihu.ai/docs/api-docs.json delete /api/v1/ticket-statuses/{key} A status that still has tickets needs move_to: the key of the status those tickets go to. At least two statuses must remain. # List statuses in workflow order Source: https://developers.mihu.ai/api-reference/ticket-statuses/list-statuses-in-workflow-order https://app.mihu.ai/docs/api-docs.json get /api/v1/ticket-statuses # Reorder the workflow Source: https://developers.mihu.ai/api-reference/ticket-statuses/reorder-the-workflow https://app.mihu.ai/docs/api-docs.json put /api/v1/ticket-statuses/reorder # Update a status Source: https://developers.mihu.ai/api-reference/ticket-statuses/update-a-status https://app.mihu.ai/docs/api-docs.json put /api/v1/ticket-statuses/{key} # Create a tag Source: https://developers.mihu.ai/api-reference/ticket-tags/create-a-tag https://app.mihu.ai/docs/api-docs.json post /api/v1/ticket-tags # Delete a tag (removed from every ticket) Source: https://developers.mihu.ai/api-reference/ticket-tags/delete-a-tag-removed-from-every-ticket https://app.mihu.ai/docs/api-docs.json delete /api/v1/ticket-tags/{key} # List tags Source: https://developers.mihu.ai/api-reference/ticket-tags/list-tags https://app.mihu.ai/docs/api-docs.json get /api/v1/ticket-tags # Update a tag Source: https://developers.mihu.ai/api-reference/ticket-tags/update-a-tag https://app.mihu.ai/docs/api-docs.json put /api/v1/ticket-tags/{key} # Add a comment (what was done for the customer) Source: https://developers.mihu.ai/api-reference/tickets/add-a-comment-what-was-done-for-the-customer https://app.mihu.ai/docs/api-docs.json post /api/v1/tickets/{uuid}/notes JSON or multipart. Files can be sent inline as `files[]` (multipart) or uploaded first via POST /tickets/{uuid}/attachments and referenced by `attachment_uuids`. # Assign a ticket to a member or a queue Source: https://developers.mihu.ai/api-reference/tickets/assign-a-ticket-to-a-member-or-a-queue https://app.mihu.ai/docs/api-docs.json post /api/v1/tickets/{uuid}/assign Only the fields you send change. `assignee_email` sets the member (`null` releases the member, the queue is kept; per-user tokens may pass `me`). `queue_uuid` sets the queue (`null` removes the ticket from its queue, the member is kept). Send both to change both. An empty body releases member and queue together. # Change a ticket's status Source: https://developers.mihu.ai/api-reference/tickets/change-a-tickets-status https://app.mihu.ai/docs/api-docs.json put /api/v1/tickets/{uuid}/status # Delete a ticket Source: https://developers.mihu.ai/api-reference/tickets/delete-a-ticket https://app.mihu.ai/docs/api-docs.json delete /api/v1/tickets/{uuid} # Get a ticket with its activity Source: https://developers.mihu.ai/api-reference/tickets/get-a-ticket-with-its-activity https://app.mihu.ai/docs/api-docs.json get /api/v1/tickets/{uuid} # List tickets Source: https://developers.mihu.ai/api-reference/tickets/list-tickets https://app.mihu.ai/docs/api-docs.json get /api/v1/tickets # Open a ticket by hand Source: https://developers.mihu.ai/api-reference/tickets/open-a-ticket-by-hand https://app.mihu.ai/docs/api-docs.json post /api/v1/tickets # Remove a file from a ticket Source: https://developers.mihu.ai/api-reference/tickets/remove-a-file-from-a-ticket https://app.mihu.ai/docs/api-docs.json delete /api/v1/tickets/{uuid}/attachments/{attachment} # Replace a ticket's tags Source: https://developers.mihu.ai/api-reference/tickets/replace-a-tickets-tags https://app.mihu.ai/docs/api-docs.json put /api/v1/tickets/{uuid}/tags # Update a ticket Source: https://developers.mihu.ai/api-reference/tickets/update-a-ticket https://app.mihu.ai/docs/api-docs.json put /api/v1/tickets/{uuid} Only supplied fields change. assignee_email null releases the member; queue_uuid null takes the ticket out of its queue; tags replaces the whole tag set. # Upload a file to a ticket Source: https://developers.mihu.ai/api-reference/tickets/upload-a-file-to-a-ticket https://app.mihu.ai/docs/api-docs.json post /api/v1/tickets/{uuid}/attachments Multipart upload of one file (max 20 MB). The file is stored on the workspace media storage. Pass the returned uuid in a comment's attachment_uuids to bind it to that comment; unbound files stay listed on the ticket. # List supported timezones Source: https://developers.mihu.ai/api-reference/timezone/list-supported-timezones https://app.mihu.ai/docs/api-docs.json get /api/v1/timezone Catalog of IANA timezones accepted as `agent.timezone`. The `value` is what you pass on the agent record; the `label` is a human-readable string. # Create a new transcription request Source: https://developers.mihu.ai/api-reference/transcriptions/create-a-new-transcription-request https://app.mihu.ai/docs/api-docs.json post /api/v1/transcriptions Submits audio for asynchronous transcription and optional evaluation. Provide either voice_file or voice_url. Use reference_id to correlate the result with your own call or recording ID. If webhook_url is provided, the API sends the completed transcript, session identifiers, evaluation results, and processed timestamp to that URL; webhook_header_token is sent as a bearer token in the webhook request. # Get full transcript with conversation messages and evaluations Source: https://developers.mihu.ai/api-reference/transcriptions/get-full-transcript-with-conversation-messages-and-evaluations https://app.mihu.ai/docs/api-docs.json get /api/v1/transcriptions/{uuid}/transcript Returns the full completed transcript payload, including role/content conversation messages, full text, linked session data, and AI evaluations. Use this endpoint when you need the same structured result that is delivered to completion webhooks. # Get transcription by UUID Source: https://developers.mihu.ai/api-reference/transcriptions/get-transcription-by-uuid https://app.mihu.ai/docs/api-docs.json get /api/v1/transcriptions/{uuid} Returns one transcription by UUID, including status, reference_id, stored audio URL, transcript result when processing is complete, and selected QA/coaching agent identifiers. Use this to poll progress or retrieve the finished result when you are not using a webhook. # List user activity logs Source: https://developers.mihu.ai/api-reference/user-activity-logs/list-user-activity-logs https://app.mihu.ai/docs/api-docs.json get /api/v1/user-activity-logs Returns the activity trail of team members using the workspace through per-user tokens: which endpoints they called, whether access was granted, and from where. With a workspace API token the full team's activity is returned; with a per-user token only that user's own activity is returned. Results are newest first. # List notifications Source: https://developers.mihu.ai/api-reference/user-notifications/list-notifications https://app.mihu.ai/docs/api-docs.json get /api/v1/user-notifications With a per-user token, returns your own notifications; with a workspace API token, every member's. Newest first. Hidden notifications are excluded unless include_hidden=true. Use unread=true to badge the tray. # Mark all your notifications as read Source: https://developers.mihu.ai/api-reference/user-notifications/mark-all-your-notifications-as-read https://app.mihu.ai/docs/api-docs.json put /api/v1/user-notifications/read-all Marks every unread notification of the token's user as read — the tray's 'Mark all read' action. Per-user tokens only. # Mark one notification as read Source: https://developers.mihu.ai/api-reference/user-notifications/mark-one-notification-as-read https://app.mihu.ai/docs/api-docs.json put /api/v1/user-notifications/{uuid}/read Marks a single notification of the token's user as read. Per-user tokens only; a notification belonging to someone else returns 404. # Mark one notification as unread Source: https://developers.mihu.ai/api-reference/user-notifications/mark-one-notification-as-unread https://app.mihu.ai/docs/api-docs.json put /api/v1/user-notifications/{uuid}/unread Puts a single notification of the token's user back to unread — for when a member wants to revisit it later. Per-user tokens only; a notification belonging to someone else returns 404. # Get working statuses Source: https://developers.mihu.ai/api-reference/user-working-statuses/get-working-statuses https://app.mihu.ai/docs/api-docs.json get /api/v1/user-working-statuses With a per-user token, returns only your own working status. With a workspace API token, returns the working status of every team member, optionally filtered by status or email. # List all selectable working statuses Source: https://developers.mihu.ai/api-reference/user-working-statuses/list-all-selectable-working-statuses https://app.mihu.ai/docs/api-docs.json get /api/v1/user-working-statuses/options Returns every working status a member can choose, in menu order, with the machine key to send when updating, the label to display, and the indicator color. Use this to render the status picker instead of hardcoding the list. # Update your working status Source: https://developers.mihu.ai/api-reference/user-working-statuses/update-your-working-status https://app.mihu.ai/docs/api-docs.json put /api/v1/user-working-statuses Sets the working status of the user the token belongs to. Only per-user tokens can update a status — each member manages their own; a workspace API token gets a 403. # Add ONE guard rule (preserves existing rules) Source: https://developers.mihu.ai/api-reference/voice-ivr-&-guards/add-one-guard-rule-preserves-existing-rules https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/guard-rules Appends a guard rule. Existing guards are untouched. `when_condition` and `then_action` are required. If `then_action=forward`, also provide `destination_type` + `destination` (or `destination_agent_uuid` when destination_type=agent). If `then_action=end_conversation`, provide `say_before_end` for a polite closer. # Add ONE routing rule (preserves existing rules) Source: https://developers.mihu.ai/api-reference/voice-ivr-&-guards/add-one-routing-rule-preserves-existing-rules https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/routing-rules Appends a new routing rule. Existing rules are untouched. If `priority` is omitted, it defaults to (max existing priority + 1) so the new rule is evaluated last. Returns the agent with the full updated routing_rules list. Use POST for incremental builds; use PUT to replace the whole set. # Delete ONE guard rule (other guards untouched) Source: https://developers.mihu.ai/api-reference/voice-ivr-&-guards/delete-one-guard-rule-other-guards-untouched https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/guard-rules/{ruleUuid} Permanent removal. Removing a compliance/safety guard means the agent will no longer auto-handle that situation; verify you have a replacement guard or routing rule before deleting. To pause without deleting, PATCH with `is_active: false`. # Delete ONE routing rule (other rules untouched) Source: https://developers.mihu.ai/api-reference/voice-ivr-&-guards/delete-one-routing-rule-other-rules-untouched https://app.mihu.ai/docs/api-docs.json delete /api/v1/agents/{uuid}/routing-rules/{ruleUuid} Permanent removal. To temporarily disable instead of delete, PATCH the rule with `is_active: false` — the rule stays configured but does not fire. Returns the agent with the routing_rules list minus the deleted entry. # Partially update ONE guard rule Source: https://developers.mihu.ai/api-reference/voice-ivr-&-guards/partially-update-one-guard-rule https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/guard-rules/{ruleUuid} Updates only the fields you send. Common uses: toggle `is_active` to disable a guard temporarily; add a channel to `selected_channels`; tighten `when_condition` text after testing. Switching `then_action` between `forward` and `end_conversation` is supported but make sure the corresponding destination/say_before_* fields are set. # Partially update ONE routing rule Source: https://developers.mihu.ai/api-reference/voice-ivr-&-guards/partially-update-one-routing-rule https://app.mihu.ai/docs/api-docs.json patch /api/v1/agents/{uuid}/routing-rules/{ruleUuid} Updates only the fields you send. Other fields and other rules are untouched. Common uses: toggle `is_active` to disable a rule without deleting it; bump `priority` to reorder; tweak `voice_response` text without re-sending the whole rule. # Replace ALL guard rules for an agent (destructive) Source: https://developers.mihu.ai/api-reference/voice-ivr-&-guards/replace-all-guard-rules-for-an-agent-destructive https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/guard-rules Wipes every existing guard rule on this agent and inserts the provided list. Guards always take precedence over routing rules at runtime — when a guard fires, the conversation either ends or transfers regardless of any matching routing rule. Use guards for safety, compliance, abuse, or any scenario that should override the conversation flow. # Replace ALL routing rules for an agent (destructive) Source: https://developers.mihu.ai/api-reference/voice-ivr-&-guards/replace-all-routing-rules-for-an-agent-destructive https://app.mihu.ai/docs/api-docs.json put /api/v1/agents/{uuid}/routing-rules Wipes every existing routing rule on this agent and inserts the provided list. Use for bulk imports or full re-syncs from an external source. For incremental edits prefer POST/PATCH/DELETE on individual rules. In-flight calls already on a transfer path are unaffected; new calls hit the new rule set immediately. `priority` defaults to insertion order if omitted (1, 2, 3, ...). # List supported speeds for a voice Source: https://developers.mihu.ai/api-reference/voice-library/list-supported-speeds-for-a-voice https://app.mihu.ai/docs/api-docs.json get /api/v1/voice_speed/{voice_uuid} Send a voice UUID, receive the speed options that voice supports. `normal` is always returned; `fast` is included only when the voice's underlying model supports it. # List voices in the library Source: https://developers.mihu.ai/api-reference/voice-library/list-voices-in-the-library https://app.mihu.ai/docs/api-docs.json get /api/v1/voice_library Returns the public voice catalog for the workspace. Filter by `language`/`gender`/`accent` or fuzzy-match `name` with `search`. Use the returned `uuid` as `settings.voice.voice_profile.voice_uuid` when creating or updating an agent. # Get one wallet transaction Source: https://developers.mihu.ai/api-reference/wallet-transactions/get-one-wallet-transaction https://app.mihu.ai/docs/api-docs.json get /api/v1/wallet/transactions/{uuid} Requires a workspace API token. Returns one transaction only when it belongs to the current workspace wallet. A UUID from another workspace is returned as 404. # List wallet transactions Source: https://developers.mihu.ai/api-reference/wallet-transactions/list-wallet-transactions https://app.mihu.ai/docs/api-docs.json get /api/v1/wallet/transactions Requires a workspace API token. Returns only the current workspace wallet's transactions, newest first. Monetary values are exact decimal strings. Use call_uuid to independently verify that a call's analytics cost equals its wallet debit. Date filtering uses [from, to): from is inclusive and to is exclusive. # Make a WhatsApp call Source: https://developers.mihu.ai/api-reference/whatsapp-calling/make-a-whatsapp-call https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/call Starts a WhatsApp voice call from the selected agent to a contact phone number. Use this only after the contact has granted WhatsApp call permission for the business number. The response returns the initiated call state plus conversation/contact identifiers when available. # Send call permission request Source: https://developers.mihu.ai/api-reference/whatsapp-calling/send-call-permission-request https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/call/send_approval Sends a WhatsApp call permission request to a contact before placing a WhatsApp voice call. The contact receives an interactive approval message and can accept or reject calling permission. Use this when POST /api/v1/whatsapp/call returns no_permission. Requests are rate-limited to 1 per day and 2 per week per contact. # The WhatsApp numbers this workspace can send from Source: https://developers.mihu.ai/api-reference/whatsapp-senders/the-whatsapp-numbers-this-workspace-can-send-from https://app.mihu.ai/docs/api-docs.json get /api/v1/whatsapp/senders Every WhatsApp Business number configured on the workspace, with the agent that owns it, its WABA, and the queues it is routed to. **When to use it.** Before starting a new outbound WhatsApp conversation, so the operator picks which number the customer sees. `agent_uuid` from the chosen entry is exactly what `POST /whatsapp/template` wants as `agentId`, and passing the same value to `GET /whatsapp/templates?agent_uuid=…` narrows the catalogue to the templates that number's WABA has actually approved. Picking the number first and the template second is what stops a send failing at Meta. **Why the list exists.** The same information can be assembled by paging `GET /agents` and filtering `channels[]`, but that reads every agent record on the workspace to find a handful of numbers. This answers it directly. **sendable.** True when the number can actually originate a message: it is active and reachable through an agent (`agent_uuid` present) with a Meta phone number id. A number that is configured for receiving but has no agent behind it comes back `sendable: false` with `agent_uuid: null` — show it disabled rather than hiding it, so the gap is visible to whoever administers the workspace. **queues.** The queues this number is routed to, from the queue designer. Note that a queue's channel also names an `ai_agent` — that is who *answers* on the number, which is not necessarily the agent that *sends* from it. **Who can call it, and how much of it they see.** A workspace API token, or a per-user JWT holding `loop.templates.send`. A workspace token — and an admin or the workspace owner on a JWT — gets every number. Any other per-user JWT gets only the numbers routed to an ACTIVE queue that user is a member of, the same membership rule the inbox reads by; a number routed to no queue is workspace/admin-only. # Create a template setting (make a template campaign-ready) Source: https://developers.mihu.ai/api-reference/whatsapp-template-settings/create-a-template-setting-make-a-template-campaign-ready https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/template-settings Configures an APPROVED template for campaign use by defining what fills each {{n}} placeholder. The template must be APPROVED — settings on pending/rejected templates are refused. params.body must provide a value for every placeholder the template declares, keyed '1'..'N'. **Value kinds:** `{{contact.name}}` (base contact field), `{{custom.car_model}}` (custom field by key), or any literal string sent as-is. **Example — template body 'Ciao {{1}}, il tagliando della tua {{2}} è pronto da {{3}}.':** ``` { 'template_uuid': 'f50d783e-38e9-4d27-8a51-754b211bcd98', 'params': { 'body': { '1': '{{contact.name}}', '2': '{{custom.car_model}}', '3': 'Ambrosi Service' } } } ``` (Shown with single quotes for readability — send standard double-quoted JSON.) For each contact, {{1}} becomes their name, {{2}} their stored car model, {{3}} is always 'Ambrosi Service'. # Delete a template setting Source: https://developers.mihu.ai/api-reference/whatsapp-template-settings/delete-a-template-setting https://app.mihu.ai/docs/api-docs.json delete /api/v1/whatsapp/template-settings/{uuid} Deletes the setting. Refused with 409 while any campaign that references it is In Process, Importing, Active, or Paused — stop or finish those campaigns first. The underlying template is not affected. # Get one template setting Source: https://developers.mihu.ai/api-reference/whatsapp-template-settings/get-one-template-setting https://app.mihu.ai/docs/api-docs.json get /api/v1/whatsapp/template-settings/{uuid} # List all available merge tags for template placeholders Source: https://developers.mihu.ai/api-reference/whatsapp-template-settings/list-all-available-merge-tags-for-template-placeholders https://app.mihu.ai/docs/api-docs.json get /api/v1/whatsapp/template-settings/merge-fields Returns every merge tag you can use as a params.body value when creating or updating a template setting: contact_fields are the base contact attributes ({{contact.}}), custom_fields are this workspace's active custom contact fields ({{custom.}}). Any other string is sent literally. Call this BEFORE building a placeholder mapping so you only offer valid tags. # List template settings Source: https://developers.mihu.ai/api-reference/whatsapp-template-settings/list-template-settings https://app.mihu.ai/docs/api-docs.json get /api/v1/whatsapp/template-settings Returns template settings, newest first. Use template_uuid to see the settings of one template, waba_id to see everything usable by an agent on that WABA, and status=active to get exactly the set a campaign wizard would offer. # Update a template setting Source: https://developers.mihu.ai/api-reference/whatsapp-template-settings/update-a-template-setting https://app.mihu.ai/docs/api-docs.json put /api/v1/whatsapp/template-settings/{uuid} Updates the placeholder values and/or status. The underlying template cannot be changed — create a new setting for a different template. Changing params affects FUTURE sends only; messages already sent are not altered. Note for running campaigns: tasks resolve values at send time, so updating an active setting changes what in-flight campaign tasks will send. # Bulk-sync templates for a WABA from Meta into local DB Source: https://developers.mihu.ai/api-reference/whatsapp-templates/bulk-sync-templates-for-a-waba-from-meta-into-local-db https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/templates/sync 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). # Create a new WhatsApp template Source: https://developers.mihu.ai/api-reference/whatsapp-templates/create-a-new-whatsapp-template https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/templates Submits the template to Meta's WhatsApp Business API and stores it locally. The returned status is whatever Meta gave back — typically PENDING for newly submitted templates (approval is async on Meta's side, usually within minutes). Use POST /api/v1/whatsapp/templates/{uuid}/sync to refresh status later. Body components must follow Meta's component spec — see https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates. The `examples` section below shows 12 ready-to-copy bodies covering every combination — text-only, variables in header/body, IMAGE/VIDEO/DOCUMENT headers, footer, all four button types, and a full-feature template. **Variables ({{1}}, {{2}}, ...):** Whenever a component's `text` contains a `{{n}}` placeholder you MUST provide an `example` payload — Meta uses it to render a preview during approval review. - BODY variables → `example.body_text` is a NESTED array: `[['John','12345']]`. The outer array is per-language; we always pass a single inner row. - HEADER (TEXT) variables → `example.header_text` is a flat array: `['John']`. A TEXT header can have at most one `{{1}}` placeholder. - HEADER (IMAGE/VIDEO/DOCUMENT) → no variables. Provide `example.header_handle = ['']` from /upload-media. **Media headers (IMAGE/VIDEO/DOCUMENT):** Two-step flow — POST /upload-media first to get a `handle`, then put that handle in `components[i].example.header_handle[0]`. The component itself uses `type='HEADER'` with `format='IMAGE'|'VIDEO'|'DOCUMENT'` and no `text` field. **Footer:** Single component `{ type:'FOOTER', text:'...' }`. Plain text only — no variables, no formatting, max 60 chars. Common use: 'Reply STOP to unsubscribe.' **Buttons:** Single `{ type:'BUTTONS', buttons:[...] }` component. Up to 10 buttons. Four supported types: - QUICK_REPLY — `{ type:'QUICK_REPLY', text:'Yes' }`. Inbound reply arrives as a button click event. - URL — `{ type:'URL', text:'Track order', url:'https://example.com/{{1}}' }`. Supports one `{{1}}` placeholder in the URL. - PHONE_NUMBER — `{ type:'PHONE_NUMBER', text:'Call us', phone_number:'+1234567890' }`. E.164 format. - COPY_CODE — `{ type:'COPY_CODE', example:'WELCOME10' }`. No `text` — WhatsApp renders the code as the button label. **Status after create:** Always PENDING for new submissions. Approval is async on Meta's side (usually under 5 minutes for clean templates, hours for borderline content). Poll with POST /templates/{uuid}/sync, or wait for the webhook. # Delete a template (Meta + local) Source: https://developers.mihu.ai/api-reference/whatsapp-templates/delete-a-template-meta-+-local https://app.mihu.ai/docs/api-docs.json delete /api/v1/whatsapp/templates/{uuid} Calls Meta's delete API and soft-deletes the local record. After deletion, no campaigns can use this template. Note: Meta may keep historical message records that referenced this template. # Get a single template by UUID Source: https://developers.mihu.ai/api-reference/whatsapp-templates/get-a-single-template-by-uuid https://app.mihu.ai/docs/api-docs.json get /api/v1/whatsapp/templates/{uuid} Returns the full template resource including the components array (HEADER/BODY/FOOTER/BUTTONS) exactly as stored locally. Use this to inspect a template's structure before sending — for example to know which {{n}} variables you need to supply. The local copy is updated whenever you call POST /templates/{uuid}/sync; if status is stale, sync first. **Tenant scoping:** templates owned by other tenants return 404 (not 403) to avoid leaking existence. Non-whatsapp templates (sms/email) and orphan rows with no waba_id are also 404. # List WhatsApp Business Accounts linked to this tenant Source: https://developers.mihu.ai/api-reference/whatsapp-templates/list-whatsapp-business-accounts-linked-to-this-tenant https://app.mihu.ai/docs/api-docs.json get /api/v1/whatsapp/wabas Returns the WABAs this tenant has configured (via WhatsappSetting). Use these waba_ids when listing/creating/syncing templates. If empty, no WhatsApp Business Account has been linked yet — set one up under Settings → WhatsApp first. # List WhatsApp message templates Source: https://developers.mihu.ai/api-reference/whatsapp-templates/list-whatsapp-message-templates https://app.mihu.ai/docs/api-docs.json get /api/v1/whatsapp/templates Paginated list of templates stored locally. Filter by waba_id (recommended — templates are scoped per WhatsApp Business Account), status, category, language, or text search. To pull the latest from Meta into local DB first, call POST /api/v1/whatsapp/templates/sync. # Refresh a single template's status from Meta Source: https://developers.mihu.ai/api-reference/whatsapp-templates/refresh-a-single-templates-status-from-meta https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/templates/{uuid}/sync Re-fetches this one template from Meta and updates local status/components/category. The typical poll after POST /templates to check whether Meta has moved the template from PENDING to APPROVED, REJECTED, or PAUSED. **Typical polling pattern after creating a template:** 1. POST /templates → returns status=PENDING 2. Wait ~30s, then POST /templates/{uuid}/sync → still PENDING? 3. Backoff (1m, 2m, 5m) and repeat until status changes 4. APPROVED → safe to send. REJECTED → check `data.components` for rejection reason; create a new template with fixes. PAUSED → Meta flagged for quality; review before resuming. **Single-template scope:** unlike POST /templates/sync which walks the whole WABA, this only fetches one template by its Meta template_id. Cheap to call repeatedly. # Upload a media file Source: https://developers.mihu.ai/api-reference/whatsapp-templates/upload-a-media-file https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/templates/upload-media Upload an image, video, or document to Meta and receive a temporary media `handle` for a WhatsApp template header. Use this endpoint only when you are creating a WhatsApp template with a media HEADER: - IMAGE header: upload an image with `media_type=image` - VIDEO header: upload a video with `media_type=video` - DOCUMENT header: upload a document with `media_type=document` Do not use this endpoint for normal message attachments or campaign media uploads. If you want to send a WhatsApp campaign without managing template media handles, use the list/campaign workflow instead: create or import contacts into a list, attach the list to a WhatsApp campaign, upload or select the campaign media there, and send through the campaign. How to use the returned handle: 1. Call `POST /api/v1/whatsapp/templates/upload-media` with multipart form data: `waba_id`, `media_type`, and `file`. 2. Read `data.handle` from the response. 3. Call `POST /api/v1/whatsapp/templates` and place that handle at `components[i].example.header_handle[0]` on the media HEADER component. Example media HEADER component for the template-create request: set `type` to `HEADER`, set `format` to `IMAGE`, `VIDEO`, or `DOCUMENT`, and set `example.header_handle` to an array containing the returned handle. Why this endpoint exists: Meta requires media used in template headers to be uploaded first through a resumable upload session. The template-create request accepts the returned handle, not the binary file. Handle lifetime: the handle is short-lived. Create the template within about 24 hours after upload. If the handle expires, upload the file again and use the new handle. Validation before upload: - image: JPEG or PNG, maximum 5 MB - video: MP4 or 3GPP, maximum 16 MB - document: PDF, plain text, Word, Excel, or PowerPoint formats, maximum 100 MB - `media_type` must match the file MIME type. For example, uploading a PDF with `media_type=image` returns 422. # Reply within a WhatsApp conversation Source: https://developers.mihu.ai/api-reference/whatsapp/reply-within-a-whatsapp-conversation https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/conversations/{uuid}/reply Channel-scoped variant of the conversation reply: sends a human reply into a WhatsApp conversation. Same request and response as POST /api/v1/conversations/{uuid}/reply; the conversation must be a WhatsApp conversation (422 otherwise). Text and files are supported — the message becomes the first file's caption. Subject to WhatsApp's 24-hour customer service window; outside it use POST /api/v1/send-whatsapp-template. # Send WhatsApp template message Source: https://developers.mihu.ai/api-reference/whatsapp/send-whatsapp-template-message https://app.mihu.ai/docs/api-docs.json post /api/v1/whatsapp/template Sends a WhatsApp template message to a specified phone number using an agent's configured WhatsApp Business API. The template must be pre-approved by WhatsApp and the agent must have WhatsApp channel configured. # Read the workspace's own informations Source: https://developers.mihu.ai/api-reference/workspace-informations/read-the-workspaces-own-informations https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace View the workspace profile and defaults, including its name, display name, logo, current wallet balance, language, and timezone. Use these details when setting up agents or schedules so they follow the workspace's existing preferences. Wallet amounts are returned exactly as recorded, together with their currency. Readable with a workspace API token or any signed-in user token; no extra permission is needed. # Update the workspace language or timezone Source: https://developers.mihu.ai/api-reference/workspace-informations/update-the-workspace-language-or-timezone https://app.mihu.ai/docs/api-docs.json put /api/v1/workspace Partial update of the two workspace defaults other endpoints assume: language_code and timezone. Only the fields you send are changed. Name, currency, country, industry and account status are not editable here. Requires a workspace API token — user tokens can only read the workspace informations. # Get one invitation Source: https://developers.mihu.ai/api-reference/workspace-invitations/get-one-invitation https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/invitations/{email} Looks the invitation up by the invited e-mail address. URL-encode it, e.g. jane%40acme.com. # Invite a person by e-mail Source: https://developers.mihu.ai/api-reference/workspace-invitations/invite-a-person-by-e-mail https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/invitations Sends an invitation e-mail with a link valid for 48 hours. The person sets their own name and password when accepting, and lands in the workspace with exactly the roles and scopes named here — so at least one role or scope is required. The response carries `invitation_url` for clients that want to hand the link over themselves — treat it as a credential. Inviting an e-mail that already has a pending invitation replaces it with a fresh one. # List invitations Source: https://developers.mihu.ai/api-reference/workspace-invitations/list-invitations https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/invitations Every invitation issued for this workspace, newest first. A pending invitation still holds a seat on the plan; an expired one does not and can be resent. # Resend an invitation Source: https://developers.mihu.ai/api-reference/workspace-invitations/resend-an-invitation https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/invitations/{email}/resend Sends the invitation e-mail again with a NEW link and a fresh 48-hour window; the previous link stops working. Use it for an expired invitation or one the person never received. The roles and scopes stay as they were — change them by revoking and inviting again. # Revoke an invitation Source: https://developers.mihu.ai/api-reference/workspace-invitations/revoke-an-invitation https://app.mihu.ai/docs/api-docs.json delete /api/v1/workspace/invitations/{email} Deletes the invitation and invalidates its link, freeing the seat it was holding. Someone who already accepted is a member and is not affected. # Approve a join request Source: https://developers.mihu.ai/api-reference/workspace-join-requests/approve-a-join-request https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/join-requests/{email}/approve Creates the workspace member from the request — the person keeps the name and password they registered with — grants the roles and scopes named here, and notifies them that they can sign in. The request leaves the queue and is kept as history (status approved, with decided_at and decided_by); the credentials it carried are dropped. At least one role or scope is required: a member with no access could sign in and see nothing. Only a request in waiting_approval can be approved. # Get one join request Source: https://developers.mihu.ai/api-reference/workspace-join-requests/get-one-join-request https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/join-requests/{email} Looks the request up by the applicant's e-mail address. URL-encode it, e.g. jane%40acme.com. # List join requests Source: https://developers.mihu.ai/api-reference/workspace-join-requests/list-join-requests https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/join-requests The approval queue, newest request first. Defaults to the requests waiting for a decision. status=registration_pending shows people who started signing up but have not finished; status=approved is the history of admitted people (with decided_at / decided_by); status=all shows everything. Rejected requests are deleted and cannot be listed. # Reject a join request Source: https://developers.mihu.ai/api-reference/workspace-join-requests/reject-a-join-request https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/join-requests/{email}/reject Deletes the request and e-mails the applicant that they were not admitted. No member is created. They can register again later. # Find knowledge tables matching a query Source: https://developers.mihu.ai/api-reference/workspace-knowledge-base/find-knowledge-tables-matching-a-query https://app.mihu.ai/docs/api-docs.json get /api/v1/knowledge-base/lookup Lightweight lookup for pickers and library views: returns only the matching knowledge tables (uuid, name, description) — no content excerpts. Matches by table name and by content relevance, best match first. # Index a knowledge table for search Source: https://developers.mihu.ai/api-reference/workspace-knowledge-base/index-a-knowledge-table-for-search https://app.mihu.ai/docs/api-docs.json post /api/v1/knowledge-base/{uuid}/sync Re-indexes the table so its current content becomes searchable: for tables attached to agents this refreshes every agent's knowledge plus general search; unattached tables are indexed for general search. Indexing runs in the background — track progress via the table's status. Workspace API token only; user tokens receive 403. # List all knowledge tables in the workspace Source: https://developers.mihu.ai/api-reference/workspace-knowledge-base/list-all-knowledge-tables-in-the-workspace https://app.mihu.ai/docs/api-docs.json get /api/v1/knowledge-base Returns every knowledge table with its record count, the agents it is attached to (empty when unattached), its relevance filter (`min_score`, null = default) and its indexing state. `sync_status` values: `up_to_date` — indexed and current, searchable; `updating` — indexing is running in the background, compare `indexed_records` with `records_count` for progress; `sync_required` — the table's content changed after the last sync, search still returns the previously indexed version until it is re-synced; `not_indexed` — never indexed or removed from search, this table is NOT searchable until it is synced. # Remove a knowledge table from search Source: https://developers.mihu.ai/api-reference/workspace-knowledge-base/remove-a-knowledge-table-from-search https://app.mihu.ai/docs/api-docs.json delete /api/v1/knowledge-base/{uuid}/sync Removes the table's indexed content from search everywhere: agent answers and general search. The table's data itself is kept and can be re-indexed at any time with the sync endpoint. Workspace API token only; user tokens receive 403. # Search inside a single knowledge table Source: https://developers.mihu.ai/api-reference/workspace-knowledge-base/search-inside-a-single-knowledge-table https://app.mihu.ai/docs/api-docs.json post /api/v1/knowledge-base/{uuid}/search Semantic search with relevance reranking limited to one knowledge table, identified by its uuid (the Knowledge Id shown on the table page). The table must be indexed for search (synced, or added to general search). # Search the whole workspace knowledge base Source: https://developers.mihu.ai/api-reference/workspace-knowledge-base/search-the-whole-workspace-knowledge-base https://app.mihu.ai/docs/api-docs.json post /api/v1/knowledge-base/search Semantic search with relevance reranking across every knowledge table in the workspace — including tables not attached to any agent. Use table_uuids to limit the search to specific tables. # Update a knowledge table's relevance filter Source: https://developers.mihu.ai/api-reference/workspace-knowledge-base/update-a-knowledge-tables-relevance-filter https://app.mihu.ai/docs/api-docs.json put /api/v1/knowledge-base/{uuid}/settings min_score (0-1, e.g. 0.8 = the 80% setting in the table page's relevance filter) is the minimum relevance excerpts from THIS table need before they are used in answers — it overrides the agent-level setting for this table's content, everywhere the table is searched. Send null to inherit the agent setting / platform default. Note: relevance scores are not percentages of correctness — correct answers typically score 0.4-0.7, so values above ~0.5 increasingly drop valid results. Workspace API token only; user tokens receive 403. # Add a member directly Source: https://developers.mihu.ai/api-reference/workspace-members/add-a-member-directly https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/users Creates the member immediately with the password you set — no invitation, no acceptance step. Use it when you provision accounts yourself; use POST /api/v1/workspace/invitations when the person should set their own password. The member is created in the workspace with exactly the roles and scopes named here, so at least one of them is required. An e-mail that already belongs to a user (in this or any other workspace) is refused. # Get the company e-mail domain setting Source: https://developers.mihu.ai/api-reference/workspace-members/get-the-company-e-mail-domain-setting https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/email-domain Whether colleagues whose e-mail is on the workspace's company domain may find this workspace and request to join. The domain itself is derived from the workspace's contact e-mail (or the owner's) and cannot be set by hand; a public mailbox provider such as gmail.com never becomes a company domain, and then the setting cannot be turned on. Requests created this way land in the join-request approval queue. # List workspace members Source: https://developers.mihu.ai/api-reference/workspace-members/list-workspace-members https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/users Everyone in the workspace with their effective access, newest first. The response also carries the plan's seat usage — used counts the members (the owner included), pending_invitations counts seats promised to people who have not accepted yet, and available is what is left. A null limit means the plan has no seat limit. # Turn self-service joining on or off Source: https://developers.mihu.ai/api-reference/workspace-members/turn-self-service-joining-on-or-off https://app.mihu.ai/docs/api-docs.json put /api/v1/workspace/email-domain Enabling it publishes the workspace to people on the same company e-mail domain: they can register themselves and appear in the join-request approval queue. Disabling it removes the published domain — pending requests already in the queue stay and can still be approved or rejected. The domain is always derived from the workspace's contact e-mail (or the owner's), so there is nothing to send but the switch. # List every scope Source: https://developers.mihu.ai/api-reference/workspace-products/list-every-scope https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/scopes Every scope across all products, each carrying the product it belongs to. Useful for resolving the scope keys on an existing role back into labels. # List one product's scopes Source: https://developers.mihu.ai/api-reference/workspace-products/list-one-products-scopes https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/products/{product}/scopes The permissions offered by a single product, in display order. Because a role may only draw scopes from one product, this is exactly the set one role can be built from. # List products with their scopes Source: https://developers.mihu.ai/api-reference/workspace-products/list-products-with-their-scopes https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/products Returns every product a role can be built from, each with its full scope list - enough to render the whole role editor in one call. Scopes keep their display order, so a client can start a new section header whenever `group` changes. # Add a human member by email Source: https://developers.mihu.ai/api-reference/workspace-queue/add-a-human-member-by-email https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/queue/{uuid}/members Queue members are workspace users and are referenced by email, not user id. # Assign a channel endpoint to a queue Source: https://developers.mihu.ai/api-reference/workspace-queue/assign-a-channel-endpoint-to-a-queue https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/queue/{uuid}/channels Use the endpoint id returned by `/workspace/queue/available-endpoints` or `/workspace/queue/options`. Phone/voice numbers are channel `call`. # Create a queue and optionally assign initial channel endpoints Source: https://developers.mihu.ai/api-reference/workspace-queue/create-a-queue-and-optionally-assign-initial-channel-endpoints https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/queue Creates the queue. `endpoints` should contain selected channels from options/available-endpoints. For a phone number, send channel=call and id from available_endpoints.call[].id. Initial `mode` applies to all endpoints created by this request. # Create queue-wide IF -> THEN routing rules Source: https://developers.mihu.ai/api-reference/workspace-queue/create-queue-wide-if->-then-routing-rules https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/queue/{uuid}/routings Each rule references one of the queue channel assignment uuids. Trigger requirements come from `/workspace/queue/options.schema.routing_rules`: `wait` requires seconds, `keyword` requires keyword, `contact` requires field/operator/value. The only action is transfer_to_ai_agent. # Delete a queue and release its endpoints Source: https://developers.mihu.ai/api-reference/workspace-queue/delete-a-queue-and-release-its-endpoints https://app.mihu.ai/docs/api-docs.json delete /api/v1/workspace/queue/{uuid} # Delete a queue routing Source: https://developers.mihu.ai/api-reference/workspace-queue/delete-a-queue-routing https://app.mihu.ai/docs/api-docs.json delete /api/v1/workspace/queue/{uuid}/routings/{routing} # Get one queue with channels, members, and routings Source: https://developers.mihu.ai/api-reference/workspace-queue/get-one-queue-with-channels-members-and-routings https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/queue/{uuid} # List queues with full Team Management configuration Source: https://developers.mihu.ai/api-reference/workspace-queue/list-queues-with-full-team-management-configuration https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/queue Workspace-token-only list endpoint. Returns every queue, all channel assignments, members, and routings. Same data shape as the legacy `GET /api/v1/queues`, but under the workspace API namespace. # List unassigned channel endpoints Source: https://developers.mihu.ai/api-reference/workspace-queue/list-unassigned-channel-endpoints https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/queue/available-endpoints Returns the numbers/accounts that can still be assigned to a queue. If the client selected phone/call, call this with `?channel=call` or `?channel=phone` and use `data.call[].id` in `endpoints[].id` or the assign-channel body. # Partially update queue metadata Source: https://developers.mihu.ai/api-reference/workspace-queue/partially-update-queue-metadata https://app.mihu.ai/docs/api-docs.json patch /api/v1/workspace/queue/{uuid} Updates only supplied queue metadata fields: name, color, is_active, and queue-level default sla_seconds. # Queue designer schema, enums, conditionals, and live options Source: https://developers.mihu.ai/api-reference/workspace-queue/queue-designer-schema-enums-conditionals-and-live-options https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/queue/options Call this before creating or editing a queue. The response is intentionally descriptive for developers and AI agents: `schema.channels` tells which endpoint id to use when a channel is selected (`call`/phone uses `available_endpoints.call[].id`, `facebook` uses `page_id`, `instagram` uses `instagram_business_id`); `schema.conditional_by_mode` tells which settings are shown or omitted for `autopilot`, `copilot`, and `human_first`; `schema.flow` lists overflow, escalation, knowledge-gap, callback, and working-hours enums; `schema.routing_rules` lists IF -> THEN trigger requirements. `agents`, `users`, `contact_fields`, `target_queues`, and `knowledge_gap_queues` are live workspace choices. # Remove a channel endpoint from a queue Source: https://developers.mihu.ai/api-reference/workspace-queue/remove-a-channel-endpoint-from-a-queue https://app.mihu.ai/docs/api-docs.json delete /api/v1/workspace/queue/{uuid}/channels/{assignment} # Remove a human member by email Source: https://developers.mihu.ai/api-reference/workspace-queue/remove-a-human-member-by-email https://app.mihu.ai/docs/api-docs.json delete /api/v1/workspace/queue/{uuid}/members/{email} # Update a queue routing Source: https://developers.mihu.ai/api-reference/workspace-queue/update-a-queue-routing https://app.mihu.ai/docs/api-docs.json put /api/v1/workspace/queue/{uuid}/routings/{routing} Same behavior as PATCH. # Update a queue routing Source: https://developers.mihu.ai/api-reference/workspace-queue/update-a-queue-routing-1 https://app.mihu.ai/docs/api-docs.json patch /api/v1/workspace/queue/{uuid}/routings/{routing} Send `name` only for a name change, or include `rules` to replace the ordered rule list. # Update per-channel conditional behavior Source: https://developers.mihu.ai/api-reference/workspace-queue/update-per-channel-conditional-behavior https://app.mihu.ai/docs/api-docs.json put /api/v1/workspace/queue/{uuid}/channels/{assignment} Same behavior as PATCH; only supplied fields are changed. # Update per-channel conditional behavior Source: https://developers.mihu.ai/api-reference/workspace-queue/update-per-channel-conditional-behavior-1 https://app.mihu.ai/docs/api-docs.json patch /api/v1/workspace/queue/{uuid}/channels/{assignment} This is the main Team Management > Queue conditional update endpoint. Send only the changed fields. Mode controls visibility: `autopilot` omits working_hours; `copilot` may send working_hours but no after_hours selector is shown; `human_first` hides knowledge_gap and uses working_hours.after_hours as voicemail, closed, or agent uuid. Overflow/escalation target can be an agent uuid or a queue uuid. Knowledge-gap handoff must use a queue from options.knowledge_gap_queues. # Update queue metadata Source: https://developers.mihu.ai/api-reference/workspace-queue/update-queue-metadata https://app.mihu.ai/docs/api-docs.json put /api/v1/workspace/queue/{uuid} Same behavior as PATCH; only supplied fields are changed. # Create a role Source: https://developers.mihu.ai/api-reference/workspace-roles/create-a-role https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/roles Creates a role from a set of scopes belonging to one product. Get the available scope keys from /api/v1/workspace/products/{product}/scopes. Re-using the key of a role that was removed brings that role back with the new name and scopes. # Delete a role Source: https://developers.mihu.ai/api-reference/workspace-roles/delete-a-role https://app.mihu.ai/docs/api-docs.json delete /api/v1/workspace/roles/{role} Deletes the role. Members who held it lose the access it granted straight away, so check members_count first if that matters. The key stays reserved, and creating a role with it again brings this one back. # Get a role Source: https://developers.mihu.ai/api-reference/workspace-roles/get-a-role https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/roles/{role} Looks the role up by its UUID or by its key. # List roles Source: https://developers.mihu.ai/api-reference/workspace-roles/list-roles https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/roles Every role in the workspace, built-in ones first. Each role reports the product its scopes come from and how many members hold it. # Update a role Source: https://developers.mihu.ai/api-reference/workspace-roles/update-a-role https://app.mihu.ai/docs/api-docs.json put /api/v1/workspace/roles/{role} Only the supplied fields change. Sending scopes replaces the role's whole scope set - including moving it to another product, as long as every scope in the new set comes from that one product. Send an empty array to strip the role of all access. Members holding the role pick the change up immediately. PATCH behaves identically. # Assign roles or direct scopes to a user Source: https://developers.mihu.ai/api-reference/workspace-user-access/assign-roles-or-direct-scopes-to-a-user https://app.mihu.ai/docs/api-docs.json post /api/v1/workspace/users/{email}/access Partially updates a member's access by email. Send roles, scopes, or both. Role keys assign the role and therefore grant that role's scopes. Scopes are direct user-specific extras; any direct scope already covered by a submitted role is dropped from direct_scopes but remains in effective_scopes through the role. # Get a user's roles and scopes Source: https://developers.mihu.ai/api-reference/workspace-user-access/get-a-users-roles-and-scopes https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/users/{email}/access Looks up a workspace member by email and returns assigned workspace roles, role-derived scopes, direct user scopes, and final effective scopes. URL-encode the email address in the path, e.g. leylatest%40mihu.ai. # Remove a user's workspace access assignments Source: https://developers.mihu.ai/api-reference/workspace-user-access/remove-a-users-workspace-access-assignments https://app.mihu.ai/docs/api-docs.json delete /api/v1/workspace/users/{email}/access Removes all workspace role assignments and all direct user scopes from the member. Backoffice roles are not touched. The member may still have default full access in the web app if the product's no-role/no-scope fallback applies. # Replace a user's roles and direct scopes Source: https://developers.mihu.ai/api-reference/workspace-user-access/replace-a-users-roles-and-direct-scopes https://app.mihu.ai/docs/api-docs.json put /api/v1/workspace/users/{email}/access Replaces the member's workspace role list and direct scope list in one request. Omitted roles or scopes become empty arrays. Use this for a full save from an edit-user modal. # Update a user's roles or direct scopes Source: https://developers.mihu.ai/api-reference/workspace-user-access/update-a-users-roles-or-direct-scopes https://app.mihu.ai/docs/api-docs.json patch /api/v1/workspace/users/{email}/access Partially updates access. Sending scopes replaces only direct user scopes; role-provided scopes stay effective until the corresponding role is removed or replaced. # Plan, rates, packages, wallet and payments in one read Source: https://developers.mihu.ai/api-reference/workspace/plan-rates-packages-wallet-and-payments-in-one-read https://app.mihu.ai/docs/api-docs.json get /api/v1/workspace/billing Everything commercial about this workspace, so a billing screen or an invoice reconciliation can be built from a single request. **What comes back** - `plan` — which plan the workspace is on, what it costs per seat and per interval, and where the subscription stands. - `usage` — the price of every unit of usage. This is what the workspace is charged, with any negotiated pricing already applied. - `actions` — the monthly automation-flow allowance and the price beyond it. - `agents` — how many AI agents and live agent seats the plan includes, and the price of an extra AI agent. - Calls and SMS are priced by destination rather than by a single figure — see `/api/v1/phone-numbers/rates` and `/api/v1/sms/rates`. Those rates apply only to traffic that goes through our telephony; bring your own carrier or SIP trunk and that provider bills you instead. - `wallet` — the current balance and the auto top-up settings. - `packages` — prepaid units still unused, and when they expire. - `payments` — the last payment taken, the next one due, and recent history. **Two things worth knowing** `billed: false` on a usage row means the price is published and agreed but nothing raises a charge for it yet. Treat those as forthcoming, not as something appearing on an invoice today. `has_custom_pricing` tells you whether the rates in `usage` come from a negotiated agreement rather than the plan's standard ladder. The rates themselves already reflect it either way; the flag exists so you can label them. **Access** A workspace API token is required. A member's own token is refused even when it carries a matching scope, because these are terms for the account rather than anything belonging to one person. # Authentication Source: https://developers.mihu.ai/authentication Learn how to authenticate your API requests with Mihu ## Prerequisites Before you begin, make sure you have: * An active Mihu workspace account * Access to your workspace dashboard * Admin or developer permissions to create API tokens ## Getting Your API Token Follow these steps to generate your API authentication token: Navigate to your Mihu workspace at `https://your-tenant.mihu.ai` and sign in with your credentials. Click on your profile icon in the top right corner of the dashboard. From the dropdown menu, select **"Developer"** to access the developer settings. In the Developer section: * Click on **"Create New API Token"** or **"Generate Token"** * Give your token a descriptive name (e.g., "Production API", "Development Testing") * Set appropriate permissions if prompted * Click **"Create"** or **"Generate"** **Important**: Copy your API token immediately and store it securely. For security reasons, you won't be able to see it again after closing the dialog. Store your token in a secure location such as: * Environment variables * Secure credential management systems * Password managers (for development) **Never share your API token** or commit it to version control systems. Treat it like a password. If you suspect your token has been compromised, revoke it immediately and generate a new one. ## Understanding Your Tenant/Subdomain Your Mihu workspace URL contains your **tenant identifier** (also called subdomain), which is required for all API calls. ### How to Find Your Tenant Your tenant is the subdomain in your Mihu workspace URL: ``` https://abc.mihu.ai ^^^ This is your tenant ``` If your workspace URL is `https://abc.mihu.ai`, then your tenant is `abc`. ### Using Your Tenant in API Calls All API endpoints use your tenant in the base URL: ``` https://{your-tenant}.mihu.ai/api/v1/... ``` **Example:** ``` https://abc.mihu.ai/api/v1/calls ``` ## Authentication Format Mihu API uses **Bearer Token Authentication**. Include your API token in the `Authorization` header of every request: ``` Authorization: Bearer YOUR_API_TOKEN ``` ### Example Authentication Headers ```bash cURL theme={null} curl -X GET https://abc.mihu.ai/api/v1/calls \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```javascript JavaScript theme={null} const response = await fetch('https://abc.mihu.ai/api/v1/calls', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); const data = await response.json(); ``` ```python Python theme={null} import requests url = "https://abc.mihu.ai/api/v1/calls" headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get(url, headers=headers) data = response.json() ``` ```javascript Node.js theme={null} const axios = require('axios'); const response = await axios.get('https://abc.mihu.ai/api/v1/calls', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); const data = response.data; ``` ## Security Best Practices * Use environment variables for API tokens * Never hardcode tokens in your source code * Use secure credential management systems in production * Rotate tokens periodically All API requests must use HTTPS. HTTP requests will be rejected. The Mihu API enforces TLS 1.2 or higher. * Create multiple tokens for different services * Rotate tokens regularly (every 90 days recommended) * Have a process to quickly rotate compromised tokens * Create separate tokens for different environments (development, staging, production) * Use descriptive names to track token usage * Revoke unused tokens immediately * Regularly review API logs for unusual activity * Set up alerts for failed authentication attempts * Monitor token usage in the Developer section of your dashboard ## Token Management ### Viewing Active Tokens You can view all active API tokens in the Developer section of your workspace: 1. Go to your profile → Developer 2. View the list of active tokens 3. See token creation date and last used timestamp ### Revoking Tokens If you need to revoke a token: 1. Navigate to Developer section 2. Find the token in your list 3. Click **"Revoke"** or the delete icon 4. Confirm the revocation Revoking a token immediately invalidates it. Any applications using that token will no longer be able to authenticate. ### Creating Multiple Tokens You can create multiple tokens for different purposes: * **Development**: For local testing and development * **Staging**: For staging environment deployments * **Production**: For production applications * **CI/CD**: For automated deployment pipelines ## Authentication Errors Common authentication errors and how to resolve them: | Status Code | Error | Solution | | ----------- | ---------------------------- | ------------------------------------------------------- | | 401 | Unauthorized | Verify your token is correct and hasn't been revoked | | 401 | Missing Authorization header | Include the `Authorization: Bearer YOUR_TOKEN` header | | 401 | Invalid token format | Ensure you're using `Bearer YOUR_TOKEN` format | | 403 | Forbidden | Check that your token has the necessary permissions | | 404 | Not Found | Verify your tenant/subdomain in the base URL is correct | ## Testing Your Authentication You can test your authentication by making a simple API call: ```bash cURL theme={null} curl -X GET https://your-tenant.mihu.ai/api/v1/calls \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```javascript JavaScript theme={null} const testAuth = async () => { try { const response = await fetch('https://your-tenant.mihu.ai/api/v1/calls', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); if (response.ok) { console.log('Authentication successful!'); } else { console.error('Authentication failed:', response.status); } } catch (error) { console.error('Error:', error); } }; testAuth(); ``` ```python Python theme={null} import requests def test_auth(): url = "https://your-tenant.mihu.ai/api/v1/calls" headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } try: response = requests.get(url, headers=headers) if response.status_code == 200: print("Authentication successful!") else: print(f"Authentication failed: {response.status_code}") except Exception as e: print(f"Error: {e}") test_auth() ``` ## Next Steps Now that you have your API token and understand authentication: Make your first API call Explore all available endpoints Set up real-time notifications Track your API usage # CLI and MCP Source: https://developers.mihu.ai/cli/mcp Connect Claude Code, Cursor, VS Code, Windsurf and Claude Desktop to your Mihu workspace in one command The [Mihu MCP Server](/guides/mcp) lets AI clients manage your workspace in natural language. The CLI configures those clients with the workspace and token from `mihu login`, so you never edit a config file by hand. ## Set up a client ```bash theme={null} mihu mcp setup claude-code # runs `claude mcp add` for you mihu mcp setup cursor # writes ~/.cursor/mcp.json mihu mcp setup vscode # writes the user-level mcp.json mihu mcp setup windsurf # writes ~/.codeium/windsurf/mcp_config.json mihu mcp setup claude # Claude Desktop, through the mcp-remote bridge (needs Node.js) ``` Restart the client, or reload its MCP servers, and ask it something: > List my Mihu agents and tell me which ones have a phone number bound. The client calls tools such as `list_agents` and `list_agent_phone_numbers` on `https://mcp.mihu.ai/mcp`, which forwards them to your workspace with your token. The token is written into the client's configuration file in plain text. Remove it with `mihu mcp remove ` when you no longer need it, and revoke the token in your dashboard if the machine is shared. ## Narrow the tool set The server exposes several hundred tools. Clients work better with fewer: ```bash theme={null} mihu mcp setup cursor --tool-profile inbox # conversations, contacts, replies mihu mcp setup cursor --tool-profile campaigns # campaigns, listings, pools mihu mcp setup cursor --tools compact # every tool, shorter descriptions ``` Available profiles: `inbox`, `appointments`, `agent-builder`, `campaigns`, `workspace`, `quality`. ## Check the connection ```bash theme={null} mihu mcp status # server Mihu MCP Server 3.2.4 # url https://mcp.mihu.ai/mcp # tenant abc # tools 61 ``` ## Other clients `mihu mcp url` prints everything a client could need: the server URL, the headers, a URL with the token embedded for clients that cannot send headers, and the OAuth client credentials. ```bash theme={null} mihu mcp url mihu mcp url -o json ``` ## Remove ```bash theme={null} mihu mcp remove cursor mihu mcp remove claude-code ``` # Mihu CLI Source: https://developers.mihu.ai/cli/overview Manage your Mihu workspace from the terminal, in CI, and from your AI-powered IDE The Mihu CLI is the official command-line interface for Mihu. Every endpoint of the API is available as a command, so you can build agents, buy numbers, place calls, read conversations and run campaigns without leaving your terminal. In this guide you will: * Install and authenticate the CLI * Run your first commands * Manage several workspaces * Connect your AI IDE to Mihu through MCP ## Installation ```bash theme={null} curl -sSL https://mihu.ai/install.sh | bash ``` ```powershell theme={null} irm https://mihu.ai/install.ps1 | iex ``` The installer downloads a single binary for your platform, verifies its checksum and puts it on your PATH. No runtime is required. Verify with `mihu version`. If your shell already has an alias named `mihu`, the alias wins; rename it or run `command mihu`. ## Quick start ```bash theme={null} mihu login ``` The CLI asks for your workspace subdomain (the `abc` in `abc.mihu.ai`), opens the API token page of your dashboard, and stores the token you paste. See [Authentication](/authentication) for how tokens work. ```bash theme={null} mihu whoami # workspace, balance and where the credentials came from mihu agents list mihu numbers list ``` ```bash theme={null} mihu calls start +14155550123 --agent --greeting "Hi, this is a test call from Mihu" ``` The response includes the call id, the conversation id and a live listen URL. ## Key features ### Every endpoint, one command tree Commands mirror the API. Path segments become groups, path parameters become arguments and the HTTP method becomes the verb: ```bash theme={null} mihu agents webhooks list # GET /agents/{uuid}/webhooks mihu campaigns publish # POST /campaigns/{uuid}/publish mihu transcriptions transcript # GET /transcriptions/{uuid}/transcript mihu commands # print all commands ``` ### Interactive create and update Run a `create` or `update` command without arguments and the CLI walks you through every field with its description, validates enums and shows the request before sending it: ```bash theme={null} mihu agents create # [1/28] name * (string) # Required. Internal label for this agent # > Support Bot # [2/28] description (string) # > ... ``` Or pass fields as flags, since every body field is a typed flag: ```bash theme={null} mihu agents create --name "Support Bot" --language en --tone "Short and friendly" mihu contacts update --email ada@example.com ``` ### Scripting and CI Output is a table on a terminal and JSON when piped, so the CLI composes with `jq`: ```bash theme={null} mihu calls list --all -o json | jq '.[] | select(.status == "ended") | .uuid' ``` In CI, skip `mihu login` and set two environment variables: ```bash theme={null} export MIHU_API_TOKEN=your-api-token export MIHU_TENANT=abc mihu agents list ``` ### Several workspaces ```bash theme={null} mihu login --name production mihu login --name staging mihu -p staging agents list mihu config use production ``` ### MCP for your IDE Give Claude Code, Cursor, VS Code, Windsurf or Claude Desktop full knowledge of your workspace in one command: ```bash theme={null} mihu mcp setup cursor ``` See [CLI and MCP](/cli/mcp). ### Any endpoint For endpoints without a dedicated command, or when you want the raw response: ```bash theme={null} mihu api /workspace mihu api /agents/ -X PATCH -f name="New name" ``` ## Common commands ```bash theme={null} mihu agents list mihu agents get mihu agents create --name "Sales" --language en mihu agents update --tone "Formal" mihu agents from-website https://example.com mihu agents voice mihu agents webhooks create --url https://example.com/hook ``` ```bash theme={null} mihu numbers list mihu numbers search US --type local --area-code 415 mihu numbers buy -f number=+14155550123 -f country_code=US -f type=local mihu agents channels call provision --phone-number-uuid mihu numbers release ``` ```bash theme={null} mihu calls start +14155550123 --agent --prompt "Confirm tomorrow's appointment" mihu calls list --status ended mihu calls get mihu calls say "One moment please" mihu calls hangup ``` ```bash theme={null} mihu conversations list --channel whatsapp --status open mihu conversations messages mihu conversations reply "Thanks, we will call you back" mihu contacts list --search ada mihu contacts create --name "Ada" --phone-number +441234567890 ``` ```bash theme={null} mihu campaigns list mihu campaigns publish mihu tasks list --status pending mihu tasks list --type make_call --executor ai ``` ```bash theme={null} mihu transcriptions create --voice-file call.mp3 --possible-language en mihu transcriptions transcript mihu evaluations list mihu qa-agents list mihu coaching-agents list ``` ## Configuration Settings live in `~/.config/mihu/config.json`, credentials in `~/.config/mihu/credentials.json` (mode 0600). On Windows both are under `%AppData%\mihu`. ```bash theme={null} mihu config path # print the directory mihu config list # saved profiles mihu config set output json # default output format mihu config set disable_update_check true ``` Environment variables override everything: `MIHU_API_TOKEN`, `MIHU_TENANT`, `MIHU_BASE_URL`, `MIHU_PROFILE`, `MIHU_CONFIG_DIR`. ## Updates The CLI checks for a new version once a day and prints a one-line hint. Update with: ```bash theme={null} mihu update --check mihu update ``` ## Uninstall ```bash theme={null} mihu uninstall # removes the binary, keeps your settings mihu uninstall --purge # also deletes ~/.config/mihu with saved credentials ``` ## Next steps Connect Claude Code, Cursor, VS Code and Windsurf Every endpoint the CLI wraps # Error Handling Source: https://developers.mihu.ai/errors Understand error codes, responses, and troubleshooting strategies for the Mihu API ## Error Response Format All API errors follow a consistent JSON format to help you quickly identify and resolve issues. ```json Standard Error Response theme={null} { "success": false, "message": "Human-readable error description", "error": { "code": "ERROR_CODE", "details": "Additional context about the error", "field": "fieldName" // Present for validation errors } } ``` Always `false` for error responses A human-readable description of the error Detailed error information Machine-readable error code Additional context or explanation The specific field that caused the error (validation errors only) ## HTTP Status Codes The Mihu API uses standard HTTP status codes to indicate success or failure. ### Success Codes (2xx) | Status Code | Meaning | Description | | ----------- | ------- | ----------------------------- | | 200 | OK | Request succeeded | | 201 | Created | Resource successfully created | ### Client Error Codes (4xx) | Status Code | Meaning | Description | | ----------- | -------------------- | ---------------------------------------- | | 400 | Bad Request | Malformed request or invalid JSON | | 401 | Unauthorized | Missing or invalid authentication token | | 403 | Forbidden | Valid token but insufficient permissions | | 404 | Not Found | Resource or endpoint doesn't exist | | 422 | Unprocessable Entity | Validation failed on one or more fields | | 429 | Too Many Requests | Rate limit exceeded | ### Server Error Codes (5xx) | Status Code | Meaning | Description | | ----------- | --------------------- | -------------------------------------- | | 500 | Internal Server Error | Unexpected server error occurred | | 502 | Bad Gateway | Service temporarily unavailable | | 503 | Service Unavailable | Server overloaded or under maintenance | ## Common Errors ### Authentication Errors #### 401 Unauthorized - Missing Token ```json theme={null} { "success": false, "message": "Authentication required", "error": { "code": "MISSING_AUTH_TOKEN", "details": "No authorization header provided" } } ``` **Solution:** Include the `Authorization: Bearer YOUR_API_TOKEN` header in your request. ```bash cURL theme={null} curl -X GET https://your-tenant.mihu.ai/api/v1/calls \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ```javascript JavaScript theme={null} const response = await fetch('https://your-tenant.mihu.ai/api/v1/calls', { headers: { 'Authorization': `Bearer ${YOUR_API_TOKEN}` } }); ``` #### 401 Unauthorized - Invalid Token ```json theme={null} { "success": false, "message": "Invalid authentication token", "error": { "code": "INVALID_AUTH_TOKEN", "details": "The provided token is invalid or has been revoked" } } ``` **Solution:** Verify your API token is correct and hasn't been revoked. Generate a new token if necessary. #### 403 Forbidden - Insufficient Permissions ```json theme={null} { "success": false, "message": "Insufficient permissions", "error": { "code": "FORBIDDEN", "details": "Your API token does not have permission to access this resource" } } ``` **Solution:** Ensure your API token has the necessary permissions. Contact your workspace admin. ### Validation Errors #### 422 Unprocessable Entity - Missing Required Field ```json theme={null} { "success": false, "message": "Validation failed", "error": { "code": "VALIDATION_ERROR", "field": "agentId", "details": "The agentId field is required" } } ``` **Solution:** Include all required fields in your request body. #### 422 Unprocessable Entity - Invalid Format ```json theme={null} { "success": false, "message": "Validation failed", "error": { "code": "INVALID_FORMAT", "field": "participant.number", "details": "Phone number must be in E.164 format (e.g., +1234567890)" } } ``` **Solution:** Ensure phone numbers are in E.164 format (+\[country code]\[number]). ```javascript Valid E.164 Format theme={null} { "participant": { "number": "+1234567890" // ✓ Valid } } ``` ```javascript Invalid Formats theme={null} { "participant": { "number": "1234567890" // ✗ Missing + } } { "participant": { "number": "+1-234-567-890" // ✗ Contains hyphens } } ``` #### 422 Unprocessable Entity - Invalid UUID ```json theme={null} { "success": false, "message": "Validation failed", "error": { "code": "INVALID_UUID", "field": "agentId", "details": "agentId must be a valid UUID" } } ``` **Solution:** Ensure UUIDs are in the correct format (e.g., `550e8400-e29b-41d4-a716-446655440000`). ### Resource Errors #### 404 Not Found - Resource ```json theme={null} { "success": false, "message": "Resource not found", "error": { "code": "RESOURCE_NOT_FOUND", "details": "Call with ID '550e8400-e29b-41d4-a716-446655440000' not found" } } ``` **Solution:** Verify the resource ID is correct and the resource exists in your workspace. #### 404 Not Found - Endpoint ```json theme={null} { "success": false, "message": "Endpoint not found", "error": { "code": "ENDPOINT_NOT_FOUND", "details": "The requested endpoint does not exist" } } ``` **Solution:** Check the endpoint URL and HTTP method. Verify you're using the correct API version. ### Rate Limit Errors #### 429 Too Many Requests ```json theme={null} { "success": false, "message": "Rate limit exceeded", "error": { "code": "RATE_LIMIT_EXCEEDED", "details": "You have exceeded the rate limit of 1000 requests per minute", "retryAfter": 45 } } ``` **Solution:** Implement exponential backoff and retry logic. Wait for the time specified in `retryAfter` (seconds). ```javascript Retry with Exponential Backoff theme={null} async function makeRequestWithRetry(url, options, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { const response = await fetch(url, options); if (response.status === 429) { const data = await response.json(); const retryAfter = data.error.retryAfter || Math.pow(2, attempt); console.log(`Rate limited. Retrying after ${retryAfter}s...`); await new Promise(resolve => setTimeout(resolve, retryAfter * 1000)); continue; } return response; } catch (error) { if (attempt === maxRetries - 1) throw error; await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000)); } } } ``` ```python Retry with Exponential Backoff theme={null} import time import requests def make_request_with_retry(url, headers, max_retries=3): for attempt in range(max_retries): try: response = requests.get(url, headers=headers) if response.status_code == 429: data = response.json() retry_after = data.get('error', {}).get('retryAfter', 2 ** attempt) print(f"Rate limited. Retrying after {retry_after}s...") time.sleep(retry_after) continue return response except Exception as e: if attempt == max_retries - 1: raise e time.sleep(2 ** attempt) ``` ### Server Errors #### 500 Internal Server Error ```json theme={null} { "success": false, "message": "An unexpected error occurred", "error": { "code": "INTERNAL_SERVER_ERROR", "details": "Please try again later or contact support if the issue persists" } } ``` **Solution:** This is a temporary server error. Retry the request. If the error persists, contact [support@mihu.ai](mailto:support@mihu.ai) with the request details. #### 503 Service Unavailable ```json theme={null} { "success": false, "message": "Service temporarily unavailable", "error": { "code": "SERVICE_UNAVAILABLE", "details": "The service is under maintenance or experiencing high load" } } ``` **Solution:** Wait a few minutes and retry. Check the Mihu status page for ongoing incidents. ## Error Handling Best Practices Never assume a request succeeded. Always check the HTTP status code and handle errors appropriately. ```javascript theme={null} const response = await fetch(url, options); if (!response.ok) { const error = await response.json(); console.error('API Error:', error.message); // Handle error appropriately } ``` Implement exponential backoff for transient errors (5xx, 429). Don't retry client errors (4xx) except after fixing the issue. **Retry:** 429, 500, 502, 503 **Don't retry:** 400, 401, 403, 404, 422 Log errors with request IDs, timestamps, and relevant context for debugging. ```javascript theme={null} console.error('API Error', { timestamp: new Date().toISOString(), endpoint: url, status: response.status, error: errorData }); ``` Validate request data on the client side before sending to reduce validation errors. ```javascript theme={null} function validatePhoneNumber(number) { const e164Regex = /^\+[1-9]\d{1,14}$/; if (!e164Regex.test(number)) { throw new Error('Invalid phone number format'); } return true; } ``` Provide user-friendly error messages instead of exposing technical details. ```javascript theme={null} try { await initiateCall(phoneNumber); } catch (error) { if (error.status === 422) { showUserMessage('Please check the phone number format'); } else if (error.status === 429) { showUserMessage('Too many requests. Please try again in a moment'); } else { showUserMessage('An error occurred. Please try again'); } } ``` Track error rates and patterns in your monitoring system. Set up alerts for unusual error spikes. ## Complete Error Handling Example Here's a comprehensive example with proper error handling: ```javascript Complete Example - JavaScript theme={null} class MihuAPIClient { constructor(tenant, apiToken) { this.baseUrl = `https://${tenant}.mihu.ai/api/v1`; this.apiToken = apiToken; } async makeRequest(endpoint, options = {}) { const url = `${this.baseUrl}${endpoint}`; const defaultOptions = { headers: { 'Authorization': `Bearer ${this.apiToken}`, 'Content-Type': 'application/json', ...options.headers } }; const requestOptions = { ...defaultOptions, ...options }; try { const response = await fetch(url, requestOptions); // Handle successful responses if (response.ok) { return await response.json(); } // Parse error response const errorData = await response.json(); // Handle specific error types switch (response.status) { case 400: throw new Error(`Bad Request: ${errorData.message}`); case 401: throw new Error('Authentication failed. Please check your API token.'); case 403: throw new Error('Permission denied. Insufficient permissions.'); case 404: throw new Error(`Not found: ${errorData.message}`); case 422: const field = errorData.error?.field || 'unknown'; throw new Error(`Validation error in ${field}: ${errorData.message}`); case 429: const retryAfter = errorData.error?.retryAfter || 60; throw new Error(`Rate limit exceeded. Retry after ${retryAfter}s`); case 500: case 502: case 503: throw new Error('Server error. Please try again later.'); default: throw new Error(`API Error: ${errorData.message}`); } } catch (error) { if (error instanceof TypeError) { throw new Error('Network error. Please check your connection.'); } throw error; } } async initiateCall(agentId, phoneNumber, options = {}) { // Validate phone number format if (!/^\+[1-9]\d{1,14}$/.test(phoneNumber)) { throw new Error('Phone number must be in E.164 format (e.g., +1234567890)'); } return await this.makeRequest('/call', { method: 'POST', body: JSON.stringify({ agentId, participant: { number: phoneNumber }, ...options }) }); } } // Usage const client = new MihuAPIClient('your-tenant', 'YOUR_API_TOKEN'); try { const result = await client.initiateCall( '550e8400-e29b-41d4-a716-446655440000', '+1234567890' ); console.log('Call initiated:', result.data.id); } catch (error) { console.error('Failed to initiate call:', error.message); } ``` ```python Complete Example - Python theme={null} import requests import time from typing import Dict, Any, Optional class MihuAPIClient: def __init__(self, tenant: str, api_token: str): self.base_url = f"https://{tenant}.mihu.ai/api/v1" self.api_token = api_token self.headers = { "Authorization": f"Bearer {api_token}", "Content-Type": "application/json" } def make_request( self, endpoint: str, method: str = "GET", data: Optional[Dict[str, Any]] = None, max_retries: int = 3 ) -> Dict[str, Any]: url = f"{self.base_url}{endpoint}" for attempt in range(max_retries): try: if method == "GET": response = requests.get(url, headers=self.headers) elif method == "POST": response = requests.post(url, headers=self.headers, json=data) elif method == "PATCH": response = requests.patch(url, headers=self.headers, json=data) elif method == "DELETE": response = requests.delete(url, headers=self.headers) # Handle successful responses if response.ok: return response.json() # Parse error response error_data = response.json() # Handle specific error types if response.status_code == 400: raise ValueError(f"Bad Request: {error_data['message']}") elif response.status_code == 401: raise PermissionError("Authentication failed. Check your API token.") elif response.status_code == 403: raise PermissionError("Permission denied. Insufficient permissions.") elif response.status_code == 404: raise ValueError(f"Not found: {error_data['message']}") elif response.status_code == 422: field = error_data.get('error', {}).get('field', 'unknown') raise ValueError(f"Validation error in {field}: {error_data['message']}") elif response.status_code == 429: retry_after = error_data.get('error', {}).get('retryAfter', 60) if attempt < max_retries - 1: print(f"Rate limited. Retrying after {retry_after}s...") time.sleep(retry_after) continue raise Exception(f"Rate limit exceeded. Retry after {retry_after}s") elif response.status_code >= 500: if attempt < max_retries - 1: wait_time = 2 ** attempt print(f"Server error. Retrying in {wait_time}s...") time.sleep(wait_time) continue raise Exception("Server error. Please try again later.") else: raise Exception(f"API Error: {error_data['message']}") except requests.exceptions.ConnectionError: raise Exception("Network error. Please check your connection.") except requests.exceptions.Timeout: raise Exception("Request timeout. Please try again.") def initiate_call( self, agent_id: str, phone_number: str, options: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: # Validate phone number format import re if not re.match(r'^\+[1-9]\d{1,14}$', phone_number): raise ValueError("Phone number must be in E.164 format (e.g., +1234567890)") data = { "agentId": agent_id, "participant": {"number": phone_number} } if options: data.update(options) return self.make_request("/call", method="POST", data=data) # Usage client = MihuAPIClient('your-tenant', 'YOUR_API_TOKEN') try: result = client.initiate_call( '550e8400-e29b-41d4-a716-446655440000', '+1234567890' ) print(f"Call initiated: {result['data']['id']}") except Exception as e: print(f"Failed to initiate call: {e}") ``` ## Troubleshooting Guide ### Quick Diagnostics Verify your API token is correct and hasn't been revoked. Test with a simple GET request. Ensure your request body is valid JSON and includes all required fields. Verify you're using the correct tenant in your base URL. Check the [Monitoring](/monitoring) dashboard for detailed error information. Isolate the issue by testing with a simple cURL command. ### Common Issues and Solutions | Issue | Possible Cause | Solution | | ------------------- | --------------------------------------------- | -------------------------------------------------------- | | CORS errors | Calling API from browser without proper setup | Use server-side API calls or configure CORS in dashboard | | Timeout errors | Slow network or server overload | Implement retry logic with exponential backoff | | Invalid JSON | Malformed request body | Validate JSON before sending, use `JSON.stringify()` | | Wrong content-type | Missing or incorrect Content-Type header | Set `Content-Type: application/json` | | Inconsistent errors | Network instability | Check network connection, use retry logic | ## Getting Support If you continue to experience errors after troubleshooting: Review detailed logs in your dashboard Contact [support@mihu.ai](mailto:support@mihu.ai) with request details and log IDs Review endpoint-specific documentation Check status.mihu.ai for ongoing incidents ### Information to Include When contacting support, please provide: * **Request ID** from the error response or logs * **Timestamp** when the error occurred * **Endpoint** you were calling * **Request payload** (sanitized - remove sensitive data) * **Error response** received * **Expected behavior** ## Next Steps Learn to track and debug API issues Explore all available endpoints Follow our quickstart guide Set up event notifications # Builder MCP Server Source: https://developers.mihu.ai/guides/builder-mcp Build and run your own apps and integrations on Mihu from any MCP client The **Builder MCP Server** lets you build and run your own software on Mihu — described in plain language, from your own AI client (Claude Desktop, Claude Code, Cursor, or any MCP client). It is the customer-facing **integration and app builder**, delivered over the Model Context Protocol. Ask it for a CRM, a connector to another service, a data migration, a webhook handler, or an automation agent, and it generates the code, reviews and tests it, deploys it to an isolated cloud sandbox, and hands you a live HTTPS URL. This is different from the [Mihu MCP Server](/guides/mcp): that one operates your existing agents, contacts, and campaigns; the **Builder MCP** creates and runs brand-new apps for you. ## What the Builder MCP can do | Capability | Example tools | | ----------------------- | --------------------------------------------------------------------------- | | Describe & build an app | `create_agent`, `answer_agent`, `approve_agent`, `get_agent`, `list_agents` | | Ship your own code | `deploy_code`, `list_deployments`, `get_deployment_files` | | Quality & safety | `review_deployment`, `test_deployment`, `get_qa_report` | | Operate a running app | `start_deployment`, `stop_deployment`, `set_auto_stop`, `delete_deployment` | | Inspect & debug | `get_logs`, `exec_command`, `create_ssh`, `recreate_ssh`, `revoke_ssh` | | Files & secrets | `create_upload_link`, `store_credentials`, `list_credentials` | | Cost | `get_spending` | Every app runs in its own isolated sandbox with a public preview URL. Each connection is **bound to one tenant** and scoped to it — no other tenant is reachable. The table above is a summary, not the full list. The complete, always-current set of tools — with each tool's parameters, types, and description — is advertised by the server itself. ## See the full tool list You don't maintain this list by hand — MCP clients discover it automatically on connect: * **Claude Desktop / Claude Code / Cursor:** once the server is registered and connected, open the tools/connectors view (Claude Desktop: the **🔌 / tools** icon in the message box; Claude Code: `/mcp`). Every Builder MCP tool is listed there with its description. * **Any MCP client:** the server answers the standard MCP `tools/list` request — that response is the authoritative list, including each tool's JSON input schema. * **From a prompt:** just ask your client *"list the tools available from mihu-builder"* — it reads them from the connected server. Each tool's description includes its required fields, enums, and example shapes, readable by the model at call-time — no external tool reference to keep in sync. ## Get your connection details You get everything you need from the app. Open **Builder Mode** and go to the **Credentials** tab — the **Builder connection** panel there shows your three values: | Value | Where it comes from | | ---------- | --------------------------------------------------------------------------------- | | **Server** | The platform URL, e.g. `https://builder.mihu.ai` | | **Tenant** | Your workspace's builder tenant name | | **Token** | Your tenant key — masked by default; click the **eye icon** to reveal and copy it | The token is created automatically the first time you use the builder. You can roll it any time from the **Credentials** tab (**Recreate token**), or delete it to revoke access — a new one is minted automatically the next time a builder is used. Keep it secret: it authorizes everything for your tenant. ## Before you start Make sure you have: * access to your Mihu tenant, * an MCP-compatible client (Claude Desktop, Claude Code, Cursor, or a custom client), * Python with the MCP package installed: `pip install mcp`, * and your **Server**, **Tenant**, and **Token** from **Builder Mode → Credentials**. ## Run the server (stdio) Run `mcp_server.py` with your three values as environment variables: ```bash theme={null} MIHU_API_URL= \ MIHU_TENANT= \ MIHU_TENANT_KEY= \ python mcp_server.py ``` For example: ```bash theme={null} MIHU_API_URL=https://builder.mihu.ai \ MIHU_TENANT=acme \ MIHU_TENANT_KEY=acme_xxx \ python mcp_server.py ``` ## Connect from Claude Pick whichever fits you. Both end up giving Claude the builder tools. **Don't want to run a local script?** The core builder tools (`create_build`, `answer_build`, `approve_build`, `rebuild_build`, `list_builders`, `deploy_builder_code`, …) are also bridged into the **hosted Mihu MCP** at `mcp.mihu.ai`. If you connect that one — see the [Mihu MCP Server guide](/guides/mcp) — you get the builder tools alongside everything else, with **no local setup**. Use the standalone Builder MCP below when you want the full, dedicated builder toolset. ### Claude Desktop 1. Open **Settings → Developer → Edit Config**. 2. Add the `mihu-builder` server below, filling in your **Tenant** and **Token** from **Builder Mode → Credentials** and the absolute path to `mcp_server.py`. 3. Save and restart Claude Desktop. The builder tools then appear under the tools/🔌 icon. ```json theme={null} { "mcpServers": { "mihu-builder": { "command": "python", "args": ["/absolute/path/to/mcp_server.py"], "env": { "MIHU_API_URL": "https://builder.mihu.ai", "MIHU_TENANT": "", "MIHU_TENANT_KEY": "" } } } } ``` ### Claude Code Register it from the terminal with the same three values: ```bash theme={null} claude mcp add mihu-builder \ --env MIHU_API_URL=https://builder.mihu.ai \ --env MIHU_TENANT= \ --env MIHU_TENANT_KEY= \ -- python /absolute/path/to/mcp_server.py ``` Then run `/mcp` inside Claude Code to confirm `mihu-builder` is connected and see its tools. ## Build flow (asynchronous — poll after each write) Building is asynchronous, so always poll after a write: 1. **Describe it** — call `create_agent` with a one-sentence prompt. 2. **Poll** — call `get_agent` (\~every 2–3s) while `status: processing`. 3. **Answer questions** — while `status: gathering`, the builder asks what it needs (credentials, size, schedule); call `answer_agent` and keep polling. 4. **Approve** — when `status: awaiting_approval`, call `approve_agent` to build, deploy, and run automated checks (AI code review + tests). 5. **Live** — once `status: deployed`, the app is running with a preview URL. Operate it with `start_deployment` / `stop_deployment` / `get_logs` / `exec_command`, or ask for changes (the builder rebuilds the live app). You can also skip the conversation and ship your own files directly with `deploy_code`. ## Test the connection Try these once connected: * "List my builders." * "Build a small JSON API that stores and returns leads." * "Show the logs for my last deployment." ## Troubleshooting | Symptom | First check | | ---------------------------- | --------------------------------------------------------------------------------------- | | `401` from the platform | Wrong tenant or wrong/expired token — re-copy it from **Builder Mode → Credentials**. | | `403` / cannot see a builder | Each token is tied to one tenant. You only see that tenant's builders. | | Preview URL doesn't resolve | The builder is stopped — start it; a preview URL only resolves while running. | | Build keeps failing | Ask the builder to "try again" or "build a simpler version"; it self-heals and retries. | | Token leaked | Recreate it from the **Credentials** tab — the old one stops working immediately. | ## Support * **Platform:** [`https://builder.mihu.ai`](https://builder.mihu.ai) * **Status / health:** [`https://builder.mihu.ai/health`](https://builder.mihu.ai/health) → `{"status": "ok"}` * **Issues:** email [support@mihu.ai](mailto:support@mihu.ai) # Mihu MCP Server Source: https://developers.mihu.ai/guides/mcp Connect LLM clients to Mihu via the Model Context Protocol Use this guide to connect the Mihu MCP Server to your client and start using it safely. * **Endpoint:** `https://mcp.mihu.ai/mcp` * **Transport:** Streamable HTTP (MCP standard) * **Health:** [`https://mcp.mihu.ai/health`](https://mcp.mihu.ai/health) ## Before you start Make sure you have: * access to the target Mihu tenant (e.g. `your-tenant.mihu.ai`), * an MCP-compatible client (Claude Desktop, IDE agent, or custom MCP client), * and a Mihu API token from your tenant panel. ## Access model Each token is tied to **one Mihu tenant**. The token inherits the panel permissions of the API key it was minted from — your client cannot exceed them. The MCP server itself stores no credentials. | Property | Value | | ---------------------- | -------------------------------------------- | | Tenant binding | One token, one tenant subdomain | | Permissions | Inherited from the underlying Mihu API token | | OAuth access token TTL | 1 hour (re-mint as needed) | | Storage | In-memory on the server (not persisted) | ## Connect Mihu MCP Server There are two ways to authenticate. Pick whichever your client supports. ### Option A — OAuth 2.1 (recommended for Claude Desktop) ```text theme={null} Authorization Server : https://mcp.mihu.ai Token URL : https://mcp.mihu.ai/oauth/token Grant types : client_credentials, authorization_code (PKCE) client_id : client_secret : ``` Claude Desktop discovers the OAuth flow automatically — no manual register step. In **Settings → Connectors → Add custom connector**: | Field | Value | | ------------------- | ------------------------- | | URL | `https://mcp.mihu.ai/mcp` | | OAuth Client ID | your tenant subdomain | | OAuth Client Secret | your Mihu API token | ### Option B — Direct headers (for scripts / curl / custom clients) ```text theme={null} Authorization : Bearer X-Mihu-Tenant : ``` No token mint needed; tenant is set per request. ### Mint a token directly ```bash theme={null} curl -s -X POST https://mcp.mihu.ai/oauth/token \ -d grant_type=client_credentials \ -d client_id= \ -d client_secret= # → {"access_token":"...","token_type":"Bearer","expires_in":3600} ``` Then call MCP with `Authorization: Bearer `. ## Test the connection Try a few read-only prompts first: * "List my agents." * "How many contacts do we have?" * "Show conversations from the last 24 hours." ## First setup checks After you connect, confirm these basics: * You are connected to the expected tenant. * Read tools (`list_agents`, `list_contacts`) return data. * Your panel permissions allow the actions you plan to run. ## What it can do The server exposes 375 tools across 43 modules. Common capabilities: | Capability | Example tools | | ------------------- | --------------------------------------------------------------------------- | | Place real calls | `initiate_call`, `say_in_call`, `forward_call`, `mute_agent`, `hangup_call` | | Send SMS / WhatsApp | `send_sms`, `send_whatsapp_template`, `whatsapp_call` | | Manage agents | `list_agents`, `create_agent`, `add_agent_guideline`, `add_agent_intent` | | Bulk outbound | `create_listing`, `add_contacts_to_listing`, `run_listing`, `stop_listing` | | Contacts | `list_contacts`, `create_contact`, `update_contact`, `add_tag_to_contact` | | Appointments | `book_appointment`, `list_appointments`, `get_available_slots` | | Conversations | `list_conversations`, `get_conversation`, `get_session_evaluation` | | Phone numbers | `search_available_phone_numbers`, `provision_call_channel` | Each tool's description includes required fields, enums, and example shapes — readable by the LLM at call-time, no external docs needed. ## What to include in a prompt Include these details when relevant: * **Time range** — "last 7 days", "yesterday", "this month" * **Target** — an agent, campaign, contact, conversation, or schedule * **Output** — summary, ranking, comparison, trend, or draft * **Action boundary** — "prepare only", "show preview", or "do not send" ### Example prompt patterns **Analysis** * "Summarize agent performance for the last 7 days." * "Which campaigns drove the most completed calls last week?" * "Compare SMS vs WhatsApp delivery rates for the last 14 days." **Audience and contact investigation** * "Show recent conversations for contact +90555…" * "List appointments booked in the last 3 days." * "Which contacts have the `vip` tag?" **Operational requests** * "Initiate a call from agent X to +90555… with greeting 'Hi…'" * "Create a listing for these 50 leads under agent Y." * "Stop the active listing named 'Q2 outbound'." ## How write actions work Write actions follow the underlying Mihu API permissions of the token: * The token inherits exactly what your API key can do in the panel — nothing more. * Bulk operations (e.g. `create_listing` with thousands of contacts) are accepted, but the agent's channel binding and tenant rate limits still apply. * All actions are logged in the standard Mihu request logs for the tenant. ## Troubleshooting | Symptom | First check | | ------------------------------ | ------------------------------------------------------------------------ | | `401` from upstream | Wrong tenant or wrong/expired API token. | | `404` from upstream | Tenant subdomain typo — does `.mihu.ai` resolve? | | "Missing tenant context" error | Client didn't send `X-Mihu-Tenant`, or OAuth token expired (1-hour TTL). | | OAuth token expired | Re-mint at `/oauth/token`. Default TTL is 1 hour. | | Action blocked by permissions | Underlying Mihu API key lacks the permission — adjust in the panel. | | Cannot access another tenant | Each token is tied to one tenant. Mint a separate token per tenant. | ## Support * **Status / health:** [`https://mcp.mihu.ai/health`](https://mcp.mihu.ai/health) → `{"ok": true}` * **Issues:** email [support@mihu.ai](mailto:support@mihu.ai) # Campaign Management Source: https://developers.mihu.ai/guides/services/campaigns Create and manage multi-channel communication campaigns ## What are Campaigns? Campaigns allow you to orchestrate multi-channel communication at scale. Whether you're conducting surveys, sending reminders, or reaching out to leads, campaigns help you organize and automate your outreach. ## Campaign Types Automated outbound calling with AI agents Template-based WhatsApp broadcasts Multi-channel campaigns with sequential touchpoints Automated sequences with timing rules ## Creating a Campaign ### Via Dashboard Go to **Campaigns** in your Mihu dashboard Click **"Create Campaign"** button * Campaign name * Campaign type (Voice, WhatsApp, Mixed) * Description * Start and end dates * For voice: Choose an AI agent * For WhatsApp: Select message template * For mixed: Configure both * Upload contact list * Select from existing contacts * Apply filters and segments * Immediate or scheduled start * Time windows (e.g., 9 AM - 5 PM) * Timezone considerations * Pacing (calls per hour) Review settings and click **"Launch"** ### Via API Create campaigns programmatically: ```bash cURL theme={null} curl -X POST https://your-tenant.mihu.ai/api/v1/campaigns \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Survey Q1 2025", "type": "voice", "agentId": "agent-uuid-here", "contacts": [ {"number": "+1234567890", "name": "John Doe"}, {"number": "+0987654321", "name": "Jane Smith"} ], "schedule": { "startDate": "2025-01-20T09:00:00Z", "endDate": "2025-01-25T17:00:00Z", "timeWindows": [ {"start": "09:00", "end": "17:00", "timezone": "America/New_York"} ] }, "settings": { "maxCallsPerHour": 100, "retryFailed": true, "maxRetries": 2 } }' ``` ```javascript JavaScript theme={null} const createCampaign = async () => { const response = await fetch( 'https://your-tenant.mihu.ai/api/v1/campaigns', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Customer Survey Q1 2025', type: 'voice', agentId: 'agent-uuid-here', contacts: [ { number: '+1234567890', name: 'John Doe' }, { number: '+0987654321', name: 'Jane Smith' } ], schedule: { startDate: '2025-01-20T09:00:00Z', endDate: '2025-01-25T17:00:00Z', timeWindows: [ { start: '09:00', end: '17:00', timezone: 'America/New_York' } ] }, settings: { maxCallsPerHour: 100, retryFailed: true, maxRetries: 2 } }) } ); return await response.json(); }; ``` ```python Python theme={null} import requests url = "https://your-tenant.mihu.ai/api/v1/campaigns" headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } payload = { "name": "Customer Survey Q1 2025", "type": "voice", "agentId": "agent-uuid-here", "contacts": [ {"number": "+1234567890", "name": "John Doe"}, {"number": "+0987654321", "name": "Jane Smith"} ], "schedule": { "startDate": "2025-01-20T09:00:00Z", "endDate": "2025-01-25T17:00:00Z", "timeWindows": [ {"start": "09:00", "end": "17:00", "timezone": "America/New_York"} ] }, "settings": { "maxCallsPerHour": 100, "retryFailed": True, "maxRetries": 2 } } response = requests.post(url, headers=headers, json=payload) data = response.json() ``` ## Campaign Settings ### Scheduling Options When the campaign should begin contacting people. Can be immediate or scheduled for a future date/time. When the campaign should stop. All pending contacts will be marked as "not contacted" after this time. Specific hours when contacts can be reached (e.g., 9 AM - 5 PM). Respects recipient timezones. Control how many contacts are reached per hour to avoid overwhelming your team or systems. Automatically retry failed attempts with configurable retry count and delay. ### Advanced Settings | Setting | Description | Default | | --------------- | ----------------------------- | ------- | | Max Calls/Hour | Rate limit for outbound calls | 100 | | Retry Failed | Retry failed attempts | true | | Max Retries | Maximum retry attempts | 2 | | Retry Delay | Hours between retries | 2 | | Skip Duplicates | Skip duplicate phone numbers | true | | Respect DNC | Honor Do Not Call lists | true | ## Contact Management ### Adding Contacts Add contacts one by one through the dashboard interface. Upload a CSV file with contact information: ```csv theme={null} name,number,email,custom_field_1 John Doe,+1234567890,john@example.com,value1 Jane Smith,+0987654321,jane@example.com,value2 ``` Select contacts from your existing contact database with filters and segments. Add contacts programmatically when creating or updating campaigns. ### Contact Filters Filter contacts based on: * **Tags**: Contact tags and labels * **Custom Fields**: Any custom field values * **Previous Interactions**: Past campaign participation * **Status**: Active, inactive, opted-out * **Location**: Country, state, city * **Timezone**: Specific timezones ## Campaign Monitoring ### Real-time Dashboard Monitor campaign progress in real-time: * **Total Contacts**: Total contacts in campaign * **Contacted**: Successfully reached * **Pending**: Not yet contacted * **Failed**: Failed to reach * **Success Rate**: Percentage successfully contacted * **Progress**: Visual progress bar ### Live Activity Feed See contact-by-contact activity: ``` 2:15 PM - Called +1234567890 (John Doe) - Success - Duration: 3:45 2:14 PM - Called +0987654321 (Jane Smith) - No Answer - Retry scheduled 2:13 PM - Called +1122334455 (Bob Wilson) - Success - Duration: 2:30 ``` ### Webhooks for Campaign Events Receive real-time updates via webhooks: ```javascript Example Webhook theme={null} { "event": "campaign.contact.completed", "timestamp": "2025-01-15T14:15:00Z", "data": { "campaignId": "campaign-uuid", "contactNumber": "+1234567890", "contactName": "John Doe", "status": "success", "duration": 225, "callId": "call-uuid" } } ``` See [Webhooks Guide](/webhooks) for setup. ## Campaign Analytics ### Performance Metrics * **Contact Rate**: Percentage of contacts reached * **Answer Rate**: Percentage who answered (voice) * **Completion Rate**: Percentage who completed interaction * **Average Duration**: Mean interaction time * **Intent Distribution**: Common intents detected * **Sentiment Analysis**: Overall sentiment breakdown ### Reports Generate detailed reports: 1. Go to **Campaigns** → Select campaign 2. Click **"Analytics"** tab 3. Choose metrics and date range 4. **Export** as CSV or PDF ### A/B Testing Test different approaches: * **Split Test**: Divide contacts into groups * **Agent Variations**: Test different agent prompts * **Template Variations**: Test different messages * **Timing**: Test different time windows * **Compare Results**: Analyze which performs better ## Campaign Types in Detail ### Voice Campaigns Automated calling campaigns with AI agents: **Best for:** * Customer surveys * Appointment reminders * Lead qualification * Debt collection * Emergency notifications **Configuration:** * Select AI agent * Set call windows * Define success criteria * Configure retry logic ### WhatsApp Campaigns Template-based messaging campaigns: **Best for:** * Order confirmations * Shipping updates * Appointment reminders * Marketing promotions * Customer notifications **Requirements:** * Approved WhatsApp templates * Valid phone numbers * Opt-in consent ### Drip Campaigns Multi-touch sequences over time: **Example Flow:** ``` Day 1: Send WhatsApp message Day 3: Make voice call if no response Day 7: Send follow-up WhatsApp Day 14: Final voice call attempt ``` **Configuration:** * Define sequence steps * Set delays between steps * Configure triggers and conditions * Handle responses ## Best Practices * Group contacts by relevant criteria * Personalize messaging for each segment * Test different approaches per segment * Track segment-specific performance * Call during business hours * Consider recipient timezones * Avoid holidays and weekends (unless appropriate) * Test different time windows * Watch real-time metrics * Pause if issues arise * Adjust pacing as needed * Iterate based on results * Honor Do Not Call lists * Process opt-out requests immediately * Maintain unsubscribe lists * Comply with regulations * Test with small sample first * Verify agent/template works correctly * Check contact data quality * Confirm scheduling is correct ## Managing Active Campaigns ### Pausing a Campaign ```bash theme={null} curl -X PATCH https://your-tenant.mihu.ai/api/v1/campaigns/{id} \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"status": "paused"}' ``` ### Resuming a Campaign ```bash theme={null} curl -X PATCH https://your-tenant.mihu.ai/api/v1/campaigns/{id} \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"status": "active"}' ``` ### Stopping a Campaign ```bash theme={null} curl -X PATCH https://your-tenant.mihu.ai/api/v1/campaigns/{id} \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"status": "stopped"}' ``` ## Compliance ### Regulations * **TCPA**: Telephone Consumer Protection Act (US) * **GDPR**: General Data Protection Regulation (EU) * **CASL**: Canadian Anti-Spam Legislation * **DNC Lists**: Do Not Call registries ### Best Practices ✅ **Do:** * Get explicit consent * Provide opt-out options * Honor opt-out requests * Respect calling hours * Maintain DNC lists ❌ **Don't:** * Call without consent * Ignore opt-out requests * Call outside permitted hours * Use misleading caller ID * Harass contacts ## Troubleshooting ### Low Contact Rate **Possible causes:** * Poor contact data quality * Calling outside business hours * Phone numbers invalid/disconnected * Agent issues **Solutions:** * Validate contact data * Adjust time windows * Review agent configuration * Test with known-good numbers ### High Failure Rate **Possible causes:** * Technical issues * Rate limiting * Invalid agent configuration * Network problems **Solutions:** * Check campaign logs * Reduce pacing * Verify agent settings * Contact support ## Next Steps Create AI agents for campaigns Set up WhatsApp messaging Manage your contact database View campaign API endpoints # Contact Management Source: https://developers.mihu.ai/guides/services/contacts Organize and manage your contact database with custom fields and segmentation ## Contact Database The Mihu contact database is your centralized repository for managing customer information. Store contact details, track interaction history, and segment audiences for targeted campaigns. ## Key Features Define unlimited custom fields for your specific needs Organize contacts with tags for easy filtering Upload and download contacts in CSV format Automatic detection and merging of duplicates ## Creating Contacts ### Via Dashboard Go to **Contacts** in your Mihu dashboard Click **"Add Contact"** button * Name (required) * Phone number (required, E.164 format) * Email (optional) * Custom fields * Tags Click **"Save"** to add to database ### Via API Create contacts programmatically: ```bash cURL theme={null} curl -X POST https://your-tenant.mihu.ai/api/v1/contacts \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "John Doe", "phone": "+1234567890", "email": "john@example.com", "customFields": { "company": "Acme Corp", "role": "Manager", "industry": "Technology" }, "tags": ["vip", "enterprise"], "timezone": "America/New_York", "language": "en" }' ``` ```javascript JavaScript theme={null} const createContact = async () => { const response = await fetch( 'https://your-tenant.mihu.ai/api/v1/contacts', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'John Doe', phone: '+1234567890', email: 'john@example.com', customFields: { company: 'Acme Corp', role: 'Manager', industry: 'Technology' }, tags: ['vip', 'enterprise'], timezone: 'America/New_York', language: 'en' }) } ); return await response.json(); }; ``` ```python Python theme={null} import requests url = "https://your-tenant.mihu.ai/api/v1/contacts" headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } payload = { "name": "John Doe", "phone": "+1234567890", "email": "john@example.com", "customFields": { "company": "Acme Corp", "role": "Manager", "industry": "Technology" }, "tags": ["vip", "enterprise"], "timezone": "America/New_York", "language": "en" } response = requests.post(url, headers=headers, json=payload) data = response.json() ``` ## Bulk Import ### CSV Upload Import multiple contacts at once using CSV: **CSV Format:** ```csv theme={null} name,phone,email,company,role,tags John Doe,+1234567890,john@example.com,Acme Corp,Manager,"vip,enterprise" Jane Smith,+0987654321,jane@example.com,Tech Inc,Director,"vip" Bob Wilson,+1122334455,bob@example.com,StartupCo,Founder,"startup,tech" ``` **Import Steps:** Create CSV with required fields: name, phone Go to Contacts → Click **"Import"** → Select CSV file Map CSV columns to contact fields Preview data and click **"Import"** **Requirements:** * Phone numbers must be in E.164 format (+1234567890) * Maximum 10,000 contacts per import * File size limit: 5 MB ### Handling Duplicates During import, duplicates are detected by phone number: * **Skip**: Don't import duplicates * **Update**: Update existing contacts with new data * **Create New**: Import as separate contacts ## Custom Fields Define custom fields to store business-specific information. ### Creating Custom Fields 1. Go to **Settings** → **Custom Fields** 2. Click **"Add Field"** 3. Configure field: * Name * Type (text, number, date, dropdown) * Required or optional * Default value 4. Save Custom fields are defined per contact in the `customFields` object. ### Field Types | Type | Description | Example | | -------- | ------------------ | ----------------------- | | Text | Free-form text | Company name, notes | | Number | Numeric values | Revenue, employee count | | Date | Date values | Birthday, contract date | | Dropdown | Predefined options | Industry, status | | Boolean | True/false | VIP status, opted-in | | URL | Website links | Company website | ### Common Custom Fields **B2B:** * Company name * Job title * Industry * Company size * Annual revenue **B2C:** * Age/Birthday * Gender * Interests * Purchase history * Loyalty tier **General:** * Lead source * Lead score * Last interaction date * Notes * Preferred contact method ## Tags & Segmentation ### Using Tags Tags help organize and filter contacts: ```javascript Example Tags theme={null} { "name": "John Doe", "tags": [ "vip", "enterprise", "q1-2025", "product-interested" ] } ``` **Common Tag Categories:** * **Customer Type**: vip, enterprise, sme, individual * **Status**: active, inactive, churned, prospect * **Source**: website, referral, event, advertisement * **Interest**: product-a, product-b, service-x * **Campaign**: q1-campaign, webinar-attendee ### Creating Segments Segments are saved filters for quick access: **Example Segments:** 1. **VIP Customers** * Tag: vip * Last interaction: \< 30 days * Status: active 2. **Inactive Leads** * Status: prospect * Last interaction: > 90 days * Tag: !converted 3. **Enterprise Prospects** * Custom field: company\_size > 1000 * Tag: enterprise * Status: prospect ## Contact History View complete interaction history for each contact: * **Calls**: All voice calls with durations and outcomes * **Messages**: WhatsApp and SMS history * **Campaigns**: Campaign participation * **Notes**: Manual notes added by team * **Timeline**: Chronological activity feed ### Example History ``` Jan 15, 2025 - Voice Call - 3:45 duration - Survey completed Jan 10, 2025 - WhatsApp - Order confirmation sent Jan 5, 2025 - Campaign - Added to Q1 Survey campaign Dec 20, 2024 - Voice Call - 2:30 duration - Appointment scheduled Dec 15, 2024 - Note - "Customer interested in enterprise plan" ``` ## Searching & Filtering ### Quick Search Search contacts by: * Name * Phone number * Email * Custom field values ### Advanced Filters Apply multiple filters: ```javascript Example Filter theme={null} { "filters": { "tags": ["vip", "enterprise"], "status": "active", "customFields": { "industry": "Technology", "revenue": { "$gte": 1000000 } }, "lastInteraction": { "$gte": "2025-01-01", "$lte": "2025-01-31" } } } ``` **Filter Operators:** * `$eq`: Equals * `$ne`: Not equals * `$gt`: Greater than * `$gte`: Greater than or equal * `$lt`: Less than * `$lte`: Less than or equal * `$in`: In array * `$nin`: Not in array ## Privacy & Compliance ### Opt-Out Management Manage contact preferences: * **Do Not Call**: Contact cannot be called * **Do Not Message**: Contact cannot receive messages * **Opted Out**: Completely opted out of all communication **Setting Opt-Out:** ```javascript theme={null} { "phone": "+1234567890", "preferences": { "doNotCall": true, "doNotMessage": false, "optedOut": false } } ``` ### GDPR Compliance Support for GDPR requirements: * **Right to Access**: Export contact data * **Right to Deletion**: Delete contact and all data * **Right to Rectification**: Update contact information * **Consent Management**: Track consent status **Deleting Contact Data:** ```bash theme={null} curl -X DELETE https://your-tenant.mihu.ai/api/v1/contacts/{id} \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ## Deduplication Mihu automatically detects duplicate contacts based on: * Phone number (primary key) * Email address * Name + similar phone ### Merging Duplicates When duplicates are detected: 1. Review suggested merges 2. Select which data to keep 3. Merge contacts 4. Update campaign assignments **Merge Strategy:** * Keep most recent data * Combine tags from both * Merge custom fields * Preserve all history ## Exporting Contacts Export contacts for analysis or backup: ### Export Options 1. Go to **Contacts** 2. Apply filters (optional) 3. Click **"Export"** 4. Choose CSV or Excel 5. Download file ```bash theme={null} curl -X GET "https://your-tenant.mihu.ai/api/v1/contacts?limit=1000" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` **Exported Data Includes:** * All standard fields * Custom fields * Tags * Creation and update dates * Opt-out preferences ## Best Practices * Regularly review and update contacts * Remove or archive inactive contacts * Merge duplicates promptly * Validate phone numbers and emails * Define fields that provide value * Keep field names consistent * Don't create too many fields * Document field purposes * Use consistent naming convention * Create tag categories * Remove outdated tags * Don't over-tag contacts * Create meaningful segments * Use segments for targeted campaigns * Update segments regularly * Test segment performance * Honor opt-out requests immediately * Comply with GDPR and privacy laws * Secure sensitive data * Document consent ## Integration with Other Features ### Campaigns Use contacts in campaigns: * Select specific contacts * Apply segment filters * Import campaign-specific lists * Track campaign participation ### Voice Agents Contacts are automatically: * Called by AI agents in campaigns * Associated with call transcriptions * Updated with call outcomes * Tracked in contact history ### WhatsApp Send messages to contacts: * Use contact database for broadcasts * Track message delivery status * Handle replies automatically * Update contact preferences ## API Operations ### List Contacts ```bash theme={null} GET /api/v1/contacts?page=1&limit=50&tags=vip&status=active ``` ### Get Contact ```bash theme={null} GET /api/v1/contacts/{id} ``` ### Update Contact ```bash theme={null} PATCH /api/v1/contacts/{id} Content-Type: application/json { "tags": ["vip", "q1-2025"], "customFields": { "last_purchase": "2025-01-15" } } ``` ### Delete Contact ```bash theme={null} DELETE /api/v1/contacts/{id} ``` See [API Reference](/api-reference) for complete documentation. ## Troubleshooting ### Import Failed **Common issues:** * Invalid phone number format (use E.164: +1234567890) * Duplicate entries in CSV * File size too large (max 5 MB) * Invalid CSV format **Solution:** Validate data, fix formatting, split large files. ### Duplicate Contacts **Causes:** * Multiple imports without deduplication * Slightly different phone numbers * API creates without checking **Solution:** Use deduplication tools, merge duplicates. ### Custom Field Not Showing **Causes:** * Field not created * Permission issue * Cache issue **Solution:** Create field in settings, refresh page. ## Next Steps Create campaigns with your contacts Set up AI agents to call contacts Send WhatsApp messages to contacts View contact API endpoints # Services Overview Source: https://developers.mihu.ai/guides/services/overview Overview of Mihu platform services and capabilities ## Mihu Platform Services Mihu provides a comprehensive suite of AI-powered communication services designed to help you build intelligent, scalable conversation experiences across multiple channels. ## Core Services Create intelligent voice agents that can conduct natural phone conversations Send automated WhatsApp messages using pre-approved templates Orchestrate multi-channel campaigns with intelligent scheduling and targeting Organize and manage your contact database with custom fields and segmentation ## Platform Capabilities ### AI Voice Agents Mihu's AI voice agents enable you to conduct natural, context-aware conversations at scale. Each agent can be customized with: * **Custom Prompts**: Define agent behavior and conversation flow * **Voice Selection**: Choose from multiple voice options * **Language Support**: Support for multiple languages and accents * **Intent Detection**: Automatic detection of user intents during conversations * **Sentiment Analysis**: Real-time sentiment tracking * **Call Recording**: Automatic recording and transcription **Use Cases:** * Customer support and help desk automation * Appointment scheduling and reminders * Survey collection and feedback gathering * Lead qualification and sales outreach * Payment reminders and collections ### WhatsApp Messaging Integrate WhatsApp Business API to send template-based messages: * **Pre-approved Templates**: Use WhatsApp-approved message templates * **Dynamic Parameters**: Personalize messages with customer data * **Rich Media**: Send images, documents, and interactive buttons * **Two-way Conversations**: Handle incoming messages and responses * **Delivery Tracking**: Track message delivery and read receipts **Use Cases:** * Order confirmations and shipping updates * Appointment reminders * Customer notifications * Marketing campaigns * Customer support ### Campaign Management Create and manage sophisticated multi-channel campaigns: * **Multi-channel Support**: Voice, WhatsApp, and more * **Smart Scheduling**: Schedule campaigns with optimal timing * **Audience Segmentation**: Target specific customer segments * **A/B Testing**: Test different message variations * **Performance Analytics**: Track campaign metrics and ROI * **Automated Follow-ups**: Set up automatic follow-up sequences **Campaign Types:** * Outbound calling campaigns * WhatsApp broadcast campaigns * Drip campaigns with multiple touchpoints * Re-engagement campaigns * Seasonal and promotional campaigns ### Contact Management Organize your contact database efficiently: * **Custom Fields**: Define custom attributes for your contacts * **Tags and Labels**: Organize contacts with tags * **Import/Export**: Bulk import and export contact data * **Deduplication**: Automatic duplicate detection * **Timezone Support**: Store contact timezone preferences * **Contact History**: View complete interaction history * **GDPR Compliance**: Privacy controls and data management ## Service Integration All Mihu services work seamlessly together: ```mermaid theme={null} graph LR A[Contacts] --> B[Campaigns] B --> C[Voice Agents] B --> D[WhatsApp] C --> E[Transcriptions] C --> F[Analytics] D --> F E --> F ``` ### Example Workflow 1. **Import Contacts**: Upload your contact list 2. **Create Campaign**: Design a multi-touch campaign 3. **Configure Agent**: Set up AI agent with custom prompts 4. **Launch Campaign**: Start reaching out to contacts 5. **Monitor Results**: Track performance in real-time 6. **Analyze Data**: Review transcriptions and analytics 7. **Optimize**: Refine based on insights ## Developer Tools ### Webhooks Receive real-time notifications about: * Conversation updates and completions * Campaign status changes * Intent detections * Message deliveries * Custom events See the [Webhooks Guide](/webhooks) for setup instructions. ### API Access Full programmatic access to all platform features: * Initiate calls and send messages * Manage campaigns and contacts * Retrieve transcriptions and analytics * Configure agents and settings Explore the [API Reference](/api-reference) for complete documentation. ### Monitoring & Logs Track and debug all API interactions: * Request/response logs * Webhook delivery logs * Performance metrics * Error tracking Learn more in the [Monitoring Guide](/monitoring). ## Service Limits Understanding service limits helps you plan your usage: | Service | Limit | Notes | | --------------------- | ----------- | ---------------------------- | | API Requests | 1000/minute | Per workspace | | Concurrent Calls | 50 | Simultaneous active calls | | Webhook Events | 100/second | Event delivery rate | | Campaign Contacts | Unlimited | No contact limit | | Contact Custom Fields | 50 | Per contact | | Message Templates | Unlimited | Subject to WhatsApp approval | Need higher limits? Contact [support@mihu.ai](mailto:support@mihu.ai) to discuss enterprise plans. ## Security & Compliance Mihu takes security seriously: * **Data Encryption**: All data encrypted in transit and at rest * **SOC 2 Compliance**: Regular security audits * **GDPR Compliant**: Full GDPR compliance and data controls * **ISO 27001**: Information security management * **Privacy Controls**: Customer data privacy and consent management ## Getting Help Explore all available API endpoints Set up real-time event notifications Track API usage and debug issues Email [support@mihu.ai](mailto:support@mihu.ai) for assistance ## Next Steps Explore how to create and configure AI voice agents Connect your WhatsApp Business account Launch a multi-channel campaign Receive real-time notifications # AI Voice Agents Source: https://developers.mihu.ai/guides/services/voice-agents Create and manage intelligent AI voice agents for automated phone conversations ## What are AI Voice Agents? AI Voice Agents are intelligent conversational AI systems that can conduct natural phone conversations with your customers. They can understand speech, respond contextually, detect intents, and complete tasks autonomously. ## Key Features Engage in human-like conversations with context awareness Automatically detect and act on user intents Support for multiple languages and accents Live transcription and sentiment analysis ## Creating Your First Agent ### Step 1: Access Agent Configuration 1. Log in to your Mihu dashboard at `https://your-tenant.mihu.ai` 2. Navigate to **Agents** in the main menu 3. Click **"Create New Agent"** ### Step 2: Configure Basic Settings Give your agent a descriptive name (e.g., "Customer Support Agent", "Appointment Scheduler") Choose from multiple voice options: * **Gender**: Male, Female, Neutral * **Accent**: US, UK, Australian, etc. * **Tone**: Professional, Friendly, Formal Select the primary language for conversations: * English (US, UK, Australian) * Spanish * French * German * And more... ### Step 3: Define Agent Behavior The agent prompt defines how your AI behaves during conversations. **Example Prompts:** ```text Customer Support Agent theme={null} You are a helpful customer support agent for Acme Corporation. Your role: - Greet customers warmly - Listen to their concerns - Provide accurate information about products and services - Escalate complex issues to human agents when needed Guidelines: - Be polite and professional - Ask clarifying questions - Confirm understanding before taking action - Thank customers for their time If you cannot help, say: "Let me connect you with a specialist who can better assist you." ``` ```text Appointment Scheduler theme={null} You are an appointment scheduling assistant. Your role: - Confirm the customer's identity - Check their availability - Schedule appointments for available time slots - Send confirmation details Available time slots: - Monday-Friday: 9 AM - 5 PM - Appointments are 30 minutes long Process: 1. Greet and confirm customer name 2. Ask about preferred date and time 3. Check availability 4. Confirm appointment details 5. Provide confirmation number ``` ```text Survey Collector theme={null} You are conducting a customer satisfaction survey. Ask these questions in order: 1. On a scale of 1-10, how satisfied are you with our service? 2. What did you like most about your experience? 3. What could we improve? 4. Would you recommend us to others? Guidelines: - Be friendly and conversational - Thank them for each response - Don't rush through questions - End with appreciation for their time ``` ### Step 4: Configure Intent Detection Intents are specific actions or goals users express during conversations. **Common Intents:** | Intent | Description | Example Phrases | | ------------------- | --------------------------------- | -------------------------------------------- | | transfer\_to\_human | User wants to speak with a person | "Can I talk to someone?", "I need a human" | | request\_callback | User wants a callback | "Call me back", "Can someone call me later?" | | billing\_inquiry | Questions about billing | "Check my bill", "Payment question" | | cancel\_service | User wants to cancel | "Cancel my subscription", "Stop service" | | technical\_support | Technical help needed | "It's not working", "Technical issue" | **Setting up Intents:** 1. Go to Agent Settings → **Intents** 2. Click **"Add Intent"** 3. Define: * Intent name * Trigger phrases * Action to take (trigger webhook, transfer call, etc.) ### Step 5: Test Your Agent Before deploying, test your agent: 1. Click **"Test Agent"** in the dashboard 2. Call the test number provided 3. Have a conversation 4. Review the transcription 5. Refine prompts and settings as needed ## Using Agents via API Once your agent is created, you can initiate calls programmatically: ```bash cURL theme={null} curl -X POST https://your-tenant.mihu.ai/api/v1/call \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agentId": "550e8400-e29b-41d4-a716-446655440000", "participant": { "number": "+1234567890", "name": "John Doe" }, "greetingMessage": "Hello! This is a call from Acme Corp." }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://your-tenant.mihu.ai/api/v1/call', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ agentId: '550e8400-e29b-41d4-a716-446655440000', participant: { number: '+1234567890', name: 'John Doe' }, greetingMessage: 'Hello! This is a call from Acme Corp.' }) }); const data = await response.json(); console.log('Call initiated:', data.data.id); ``` ```python Python theme={null} import requests url = "https://your-tenant.mihu.ai/api/v1/call" headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } payload = { "agentId": "550e8400-e29b-41d4-a716-446655440000", "participant": { "number": "+1234567890", "name": "John Doe" }, "greetingMessage": "Hello! This is a call from Acme Corp." } response = requests.post(url, headers=headers, json=payload) call_data = response.json() print(f"Call initiated: {call_data['data']['id']}") ``` ## Agent Analytics Track agent performance in real-time: ### Available Metrics * **Total Calls**: Number of calls handled * **Average Duration**: Mean call length * **Success Rate**: Percentage of successful completions * **Intent Detection**: Most common intents triggered * **Sentiment Analysis**: Overall sentiment distribution * **Transcription Quality**: Speech recognition accuracy ### Viewing Analytics 1. Go to **Agents** → Select your agent 2. Click **"Analytics"** tab 3. Choose date range 4. Export data as needed ## Best Practices * Be specific about agent's role and capabilities * Include example responses * Define boundaries (what agent should NOT do) * Use bullet points for clarity * Test with various conversation scenarios * Include edge cases and unusual requests * Test with different accents and speech patterns * Review transcriptions for accuracy * Always provide a path to human assistance * Set up transfer intents * Configure callback options * Train agents when to escalate * Review transcriptions regularly * Track success and failure rates * Identify common issues * Iterate on prompts based on data * Don't collect unnecessary personal information * Inform users they're speaking with AI * Comply with recording consent laws * Follow GDPR and data privacy regulations ## Common Use Cases ### Customer Support ```text Agent Prompt theme={null} You are a customer support agent for [Company Name]. Capabilities: - Answer questions about products and services - Help with account issues - Process refund requests - Schedule callbacks If customer needs: - Password reset → Guide them to reset link - Refund → Collect order number and reason - Technical issue → Transfer to tech support - Billing question → Verify account and provide info Always be patient, empathetic, and helpful. ``` ### Appointment Scheduling ```text Agent Prompt theme={null} You are an appointment booking assistant for [Business Name]. Process: 1. Greet customer: "Hello! I can help you schedule an appointment." 2. Confirm their name and phone number 3. Ask for preferred date and time 4. Check availability (Mon-Fri, 9 AM-5 PM) 5. Confirm appointment details 6. Provide confirmation number If slot unavailable, offer 2-3 alternatives. If they need to reschedule, collect existing appointment details first. ``` ### Lead Qualification ```text Agent Prompt theme={null} You are a sales qualification assistant. Your goal: Qualify leads by gathering information. Questions to ask: 1. What product/service are you interested in? 2. What's your timeline for making a decision? 3. What's your budget range? 4. Who else is involved in the decision? Based on answers: - High priority: Budget >$10k, timeline <30 days → Schedule demo - Medium priority: Budget $5-10k → Send information packet - Low priority: Just researching → Add to newsletter Be conversational, not interrogative. ``` ## Troubleshooting ### Agent Not Responding * Check agent is activated * Verify phone number format (E.164) * Check API token is valid * Review error logs in dashboard ### Poor Transcription Quality * Ensure good audio quality * Check for background noise * Verify language setting matches caller * Test with different voice options ### Intent Not Detecting * Add more trigger phrases * Make phrases more specific * Test intent configuration * Review transcriptions for actual phrases used ## Next Steps See full API documentation Get real-time conversation updates Create agent-powered campaigns Track agent performance # WhatsApp Messaging Source: https://developers.mihu.ai/guides/services/whatsapp Send automated WhatsApp messages using pre-approved templates ## WhatsApp Business API Mihu integrates with WhatsApp Business API to enable automated messaging at scale. Send notifications, confirmations, and updates directly to your customers' WhatsApp. ## Prerequisites Before you can send WhatsApp messages, you need: Set up a WhatsApp Business account through Meta Create and get approval for message templates Link your WhatsApp Business account in Mihu dashboard ## Message Templates WhatsApp requires pre-approved templates for outbound messages. Templates ensure compliance with WhatsApp policies and prevent spam. ### Template Structure A template consists of: * **Template Name**: Unique identifier * **Language**: Message language code * **Category**: Marketing, Utility, or Authentication * **Content**: Header, body, footer, and buttons * **Parameters**: Dynamic placeholders for personalization ### Template Example ```text theme={null} Template Name: appointment_reminder Category: Utility Language: en Header: Your Appointment Reminder Body: Hi {{1}}, this is a reminder for your appointment on {{2}} at {{3}}. Reply CONFIRM to confirm or CANCEL to reschedule. Footer: Powered by Acme Corp Buttons: [Quick Reply: CONFIRM] [Quick Reply: CANCEL] ``` ### Creating Templates 1. Log in to Mihu dashboard 2. Go to **WhatsApp** → **Templates** 3. Click **"Create Template"** 4. Fill in template details 5. Submit for WhatsApp approval 6. Wait for approval (usually 24-48 hours) 1. Log in to Meta Business Manager 2. Navigate to WhatsApp Manager 3. Go to **Message Templates** 4. Create and submit templates 5. Once approved, they'll appear in Mihu ### Template Categories | Category | Purpose | Example Use Cases | | ------------------ | -------------------- | ------------------------------------------------ | | **Marketing** | Promotional messages | Sales, offers, newsletters | | **Utility** | Transaction updates | Order confirmations, shipping updates, reminders | | **Authentication** | Verification codes | OTP, password resets, login codes | Marketing templates have more restrictions and may have lower delivery rates. Use Utility or Authentication categories when possible. ## Sending Messages via API Once your templates are approved, you can send messages programmatically. ### Basic Example ```bash cURL theme={null} curl -X POST https://your-tenant.mihu.ai/api/v1/whatsapp/template \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agentId": "agent-uuid-here", "templateId": "template-uuid-here", "participant": { "number": "+1234567890", "name": "John Doe" }, "parameters": ["John", "March 15", "2:00 PM"] }' ``` ```javascript JavaScript theme={null} const sendWhatsAppMessage = async () => { const response = await fetch( 'https://your-tenant.mihu.ai/api/v1/whatsapp/template', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ agentId: 'agent-uuid-here', templateId: 'template-uuid-here', participant: { number: '+1234567890', name: 'John Doe' }, parameters: ['John', 'March 15', '2:00 PM'] }) } ); const data = await response.json(); return data; }; ``` ```python Python theme={null} import requests url = "https://your-tenant.mihu.ai/api/v1/whatsapp/template" headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } payload = { "agentId": "agent-uuid-here", "templateId": "template-uuid-here", "participant": { "number": "+1234567890", "name": "John Doe" }, "parameters": ["John", "March 15", "2:00 PM"] } response = requests.post(url, headers=headers, json=payload) data = response.json() ``` ### With Media Send templates with images or documents: ```javascript theme={null} { "agentId": "agent-uuid-here", "templateId": "template-uuid-here", "participant": { "number": "+1234567890" }, "parameters": ["John Doe", "ORD-12345"], "media": { "type": "image", "url": "https://example.com/invoice.jpg" } } ``` ## Use Cases ### Order Confirmations ```text Template theme={null} Name: order_confirmation Category: Utility Hi {{1}}! Your order #{{2}} has been confirmed. Total: ${{3}} Expected delivery: {{4}} Track your order: {{5}} Thank you for shopping with us! ``` ### Appointment Reminders ```text Template theme={null} Name: appointment_reminder Category: Utility Hello {{1}}, Reminder: You have an appointment on {{2}} at {{3}}. Location: {{4}} Reply CONFIRM to confirm or CANCEL to reschedule. ``` ### Shipping Updates ```text Template theme={null} Name: shipping_update Category: Utility Great news {{1}}! Your order #{{2}} has shipped. Tracking: {{3}} Estimated delivery: {{4}} Track shipment: {{5}} ``` ### Payment Reminders ```text Template theme={null} Name: payment_reminder Category: Utility Hi {{1}}, Your payment of ${{2}} is due on {{3}}. Pay now: {{4}} Questions? Reply to this message. ``` ## Best Practices * Submit templates for approval before you need them * Allow 24-48 hours for approval * Have backup templates ready * Keep rejected templates for reference * Use customer names * Include relevant order/account details * Make messages specific to the recipient * Avoid generic broadcasts * Honor customer preferences * Provide easy opt-out options * Don't message opted-out contacts * Keep unsubscribe list updated * Send messages during business hours * Consider recipient's timezone * Don't send too frequently * Space out campaigns appropriately * Track delivery and read rates * Monitor for failed deliveries * Check template performance * Optimize based on metrics ## Template Approval Tips To get templates approved faster: ✅ **Do:** * Be clear and concise * Use proper grammar and spelling * Include opt-out instructions for marketing * Follow WhatsApp policies * Provide value to recipients ❌ **Don't:** * Use all caps * Include misleading content * Make false claims * Use excessive emojis * Violate WhatsApp policies ## Handling Responses ### Receiving Replies When customers reply to your messages, you can handle them via webhooks: ```javascript Webhook Example theme={null} { "event": "whatsapp.message.received", "timestamp": "2025-01-15T10:30:00Z", "data": { "from": "+1234567890", "message": "CONFIRM", "conversationId": "conv-uuid", "templateId": "template-uuid" } } ``` Set up webhooks to receive and process customer responses. See the [Webhooks Guide](/webhooks) for details. ## Compliance ### WhatsApp Policies * **24-hour Window**: After customer initiates, you have 24 hours to send free-form messages * **Templates Required**: Outside 24-hour window, use approved templates * **Opt-in Required**: Customers must opt-in to receive messages * **Quality Rating**: Maintain high quality rating to avoid limits ### Data Privacy * Comply with GDPR and local privacy laws * Get explicit consent before messaging * Provide clear opt-out mechanisms * Protect customer data * Don't share data with third parties ## Troubleshooting ### Template Rejected **Common reasons:** * Policy violation * Grammatical errors * Misleading content * Missing required elements * Inappropriate content **Solution:** Review WhatsApp guidelines, revise template, resubmit. ### Message Not Delivered **Possible causes:** * Invalid phone number * User blocked business * Template not approved * Rate limits exceeded * Opt-out list **Solution:** Check logs, verify number format, review opt-out status. ### Parameters Not Replacing **Possible causes:** * Wrong parameter order * Incorrect parameter count * Type mismatch **Solution:** Ensure parameter array matches template placeholders exactly. ## Monitoring & Analytics Track WhatsApp message performance: ### Available Metrics * **Sent**: Total messages sent * **Delivered**: Successfully delivered * **Read**: Messages read by recipient * **Failed**: Delivery failures * **Response Rate**: Percentage of replies ### Viewing Stats 1. Go to **WhatsApp** → **Analytics** 2. Select date range 3. Filter by template 4. Export data as needed ## Rate Limits WhatsApp has quality-based rate limits: | Quality Rating | Daily Message Limit | | -------------- | ------------------- | | High | 100,000 messages | | Medium | 10,000 messages | | Low | 1,000 messages | Maintain high quality by: * Sending relevant messages * Honoring opt-outs * Using approved templates * Avoiding spam reports ## Next Steps View complete WhatsApp API docs Handle incoming messages Create WhatsApp campaigns Track message performance # Introduction Source: https://developers.mihu.ai/introduction Welcome to Mihu API Documentation - Build powerful AI-driven voice and text conversations ## Welcome to Mihu Mihu is an advanced AI agent platform that enables you to create intelligent voice and text conversations at scale. Whether you're building automated customer support, conducting surveys, or creating interactive voice response systems, Mihu provides the tools you need to deliver exceptional conversational experiences. ## What is Mihu? Mihu empowers developers to integrate AI-powered communication capabilities into their applications. Our platform handles the complexity of natural language processing, voice synthesis, and conversation management, allowing you to focus on building great experiences for your users. ## Key Features Initiate intelligent outbound calls with customizable AI agents that can handle complex conversations naturally. Send automated WhatsApp messages using pre-approved templates with dynamic content. Create and manage multi-channel campaigns with sophisticated targeting and scheduling. Organize and segment contacts with custom fields, tags, and preferences. Receive instant notifications about conversation updates, completions, and custom intents. Access detailed conversation transcripts with sentiment analysis and intent detection. ## Core Capabilities ### Intelligent Voice Conversations Create AI agents that can conduct natural, context-aware voice conversations. Our platform supports: * Custom greeting messages and conversation flows * Real-time conversation handling * Automatic transcription and analysis * Support for multiple languages and accents ### Multi-Channel Communication Reach your audience across multiple channels: * **Voice Calls**: Outbound and inbound voice calls with AI agents * **WhatsApp**: Template-based messaging with dynamic content * **Web Calls**: Browser-based voice interactions ### Advanced Analytics Gain insights into every conversation: * Full conversation transcripts * Sentiment analysis * Intent detection * Call quality metrics * Campaign performance tracking ## Getting Started Ready to build with Mihu? Follow these steps: [Set up your API authentication](/authentication) to get your API token and tenant information. Follow our [quickstart guide](/quickstart) to make your first API call in minutes. Browse our [API reference](/api-reference) to discover all available endpoints and capabilities. Set up [webhooks](/webhooks) to receive real-time updates about your conversations. ## API Overview The Mihu API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. **Base URL Format:** ``` https://{subdomain}.mihu.ai ``` Replace `{subdomain}` with your workspace tenant identifier. ## Support Need help? We're here for you: * **Documentation**: Browse our comprehensive guides and API reference * **Email Support**: Reach out to [support@mihu.ai](mailto:support@mihu.ai) * **Community**: Join our developer community for discussions and updates ## What's Next? Learn how to authenticate your API requests Make your first API call in minutes Explore all available endpoints Set up real-time event notifications # Monitoring & Logs Source: https://developers.mihu.ai/monitoring Track your API requests, responses, and webhook deliveries in real-time ## Overview Mihu provides comprehensive logging and monitoring tools to help you track API usage, debug issues, and ensure your integrations are working correctly. All logs are accessible through your workspace dashboard and provide detailed information about every request and webhook delivery. ## Accessing Logs Navigate to your Mihu workspace at `https://your-tenant.mihu.ai` and sign in. Click on **"Logs"** in the right section of your dashboard navigation. Select the type of logs you want to view: * **API Logs**: Request and response details for all API calls * **Webhook Logs**: Webhook delivery attempts and responses ## API Logs API Logs provide detailed information about every API request made to your Mihu workspace. ### What's Included Each API log entry contains: Exact date and time when the request was received HTTP method used (GET, POST, PATCH, DELETE) The API endpoint that was called (e.g., `/api/v1/call`) HTTP response status code (200, 400, 401, 422, 500, etc.) How long the request took to process (in milliseconds) Source IP address of the request Headers included in the request (API tokens are masked for security) The payload sent with the request The response returned by the API Client application or library information ### Viewing API Log Details From the Logs panel, select **"API Logs"**. View a chronological list of all API requests. The most recent requests appear at the top. Use filters to narrow down results: * **Date range**: Select specific time periods * **Status code**: Filter by success (2xx), client errors (4xx), or server errors (5xx) * **Endpoint**: View logs for specific API endpoints * **Method**: Filter by HTTP method (GET, POST, etc.) Click on any log entry to see complete request and response details. ### Example API Log Entry ```json theme={null} { "id": "log_abc123xyz789", "timestamp": "2025-01-15T10:30:45.123Z", "method": "POST", "endpoint": "/api/v1/call", "statusCode": 200, "responseTime": 245, "ipAddress": "203.0.113.42", "userAgent": "axios/1.6.0", "request": { "headers": { "Authorization": "Bearer ****...****", "Content-Type": "application/json" }, "body": { "agentId": "550e8400-e29b-41d4-a716-446655440000", "participant": { "number": "+1234567890" } } }, "response": { "success": true, "message": "Call initiated successfully", "data": { "id": "call_xyz789abc123", "status": "initiated" } } } ``` ## Webhook Logs Webhook Logs show all webhook delivery attempts, including successes, failures, and retries. ### What's Included Each webhook log entry contains: When the webhook was sent The type of event (e.g., `conversation.end`, `intent.triggered`) Your endpoint URL that received the webhook HTTP status code returned by your endpoint How long your endpoint took to respond (in milliseconds) Which delivery attempt this was (1-5) The complete webhook payload that was sent The response returned by your endpoint Any error message if the delivery failed ### Viewing Webhook Log Details From the Logs panel, select **"Webhook Logs"**. View all webhook delivery attempts in chronological order. Filter by: * **Date range**: Specific time periods * **Event type**: Specific webhook events * **Status**: Success, failed, or pending retry * **Status code**: HTTP response codes Click any log entry to see the full payload, response, and any error details. ### Example Webhook Log Entry ```json theme={null} { "id": "webhook_log_123abc", "timestamp": "2025-01-15T10:35:00.456Z", "eventType": "conversation.end", "webhookUrl": "https://api.yourcompany.com/webhooks/mihu", "statusCode": 200, "responseTime": 342, "attemptNumber": 1, "payload": { "event": "conversation.end", "timestamp": "2025-01-15T10:35:00Z", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "duration": 285 } }, "response": { "received": true, "event": "conversation.end" }, "success": true } ``` ## Monitoring Best Practices Regularly check for 4xx and 5xx errors in API logs. Consider setting up external monitoring to alert you when error rates increase. Watch for slow API responses. If response times consistently exceed 2-3 seconds, investigate potential issues with your requests or network. Ensure webhooks are being delivered successfully. Failed webhook deliveries may indicate issues with your endpoint. If webhooks are failing repeatedly, check your endpoint's error logs and ensure it's responding with 200 status codes. Track your API usage to understand patterns and plan for capacity. Watch for unusual spikes that might indicate issues. Download and archive logs if you need to maintain records for compliance or audit purposes. ## Understanding Log Retention **Log Retention Period** * **API Logs**: Retained for 30 days * **Webhook Logs**: Retained for 30 days Logs older than the retention period are automatically deleted. Download important logs if you need to keep them longer. ## Common Monitoring Scenarios ### Debugging Failed API Calls Filter API logs by status code 4xx or 5xx to find failed requests. Open the log entry and examine: * Request body for malformed data * Headers for missing or incorrect authentication * Response body for error messages The response body will contain specific error information to help you fix the issue. Correct the issue in your code and retry the request. Check logs to confirm success. ### Troubleshooting Webhook Deliveries Open Webhook Logs and filter by failed deliveries. Look at: * Status code from your endpoint * Response time (timeouts are >5 seconds) * Error messages * Retry attempts Verify your webhook endpoint is: * Publicly accessible * Using HTTPS * Responding within 5 seconds * Returning 200 status code Use the "Send Test Event" feature in Developer settings to test your endpoint. ### Monitoring API Performance Regular monitoring helps you identify performance issues early: 1. **Track average response times**: Response times should typically be under 500ms 2. **Watch for timeout errors**: Requests timing out may indicate network or server issues 3. **Monitor error rates**: Sudden spikes in errors may indicate a problem 4. **Check rate limits**: Ensure you're not approaching rate limits ## Exporting Logs You can export logs for external analysis or compliance: Use filters to select the logs you want to export. Choose your preferred format: * **JSON**: For programmatic analysis * **CSV**: For spreadsheet analysis Click **"Export"** and save the file to your device. ## API Metrics Dashboard The Mihu dashboard provides visual metrics for your API usage: ### Available Metrics Total API requests over time, broken down by endpoint Percentage of successful requests (2xx status codes) Mean response time for API requests Percentage of failed requests (4xx and 5xx) Success rate for webhook deliveries Most frequently called API endpoints ## Rate Limits and Quotas Monitor your usage against rate limits: **Standard Rate Limits** * **API Requests**: 1000 requests per minute per workspace * **Concurrent Calls**: 50 simultaneous active calls * **Webhook Deliveries**: 100 events per second Contact support if you need higher limits for your use case. ### Checking Your Usage View your current usage in the dashboard: 1. Navigate to **Developer** → **Usage** 2. View real-time metrics for: * Requests per minute * Active calls * Webhook queue size If you exceed rate limits, you'll receive `429 Too Many Requests` responses. Implement exponential backoff in your code to handle rate limit errors gracefully. ## Advanced Monitoring For production applications, consider implementing: ### External Monitoring * Use services like Datadog, New Relic, or Prometheus to monitor API performance * Set up alerts for error rate thresholds * Track custom metrics specific to your use case ### Log Aggregation * Stream logs to your own logging infrastructure * Integrate with tools like Elasticsearch, Splunk, or CloudWatch * Correlate Mihu logs with your application logs ### Health Checks Create scheduled health checks to verify API availability: ```javascript Example Health Check theme={null} const checkMihuAPI = async () => { try { const response = await fetch( `https://your-tenant.mihu.ai/api/v1/calls?page=1&limit=1`, { headers: { 'Authorization': `Bearer ${API_TOKEN}` } } ); if (response.ok) { console.log('✓ Mihu API is healthy'); return true; } else { console.error('✗ Mihu API returned error:', response.status); return false; } } catch (error) { console.error('✗ Mihu API is unreachable:', error.message); return false; } }; // Run every 5 minutes setInterval(checkMihuAPI, 5 * 60 * 1000); ``` ## Getting Help If you notice unusual patterns in your logs or need assistance with monitoring: * **Check the documentation**: Review the [errors guide](/errors) for common issues * **Contact support**: Email [support@mihu.ai](mailto:support@mihu.ai) with log IDs for specific issues * **Community forum**: Ask questions in the developer community ## Next Steps Learn about error codes and troubleshooting Set up webhook monitoring Explore all available endpoints Manage API tokens and security # Quickstart Source: https://developers.mihu.ai/quickstart Get started with the Mihu API in minutes - make your first call ## Prerequisites Before you begin, ensure you have: You'll need a valid API token. If you haven't created one yet, follow the [authentication guide](/authentication) to generate your token. Know your workspace tenant/subdomain. This is the subdomain in your Mihu workspace URL (e.g., if your URL is `https://abc.mihu.ai`, your tenant is `abc`). You'll need an Agent ID to initiate calls. You can find your agents in the Mihu dashboard under the Agents section. The Agent ID is a UUID format identifier. ## Make Your First API Call Let's initiate an AI-powered voice call using the Mihu API. This example will show you how to start a conversation with a phone number. ### Step 1: Set Up Your Environment First, set up your credentials as environment variables: ```bash Terminal theme={null} export MIHU_API_TOKEN="your-api-token-here" export MIHU_TENANT="your-tenant-here" export MIHU_AGENT_ID="your-agent-id-here" ``` ```javascript .env (Node.js) theme={null} MIHU_API_TOKEN=your-api-token-here MIHU_TENANT=your-tenant-here MIHU_AGENT_ID=your-agent-id-here ``` ```python .env (Python) theme={null} MIHU_API_TOKEN=your-api-token-here MIHU_TENANT=your-tenant-here MIHU_AGENT_ID=your-agent-id-here ``` ### Step 2: Initiate Your First Call ```bash cURL theme={null} curl -X POST https://{your-tenant}.mihu.ai/api/v1/call \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agentId": "your-agent-id-here", "participant": { "number": "+1234567890" } }' ``` ```javascript JavaScript/Node.js theme={null} // Using fetch (built-in in Node.js 18+) const initiateCall = async () => { const response = await fetch('https://your-tenant.mihu.ai/api/v1/call', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.MIHU_API_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ agentId: process.env.MIHU_AGENT_ID, participant: { number: '+1234567890' } }) }); const data = await response.json(); console.log('Call initiated:', data); return data; }; initiateCall(); ``` ```python Python theme={null} import requests import os def initiate_call(): url = f"https://{os.getenv('MIHU_TENANT')}.mihu.ai/api/v1/call" headers = { "Authorization": f"Bearer {os.getenv('MIHU_API_TOKEN')}", "Content-Type": "application/json" } data = { "agentId": os.getenv('MIHU_AGENT_ID'), "participant": { "number": "+1234567890" } } response = requests.post(url, headers=headers, json=data) result = response.json() print("Call initiated:", result) return result # Execute the call initiate_call() ``` ```typescript TypeScript theme={null} interface CallRequest { agentId: string; participant: { number: string; }; } interface CallResponse { success: boolean; message: string; data: { id: string; status: string; provider: string; }; } const initiateCall = async (): Promise => { const response = await fetch( `https://${process.env.MIHU_TENANT}.mihu.ai/api/v1/call`, { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.MIHU_API_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ agentId: process.env.MIHU_AGENT_ID, participant: { number: '+1234567890' } } as CallRequest) } ); const data = await response.json(); console.log('Call initiated:', data); return data; }; initiateCall(); ``` ### Step 3: Understanding the Response When successful, you'll receive a response like this: ```json theme={null} { "success": true, "message": "Call initiated successfully", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "provider": "twilio", "agentId": "your-agent-id-here", "participant": { "number": "+1234567890" }, "createdAt": "2025-01-15T10:30:00Z" } } ``` Indicates whether the call was initiated successfully A human-readable message describing the result Contains the call details Unique identifier for the call (UUID format). Save this to track the call status. Current status of the call (e.g., "initiated", "in-progress", "completed") The telephony provider used for the call The ID of the AI agent conducting the call ## Advanced Call Options You can customize your call with additional parameters: ```bash cURL with Options theme={null} curl -X POST https://your-tenant.mihu.ai/api/v1/call \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agentId": "your-agent-id-here", "participant": { "number": "+1234567890", "name": "John Doe" }, "greetingMessage": "Hello! This is an automated call from Mihu.", "metadata": { "campaign": "customer-survey", "customerId": "12345" } }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://your-tenant.mihu.ai/api/v1/call', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.MIHU_API_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ agentId: process.env.MIHU_AGENT_ID, participant: { number: '+1234567890', name: 'John Doe' }, greetingMessage: 'Hello! This is an automated call from Mihu.', metadata: { campaign: 'customer-survey', customerId: '12345' } }) }); ``` ```python Python theme={null} data = { "agentId": os.getenv('MIHU_AGENT_ID'), "participant": { "number": "+1234567890", "name": "John Doe" }, "greetingMessage": "Hello! This is an automated call from Mihu.", "metadata": { "campaign": "customer-survey", "customerId": "12345" } } response = requests.post(url, headers=headers, json=data) ``` ## Checking Call Status After initiating a call, you can check its status using the call ID: ```bash cURL theme={null} curl -X GET https://your-tenant.mihu.ai/api/v1/calls/{call-id} \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```javascript JavaScript theme={null} const getCallStatus = async (callId) => { const response = await fetch( `https://your-tenant.mihu.ai/api/v1/calls/${callId}`, { headers: { 'Authorization': `Bearer ${process.env.MIHU_API_TOKEN}`, 'Content-Type': 'application/json' } } ); const data = await response.json(); console.log('Call status:', data); return data; }; ``` ```python Python theme={null} def get_call_status(call_id): url = f"https://{os.getenv('MIHU_TENANT')}.mihu.ai/api/v1/calls/{call_id}" headers = { "Authorization": f"Bearer {os.getenv('MIHU_API_TOKEN')}", "Content-Type": "application/json" } response = requests.get(url, headers=headers) return response.json() ``` ## Handling Errors Always implement proper error handling: ```javascript JavaScript theme={null} const initiateCall = async () => { try { const response = await fetch('https://your-tenant.mihu.ai/api/v1/call', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.MIHU_API_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ agentId: process.env.MIHU_AGENT_ID, participant: { number: '+1234567890' } }) }); if (!response.ok) { const error = await response.json(); throw new Error(`API Error: ${error.message}`); } const data = await response.json(); return data; } catch (error) { console.error('Failed to initiate call:', error.message); throw error; } }; ``` ```python Python theme={null} def initiate_call(): url = f"https://{os.getenv('MIHU_TENANT')}.mihu.ai/api/v1/call" headers = { "Authorization": f"Bearer {os.getenv('MIHU_API_TOKEN')}", "Content-Type": "application/json" } data = { "agentId": os.getenv('MIHU_AGENT_ID'), "participant": { "number": "+1234567890" } } try: response = requests.post(url, headers=headers, json=data) response.raise_for_status() # Raises an HTTPError for bad status codes return response.json() except requests.exceptions.HTTPError as e: print(f"HTTP Error: {e}") print(f"Response: {e.response.json()}") raise except requests.exceptions.RequestException as e: print(f"Request failed: {e}") raise ``` ## Common Error Responses | Status Code | Error | Solution | | ----------- | ---------------- | -------------------------------------------------- | | 400 | Bad Request | Check your request body format and required fields | | 401 | Unauthorized | Verify your API token is correct | | 404 | Not Found | Check your tenant subdomain and endpoint URL | | 422 | Validation Error | Review the error message for invalid parameters | ## Next Steps Congratulations! You've made your first API call. Here's what to explore next: Receive real-time updates about your calls Discover all available endpoints and features Track your API requests and responses Learn about error codes and troubleshooting ## Complete Example Here's a complete working example that initiates a call and monitors its status: ```javascript Complete Example theme={null} require('dotenv').config(); const MIHU_CONFIG = { tenant: process.env.MIHU_TENANT, token: process.env.MIHU_API_TOKEN, agentId: process.env.MIHU_AGENT_ID }; const initiateAndMonitorCall = async (phoneNumber) => { const baseUrl = `https://${MIHU_CONFIG.tenant}.mihu.ai/api/v1`; const headers = { 'Authorization': `Bearer ${MIHU_CONFIG.token}`, 'Content-Type': 'application/json' }; try { // Step 1: Initiate the call console.log('Initiating call to', phoneNumber); const callResponse = await fetch(`${baseUrl}/call`, { method: 'POST', headers, body: JSON.stringify({ agentId: MIHU_CONFIG.agentId, participant: { number: phoneNumber } }) }); if (!callResponse.ok) { throw new Error(`Failed to initiate call: ${callResponse.statusText}`); } const callData = await callResponse.json(); console.log('Call initiated:', callData.data.id); // Step 2: Monitor call status const callId = callData.data.id; const statusResponse = await fetch(`${baseUrl}/calls/${callId}`, { headers }); const statusData = await statusResponse.json(); console.log('Call status:', statusData.data.status); return statusData; } catch (error) { console.error('Error:', error.message); throw error; } }; // Run the example initiateAndMonitorCall('+1234567890'); ``` ```python Complete Example theme={null} import os import requests from dotenv import load_dotenv load_dotenv() MIHU_CONFIG = { 'tenant': os.getenv('MIHU_TENANT'), 'token': os.getenv('MIHU_API_TOKEN'), 'agent_id': os.getenv('MIHU_AGENT_ID') } def initiate_and_monitor_call(phone_number): base_url = f"https://{MIHU_CONFIG['tenant']}.mihu.ai/api/v1" headers = { "Authorization": f"Bearer {MIHU_CONFIG['token']}", "Content-Type": "application/json" } try: # Step 1: Initiate the call print(f"Initiating call to {phone_number}") call_response = requests.post( f"{base_url}/call", headers=headers, json={ "agentId": MIHU_CONFIG['agent_id'], "participant": {"number": phone_number} } ) call_response.raise_for_status() call_data = call_response.json() print(f"Call initiated: {call_data['data']['id']}") # Step 2: Monitor call status call_id = call_data['data']['id'] status_response = requests.get( f"{base_url}/calls/{call_id}", headers=headers ) status_response.raise_for_status() status_data = status_response.json() print(f"Call status: {status_data['data']['status']}") return status_data except requests.exceptions.RequestException as e: print(f"Error: {e}") raise # Run the example if __name__ == "__main__": initiate_and_monitor_call("+1234567890") ``` # Webhooks Source: https://developers.mihu.ai/webhooks Receive real-time notifications about events in your Mihu workspace ## What Are Webhooks? Webhooks allow you to receive real-time HTTP notifications whenever specific events occur in your Mihu workspace. Instead of continuously polling the API for updates, Mihu will send POST requests to your specified endpoint URL when events happen. ### Why Use Webhooks? Get instant notifications when conversations end, status changes occur, or intents are triggered. No need to poll the API repeatedly. Webhooks push data to you automatically. Build reactive applications that respond immediately to conversation events. Integrate Mihu with your existing systems and workflows seamlessly. ## Setting Up Webhooks ### Prerequisites Before configuring webhooks, ensure you have: * Admin or developer access to your Mihu workspace * A publicly accessible HTTPS endpoint to receive webhook events * (Recommended) A secret key for webhook signature verification ### Configuration Steps 1. Log in to your Mihu workspace at `https://your-tenant.mihu.ai` 2. Click on your profile icon in the top right corner 3. Select **"Developer"** from the dropdown menu In the Developer section, find the **"Webhooks"** configuration area. 1. In the **"Webhook URL"** field, enter your endpoint URL 2. This must be a publicly accessible HTTPS URL 3. Example: `https://api.yourcompany.com/webhooks/mihu` HTTP URLs are not supported for security reasons. Your endpoint must use HTTPS. 1. Enter a **"Secret Key"** in the provided field 2. This key will be used to sign webhook payloads 3. Store this key securely - you'll need it to verify webhook signatures 4. Use a strong, random string (minimum 32 characters recommended) Generate a secure secret key using: `openssl rand -hex 32` Choose which events you want to receive notifications for: * ✅ **Conversation Update**: Real-time updates during conversations * ✅ **Conversation End Report**: Detailed report when conversation completes * ✅ **Conversation Status**: Status changes (initiated, in-progress, ended) * ✅ **Intent Call**: Triggered when specific intents are detected * ✅ **Text Evaluation**: Results from text-based evaluations * ✅ **Voice Evaluation**: Results from voice conversation evaluations Select only the events you need to reduce unnecessary webhook traffic. Click **"Save"** or **"Update"** to activate your webhook configuration. ## Available Event Types ### Conversation Update Sent in real-time as the conversation progresses. Useful for live monitoring and transcription display. **Event Type:** `conversation.update` ```json Example Payload theme={null} { "event": "conversation.update", "timestamp": "2025-01-15T10:30:45Z", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "agentId": "agent-uuid-here", "status": "in-progress", "participant": { "number": "+1234567890", "name": "John Doe" }, "transcript": [ { "speaker": "agent", "text": "Hello, how can I help you today?", "timestamp": "2025-01-15T10:30:10Z" }, { "speaker": "participant", "text": "I need help with my account.", "timestamp": "2025-01-15T10:30:35Z" } ], "currentSentiment": "neutral" } } ``` ### Conversation End Report Sent when a conversation completes. Contains comprehensive conversation analytics. **Event Type:** `conversation.end` ```json Example Payload theme={null} { "event": "conversation.end", "timestamp": "2025-01-15T10:35:00Z", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "agentId": "agent-uuid-here", "status": "completed", "duration": 285, "participant": { "number": "+1234567890", "name": "John Doe" }, "summary": { "outcome": "resolved", "sentiment": "positive", "intentsDetected": ["account_inquiry", "billing_question"], "resolutionTime": 285, "customerSatisfaction": 4.5 }, "fullTranscript": "...", "recording": { "url": "https://recordings.mihu.ai/...", "duration": 285 }, "metadata": { "campaign": "customer-support", "customerId": "12345" } } } ``` ### Conversation Status Sent when conversation status changes (initiated → in-progress → ended/failed/missed). **Event Type:** `conversation.status` ```json Example Payload theme={null} { "event": "conversation.status", "timestamp": "2025-01-15T10:30:15Z", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "agentId": "agent-uuid-here", "previousStatus": "initiated", "currentStatus": "in-progress", "participant": { "number": "+1234567890" }, "statusChangedAt": "2025-01-15T10:30:15Z" } } ``` ### Intent Call Triggered when a specific intent is detected during the conversation. Useful for triggering actions or integrations. **Event Type:** `intent.triggered` ```json Example Payload theme={null} { "event": "intent.triggered", "timestamp": "2025-01-15T10:32:00Z", "data": { "conversationId": "550e8400-e29b-41d4-a716-446655440000", "intent": { "name": "transfer_to_human", "confidence": 0.95, "parameters": { "department": "billing", "priority": "high" } }, "context": { "lastUserMessage": "I need to speak with someone about my bill", "conversationTurn": 5 } } } ``` ### Text Evaluation Results from text-based conversation evaluations. **Event Type:** `evaluation.text` ```json Example Payload theme={null} { "event": "evaluation.text", "timestamp": "2025-01-15T10:35:30Z", "data": { "conversationId": "550e8400-e29b-41d4-a716-446655440000", "evaluationType": "quality_assurance", "scores": { "accuracy": 0.92, "relevance": 0.88, "completeness": 0.95 }, "feedback": "Conversation handled professionally with accurate information.", "recommendations": [ "Consider offering callback option earlier" ] } } ``` ### Voice Evaluation Results from voice conversation quality evaluations. **Event Type:** `evaluation.voice` ```json Example Payload theme={null} { "event": "evaluation.voice", "timestamp": "2025-01-15T10:35:45Z", "data": { "conversationId": "550e8400-e29b-41d4-a716-446655440000", "evaluationType": "voice_quality", "scores": { "clarity": 0.94, "naturalness": 0.89, "emotionalTone": 0.87, "audioQuality": 0.96 }, "metrics": { "averageResponseTime": 1.2, "silenceDuration": 5.3, "interruptionCount": 2 } } } ``` ## Webhook Payload Structure All webhook payloads follow a consistent structure: ```json theme={null} { "event": "event.type", "timestamp": "ISO 8601 timestamp", "data": { // Event-specific data }, "signature": "webhook-signature-hash" } ``` The type of event that triggered the webhook ISO 8601 formatted timestamp when the event occurred Event-specific payload containing relevant information HMAC-SHA256 signature for payload verification (when secret key is configured) ## Security & Verification ### Verifying Webhook Signatures When you configure a secret key, Mihu signs each webhook payload with an HMAC-SHA256 signature. Always verify this signature to ensure the webhook is genuine. ```javascript Node.js theme={null} const crypto = require('crypto'); function verifyWebhookSignature(payload, signature, secret) { const hmac = crypto.createHmac('sha256', secret); const expectedSignature = hmac.update(JSON.stringify(payload)).digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ); } // Express.js middleware example app.post('/webhooks/mihu', express.json(), (req, res) => { const signature = req.headers['x-mihu-signature']; const secret = process.env.MIHU_WEBHOOK_SECRET; if (!verifyWebhookSignature(req.body, signature, secret)) { return res.status(401).json({ error: 'Invalid signature' }); } // Process webhook const { event, data } = req.body; console.log(`Received event: ${event}`); res.status(200).json({ received: true }); }); ``` ```python Python (Flask) theme={null} import hmac import hashlib import json from flask import Flask, request, jsonify app = Flask(__name__) def verify_webhook_signature(payload, signature, secret): expected_signature = hmac.new( secret.encode('utf-8'), json.dumps(payload).encode('utf-8'), hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected_signature) @app.route('/webhooks/mihu', methods=['POST']) def handle_mihu_webhook(): signature = request.headers.get('X-Mihu-Signature') secret = os.environ.get('MIHU_WEBHOOK_SECRET') payload = request.json if not verify_webhook_signature(payload, signature, secret): return jsonify({'error': 'Invalid signature'}), 401 # Process webhook event_type = payload.get('event') data = payload.get('data') print(f"Received event: {event_type}") return jsonify({'received': True}), 200 ``` ```php PHP theme={null} 'Invalid signature']); exit; } // Process webhook $eventType = $payload['event']; $data = $payload['data']; http_response_code(200); echo json_encode(['received' => true]); ?> ``` ### Best Practices Never process webhooks without verifying the signature when a secret key is configured. This prevents unauthorized access and spoofed requests. Only use HTTPS endpoints for webhooks. HTTP is not supported for security reasons. Return a 200 status code within 5 seconds. Process long-running tasks asynchronously in a background job. Webhooks may be delivered more than once. Use the event ID to track processed events and prevent duplicate processing. If your endpoint is temporarily unavailable, Mihu will retry delivery. Implement proper error handling to accept retries gracefully. Keep logs of received webhooks for debugging and audit purposes. ## Webhook Endpoint Requirements Your webhook endpoint must: ✅ Accept POST requests with JSON payloads ✅ Use HTTPS (HTTP not supported) ✅ Return HTTP 200 status code to acknowledge receipt ✅ Respond within 5 seconds ✅ Be publicly accessible on the internet Endpoints that consistently timeout or return errors may be automatically disabled to prevent delivery issues. ## Testing Webhooks ### Viewing Webhook Logs You can view webhook delivery attempts in your Mihu dashboard: 1. Navigate to **Developer** section 2. Click on **"Logs"** in the right panel 3. Select **"Webhook Logs"** Here you'll see: * Delivery timestamps * Event types * HTTP status codes * Response times * Payload contents * Error messages (if any) ### Testing Locally For local development, use tools like ngrok to expose your local server: ```bash theme={null} # Install ngrok npm install -g ngrok # Expose your local server ngrok http 3000 # Use the generated HTTPS URL in webhook configuration # Example: https://abc123.ngrok.io/webhooks/mihu ``` ### Manual Testing You can trigger test webhook events from the Developer section: 1. Go to **Developer** → **Webhooks** 2. Click **"Send Test Event"** 3. Select the event type 4. Review the test payload 5. Click **"Send"** ## Example Webhook Handler Here's a complete example webhook handler with signature verification and event processing: ```javascript Complete Node.js Handler theme={null} const express = require('express'); const crypto = require('crypto'); const app = express(); app.use(express.json()); const WEBHOOK_SECRET = process.env.MIHU_WEBHOOK_SECRET; // Verify webhook signature function verifySignature(payload, signature) { const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET); const expectedSignature = hmac.update(JSON.stringify(payload)).digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ); } // Webhook handler app.post('/webhooks/mihu', async (req, res) => { try { const signature = req.headers['x-mihu-signature']; // Verify signature if (!verifySignature(req.body, signature)) { return res.status(401).json({ error: 'Invalid signature' }); } const { event, data, timestamp } = req.body; // Process different event types switch (event) { case 'conversation.end': await handleConversationEnd(data); break; case 'conversation.update': await handleConversationUpdate(data); break; case 'intent.triggered': await handleIntentTriggered(data); break; default: console.log(`Unhandled event type: ${event}`); } // Acknowledge receipt res.status(200).json({ received: true, event }); } catch (error) { console.error('Webhook processing error:', error); res.status(500).json({ error: 'Processing failed' }); } }); async function handleConversationEnd(data) { console.log('Conversation ended:', data.id); console.log('Duration:', data.duration, 'seconds'); console.log('Outcome:', data.summary.outcome); // Store in database, send notifications, etc. } async function handleConversationUpdate(data) { console.log('Conversation update:', data.id); console.log('Current status:', data.status); // Update real-time dashboard, etc. } async function handleIntentTriggered(data) { console.log('Intent triggered:', data.intent.name); console.log('Confidence:', data.intent.confidence); // Trigger actions based on intent } app.listen(3000, () => { console.log('Webhook server listening on port 3000'); }); ``` ```python Complete Python Handler theme={null} from flask import Flask, request, jsonify import hmac import hashlib import json import os app = Flask(__name__) WEBHOOK_SECRET = os.environ.get('MIHU_WEBHOOK_SECRET') def verify_signature(payload, signature): expected_signature = hmac.new( WEBHOOK_SECRET.encode('utf-8'), json.dumps(payload).encode('utf-8'), hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected_signature) @app.route('/webhooks/mihu', methods=['POST']) def handle_webhook(): try: signature = request.headers.get('X-Mihu-Signature') payload = request.json # Verify signature if not verify_signature(payload, signature): return jsonify({'error': 'Invalid signature'}), 401 event_type = payload.get('event') data = payload.get('data') timestamp = payload.get('timestamp') # Process different event types if event_type == 'conversation.end': handle_conversation_end(data) elif event_type == 'conversation.update': handle_conversation_update(data) elif event_type == 'intent.triggered': handle_intent_triggered(data) else: print(f"Unhandled event type: {event_type}") # Acknowledge receipt return jsonify({'received': True, 'event': event_type}), 200 except Exception as e: print(f"Webhook processing error: {e}") return jsonify({'error': 'Processing failed'}), 500 def handle_conversation_end(data): print(f"Conversation ended: {data['id']}") print(f"Duration: {data['duration']} seconds") print(f"Outcome: {data['summary']['outcome']}") # Store in database, send notifications, etc. def handle_conversation_update(data): print(f"Conversation update: {data['id']}") print(f"Current status: {data['status']}") # Update real-time dashboard, etc. def handle_intent_triggered(data): print(f"Intent triggered: {data['intent']['name']}") print(f"Confidence: {data['intent']['confidence']}") # Trigger actions based on intent if __name__ == '__main__': app.run(port=3000) ``` ## Retry Policy If your webhook endpoint fails or times out, Mihu will automatically retry delivery: * **Initial retry**: After 1 minute * **Subsequent retries**: Exponential backoff (2min, 4min, 8min, 16min) * **Maximum retries**: 5 attempts * **Timeout**: 5 seconds per attempt After exhausting all retries, the webhook event will be marked as failed and logged in the Webhook Logs. ## Troubleshooting ### Common Issues **Possible causes:** * Endpoint URL is not publicly accessible * Firewall blocking incoming requests * Server is down or not responding * Using HTTP instead of HTTPS **Solution:** Test your endpoint with tools like Postman or curl, check logs, ensure HTTPS. **Possible causes:** * Incorrect secret key * Payload modified before verification * Character encoding issues **Solution:** Double-check your secret key, verify you're using the raw request body. **Possible causes:** * Processing taking longer than 5 seconds * Database operations blocking response **Solution:** Return 200 immediately, process webhook asynchronously in background. **Possible causes:** * Retry mechanism delivering same event * Network issues causing retransmission **Solution:** Implement idempotency using event IDs to track processed events. ## Next Steps Learn how to monitor webhook deliveries and API usage Explore all available API endpoints Understand error codes and troubleshooting Build your first integration