Build reliable voice and SMS operations with HUM.
Learn the core concepts, common workflows, authentication model, and public API reference for managing AI voice calls, SMS conversations and campaigns, call flows, review queues, and integrations.
The API reference is read-only and does not execute authenticated requests.
The OpenAPI files describe customer-facing routes only.
Most API operations require a BlueHive SSO browser session.
How HUM Works
HUM coordinates the operational loop around AI voice calls: configure a workflow, route calls into it, review the result, and connect outcomes to the systems your team already uses.
The tenant boundary for users, phone numbers, calls, flows, webhooks, billing, and analytics.
A reusable AI worker (stored as a call flow) that defines prompts, greetings, transfers, voicemail behavior, business hours, and tools. Agents can be triggered by a live call, an SMS message, or an event.
A routable number assigned to a flow. Inbound calls use the assigned flow to decide how the voice agent responds.
The reviewable history of a call: metadata, transcript, tool activity, summary, outcome, tags, notes, and voicemail context.
A customer-managed delivery endpoint for signed events that should leave HUM and enter another system.
A customer-managed tool integration that selected flows can use when a call needs approved external actions.
A long-lived thread keyed by (your number, contact E.164). Closing a conversation does not delete history; an inbound message reopens it automatically.
A throttled bulk send to a recipient list, optionally tied to a flow so AI handles inbound replies.
A customer-managed base URL and shared secret implementing four signed endpoints (lookup, create, calls, ping). HUM resolves callers and pushes call activity without any CRM-specific code in the call path.
A phone-keyed address-book record enriched from Twilio Lookup (carrier, line type, caller name) and your CRM, so flows know who is calling before the agent speaks.
The core loop
Quick Start
A typical HUM rollout starts with a single organization, one flow, and one assigned phone number. Expand from there as the workflow proves itself.
Sign in and choose an organization
HUM uses the BlueHive SSO session. Once signed in, every tenant endpoint is scoped to the current organization.
Create an AI agent
Define the greeting, instructions, voicemail handling, business hours, and optional tools the voice agent should use.
Assign a phone number
Connect a number to the flow so inbound callers reach the right workflow.
Review calls and outcomes
Use calls, transcripts, summaries, notes, tags, contacts, voicemails, and analytics to manage follow-up.
Authentication
HUM uses the BlueHive SSO browser session. The session cookie is HTTP-only, and tenant endpoints resolve access from the signed-in user and current organization membership.
Start with /auth/login. After sign-in, use /api/me to load the current user and organization context.
Organization data endpoints are scoped to the current organization. A valid session alone is not enough without membership in that organization.
GET https://hum-api.bluehive.com/auth/login?return_to=/dashboard
GET https://hum-api.bluehive.com/api/meCall Lifecycle
Calls move from routing into live handling, then into review. The public API mirrors that lifecycle with list, detail, live event, note, tag, and analytics endpoints.
Use the call detail and live event stream to keep transcripts, call state, and tool activity fresh while a call is active.
Add tags and notes, update contacts, mark voicemails heard, and use outcomes to drive follow-up work.
Use analytics and flow-specific metrics to compare volume, outcomes, and trend windows across operational workflows.
| Endpoint | Purpose |
|---|---|
| /api/calls | Find calls by search, direction, status, date range, and cursor. |
| /api/calls/{id} | Read call detail, transcript, summary, outcome, and review context. |
| /api/calls/{id}/stream | Subscribe to live call events while a call is active. |
| /api/analytics | Review aggregate call trends for a day window. |
AI Agents
AI Agents are the reusable instructions behind HUM calls (the /api/flows resource). A good agent gives the voice agent clear goals, boundaries, fallback behavior, and follow-up structure.
| Field | Use |
|---|---|
| name | Required label shown throughout HUM. |
| kind | Inbound or outbound workflow type. |
| greeting | Opening phrase the caller hears before the workflow continues. |
| system_prompt | Primary instructions for the voice agent. |
| voicemail_enabled | Controls whether voicemail capture is available. |
| business_hours_json | Optional schedule rules for when the flow should answer normally. |
| tools_json | Approved tool configuration for the flow. |
POST /api/flows
{
"name": "Clinic intake",
"kind": "inbound",
"greeting": "Thanks for calling. I can help collect your request.",
"system_prompt": "Gather the caller's name, best phone number, reason for calling, and urgency.",
"voicemail_enabled": 1,
"announce_recording": 1
}Phone Numbers
Phone numbers connect callers to flows. Keep assignments explicit so operational teams can understand which workflow answers each number.
| Endpoint | Purpose |
|---|---|
| /api/numbers | List or register numbers available to the organization. |
| /api/numbers/sync | Refresh the inventory after provisioning changes. |
| /api/numbers/{id} | Update friendly name or flow assignment. |
Outbound Calls
Outbound calls use the same flow model with call-specific task context. Use this for structured follow-up calls, reminders, and operational outreach.
POST /api/outbound/calls
{
"flow_id": "flow_123",
"to": "+15551234567",
"task_context": {
"reason": "Confirm appointment details",
"preferred_window": "today afternoon"
}
}Review Inbox
The review workflow combines voicemails, contacts, tags, notes, blocked numbers, and call outcomes so teams can decide what needs action.
| Endpoint | Purpose |
|---|---|
| /api/voicemails | Review heard and unheard voicemail items. |
| /api/contacts | Store caller identity and relationship context. |
| /api/calls/{callId}/tags | Add labels for filtering and reporting. |
| /api/calls/{callId}/notes | Add human review notes to a call timeline. |
| /api/blocklist | Manage organization-level blocked numbers. |
SMS Platform
HUM ships a bi-directional SMS platform on the same number inventory as voice. Conversations are persistent, opt-out aware, MMS-capable, and can be driven by the AI, by a human in the inbox, or by your backend through the REST API.
Each (your number, contact E.164) pair is a single thread that reopens on inbound messages. Closing a conversation never deletes history.
Carrier keywords (STOP, HELP, START) are processed automatically and outbound sends to opted-out numbers short-circuit before Twilio is called.
| Endpoint | Purpose |
|---|---|
| /api/sms/conversations | List, create, or fetch conversations. |
| /api/sms/conversations/{id} | Read or update one thread (assignee, status, AI pause, snooze). |
| /api/sms/conversations/{id}/messages | Send outbound (now or scheduled) and paginate the thread. |
| /api/sms/conversations/{id}/read | Reset unread_count to zero for inbox-style UIs. |
| /api/sms/conversations/{id}/close | Mark closed and fire the conversation.closed webhook. |
| /api/sms/conversations/{id}/reopen | Move back to open and clear any snooze timer. |
| /api/sms/scheduled | List or cancel pending scheduled sends. |
POST /api/sms/conversations
{
"twilio_number_id": "01HVN...",
"contact_e164": "+13175551234",
"initial_message": {
"body": "Hi! Just confirming your 10am appointment."
}
}SMS AI Flows
Drop the same flow concept used for voice onto SMS. Set a flow's channel to 'sms', wire it to a number, and inbound messages are debounced and answered by a single Responses-API turn that can call your tools.
assign_to_human, close_conversation, transfer_sms_to_flow, schedule_followup_sms, lookup_knowledge, and report_outcome ship out of the box.
Per-flow caps on turns per 10-minute window, messages per run, and pending AI follow-ups protect against runaway behavior. Tool calls are sequential, not parallel.
POST /api/flows
{
"name": "SMS triage",
"channel": "sms",
"system_prompt": "You are a helpful assistant for ACME Clinic.",
"sms_config_json": {
"max_reply_chars": 1600,
"debounce_ms": 1500,
"max_turns_per_window": 30,
"fallback_message": "We'll get back to you shortly."
}
}
PATCH /api/numbers/{numberId}
{ "sms_flow_id": "flow_...", "sms_enabled": true }Campaigns
Throttled bulk SMS with quiet-hours awareness, per-recipient body overrides, and optional flow attachment so inbound replies route into the AI.
| Endpoint | Purpose |
|---|---|
| /api/sms/campaigns | List or create campaigns. |
| /api/sms/campaigns/{id} | Read campaign detail and recipient progress. |
| /api/sms/campaigns/{id}/launch | Move from draft or paused into queued for the cron dispatcher. |
| /api/sms/campaigns/{id}/cancel | Stop further sends; in-flight messages still deliver. |
POST /api/sms/campaigns
{
"name": "January refill reminder",
"twilio_number_id": "01HV...",
"body_template": "Hi! Time to refill. Reply STOP to opt out.",
"throttle_per_minute": 30,
"scheduled_start_at": "2026-02-01T09:00:00Z",
"recipients": [
{ "contact_e164": "+13175551234" },
{ "contact_e164": "+13175555678", "body": "Custom override for this recipient" }
]
}
POST /api/sms/campaigns/{id}/launchOpt-outs & Quiet Hours
HUM processes carrier keywords automatically and honors per-org business hours on outbound sends. You can manage the opt-out list directly through the API.
| Endpoint | Purpose |
|---|---|
| /api/sms/opt-outs | List or add opt-outs (fires sms.opt_out). |
| /api/sms/opt-outs/{e164} | Remove an opt-out (fires sms.opt_in). URL-encode the leading +. |
Outbound sends outside the org's business hours auto-defer to the next open window with source='quiet_hours'. Pass honor_quiet_hours=false to bypass.
Subscribe to sms.received, sms.sent, sms.delivered, sms.failed, sms.opt_out, sms.opt_in, conversation.started, conversation.assigned, and conversation.closed.
See the full developer reference at sms-api.md for payload shapes, anti-loop guards, and operational notes.
Team Roles
Team endpoints help organization admins invite users and manage access. Use the least-privileged role that fits each person.
| Role | Typical use |
|---|---|
| viewer | Can inspect operational data without managing configuration. |
| operator | Can work day-to-day call review workflows. |
| admin | Can manage organization settings, team access, and integrations. |
Customer-Managed Webhooks
Webhooks deliver signed HUM events to customer-owned systems. Treat the signing secret like a credential and verify every delivery before processing it.
Store the signing secret securely and verify each delivery in the receiving service before trusting the payload.
Use test deliveries, delivery history, secret rotation, and redelivery when troubleshooting customer-owned endpoints.
MCP Tool Integrations
MCP integrations let selected flows use customer-approved tools. Keep tool allowlists narrow and require approval by default for sensitive actions.
| Setting | Guidance |
|---|---|
| transport | Choose the integration transport supported by the customer-owned tool server. |
| allowed_tools_json | Limit which tools the flow can see and call. |
| auto_approve_tools_json | Allow only low-risk tools to run without review. |
| require_approval_default | Default to approval for safer tool execution. |
CRM Connectors
A CRM Connector lets HUM resolve callers against your CRM and push finished-call activity back — without any CRM-specific code in the call path. Register a base URL and a shared secret, then implement four endpoints HUM calls over a small, signed HTTP contract.
| Endpoint | Purpose |
|---|---|
| POST {base_url}/contacts/lookup | Resolve a phone number to a contact. |
| POST {base_url}/contacts | Create a contact HUM couldn't find. |
| POST {base_url}/calls | Attribute a finished call as activity. |
| POST {base_url}/ping | Connectivity and auth check. |
Every request carries Authorization: Bearer <secret> and X-HUM-Signature: sha256=HMAC-SHA256(secret, rawBody). Verify both with a constant-time compare over the raw bytes before parsing.
Respond within the connector's timeout_ms (default 4000 ms, max 30000). HUM handles orchestration, queue-level retries, logging, and signing.
Pre-call hooks can also call CRM endpoints to enrich the agent prompt before Bea speaks. See the full reference at crm-integration.md and flow-hooks.md.
Contacts & Caller Enrichment
HUM keeps a phone-keyed address book per organization. Inbound numbers are enriched automatically through Twilio Lookup, and a registered CRM connector can supply the canonical contact, so flows and agents know who is calling before answering.
Twilio Lookup populates carrier, line type, and caller name on inbound calls. User overrides and CRM lookups take precedence when present.
Backfill existing contacts from Twilio retroactively, then search by phone or name and tag records for routing and reporting.
Billing and Usage
Billing endpoints support plan review, checkout, customer portal redirects, subscription settings, and usage summaries for the current organization.
| Endpoint | Purpose |
|---|---|
| /api/billing | Read plan, subscription, and usage summary. |
| /api/billing/checkout | Create a hosted checkout redirect for a selected plan. |
| /api/billing/portal | Create a hosted customer portal redirect. |
| /api/billing/subscription | Update customer-controlled subscription settings. |
API Reference
Use the generated OpenAPI files for client generation, review, and integration planning. The hosted API reference is intentionally read-only.
Security Notes
The public docs are designed to explain customer-facing integration behavior while keeping authenticated actions inside the HUM application.
Most endpoints require a valid SSO-backed browser session and organization membership. The API reference does not send browser credentials.
The public OpenAPI document is intentionally scoped to routes customers need for planning, integration, and app-adjacent workflows.
FAQ
Common questions for teams using the public HUM docs and API contract.
Can I run API requests from this reference?
No. The public API reference is intentionally read-only. Use the HUM app for authenticated actions and use the OpenAPI files for reference, client generation, and integration planning.
Why do most endpoints use a session cookie?
HUM is primarily a browser-operated console. The API uses the BlueHive SSO session plus organization membership to scope every tenant request.
Does the public spec include every API route?
No. The public contract is limited to customer-facing routes that are useful for product understanding, client generation, and integration planning.
How should I model outbound webhook receivers?
Create a webhook in HUM, store the returned signing secret securely, verify signatures on every delivery, and use delivery history plus redelivery for troubleshooting.
What is the safest way to test a call flow?
Duplicate a production flow, make changes in the copy, place a test call to a controlled number, then assign the revised flow only after review.
Can the AI respond to inbound SMS automatically?
Yes. Create a Call Flow with channel='sms' and assign it to a number's sms_flow_id. Inbound messages are debounced for a few seconds, then a single Responses-API turn produces a reply. The same tool registry the voice runtime uses is available, plus SMS-specific tools (assign_to_human, close_conversation, schedule_followup_sms, transfer_sms_to_flow, report_outcome).
How are STOP / HELP / START handled?
Twilio carrier keywords (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, START, YES, UNSTOP, HELP, INFO) are processed automatically. Opt-outs fire sms.opt_out, opt-ins fire sms.opt_in, and outbound sends to opted-out numbers return status=opted_out without contacting Twilio.
What happens if I try to send SMS during quiet hours?
By default the message is auto-deferred to the next open window in the org's business hours and the response status is 'scheduled'. The cron scheduler drains it on the next minute boundary. Set honor_quiet_hours=false on a per-send basis to bypass the check (the API does this for human-initiated sends; the AI honors quiet hours).
- HUM app and docs
- https://hum.bluehive.com
- HUM API
- https://hum-api.bluehive.com