Core Concepts

This page covers the key entities in oHallo and how they relate to each other. Understanding these concepts will help you navigate the API and build effective integrations.

Account

Your oHallo account is the top-level container for all your data. Every piece of data in the platform — conversations, contacts, knowledge base entries, agent definitions — belongs to exactly one account. There is no cross-account data access at any level.

When you authenticate with an API key, the key is bound to your account. All API calls automatically scope to your account’s data.

Workspace

A workspace is an operational unit within your account. Workspaces typically correspond to a country, language, or business unit. Each workspace has its own:

• Channels (email addresses, chat widgets, WhatsApp numbers)
• Knowledge base entries
• Policy rules
• MCP server connections
• Agent configurations

Most API calls require a workspaceId parameter. If your organisation operates in a single region, you will have one workspace. Multi-country operations typically use one workspace per country.

{
  "id": "ws_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Denmark",
  "operatingLanguage": "da",
  "currency": "DKK",
  "businessType": "b2b",
  "timezone": "Europe/Copenhagen"
}

Brand

A brand is the customer-facing identity used in outbound messages. Each workspace is linked to a brand that controls:

• Company name and logo
• Email sender name and reply address
• Tone of voice (friendly, professional, formal, trade)
• Email signature
• Brand-specific instructions for the AI

A single brand can serve multiple workspaces. For example, a brand “Acme Tools” might have workspaces for Denmark, Sweden, and Norway — each with its own language and currency but sharing the same visual identity.

Channel

A channel is how messages arrive and depart. Each channel belongs to a workspace and is linked to a brand. Supported channel types:

Type	Description
email	Inbound via AWS SES, outbound via SES. Each channel has a dedicated reply address.
chat	Embeddable web widget with WebSocket connection.
whatsapp	Via Meta Cloud API. Subject to 24-hour messaging window rules.
voice	Inbound and outbound voice calls.

Channels are identified by UUID. When composing outbound messages or filtering conversations, you reference the channel ID.

Conversation

A conversation is a thread of messages between a customer contact and oHallo on a single channel. Every conversation has:

• A unique UUID
• A status indicating where it is in its lifecycle
• A link to the contact who initiated it
• A link to the channel it arrived on
• An optional AI-generated summary

Conversation statuses

Status	Meaning
open	New conversation, not yet processed by the AI pipeline.
in_progress	AI is actively processing or has replied; awaiting customer response.
awaiting_contact	AI has replied; waiting for the customer to respond.
resolved	Conversation completed — either by the AI or a human agent.
closed	Administratively closed.
abandoned	Customer did not respond within the configured timeout.

Contact and Account

A contact is an individual person. Contacts are identified by their channel identity — an email address, phone number, or chat session ID. oHallo auto-creates contacts when it receives a message from an unknown sender.

An account is the company a contact belongs to. For B2B workspaces, oHallo attempts to resolve accounts automatically using the sender’s email domain, VAT number, or company registration number. You can also link contacts to accounts manually via the API.

{
  "id": "cnt_f7e8d9c0-b1a2-3456-7890-abcdef123456",
  "name": "Henrik Larsen",
  "email": "henrik@example.dk",
  "accountId": "12345678-abcd-4f01-a345-678901234567",
  "accountName": "Nordic Parts ApS"
}

Agent

An agent is an AI worker that performs a specific task in the conversation pipeline. There are two categories:

System agents handle the core pipeline. You cannot delete them, but you can add custom instructions to influence their behaviour:

• Conversation Orchestrator — analyses incoming messages, classifies intent, and dispatches specialist agents. Evaluates their results and decides when enough information has been gathered.
• Message Agent — composes the final reply using gathered context
• Reply Validation Agent — checks the drafted reply for factual accuracy and policy compliance
• Learning Loop Agent — analyses resolved conversations and proposes knowledge base and policy improvements

The platform also provides built-in specialist agents (Knowledge Base Agent, Policy Agent, Identity Agent, Meeting Booking Agent) that handle standard tasks. These are dispatched automatically by the Orchestrator.

Custom agents handle domain-specific tasks. You create them, bind them to MCP server connections, and give them instructions. The Orchestrator dispatches them automatically when it recognises a matching intent.

{
  "id": "abcdef12-3456-4890-abcd-ef1234567890",
  "name": "Order Lookup Agent",
  "description": "Retrieves order details, tracking information, and delivery status",
  "agentRole": "specialist",
  "model": "claude-sonnet-4-6"
}

MCP Server

An MCP (Model Context Protocol) server exposes tools that oHallo’s agents can call. You build and host the MCP server; oHallo connects to it via HTTPS.

Each MCP server provides a set of tools with typed input schemas. When an agent needs to look up an order, it calls the get_order tool on your MCP server with the order ID. Your server executes the lookup against your system and returns the result.

Example tools an order management MCP server might expose:

Tool	Description
get_order	Look up an order by ID or reference number
search_orders	Search orders by customer, date range, or status
track_shipment	Get shipment tracking information
create_return	Initiate a return request

MCP connections are registered per workspace (or per brand or organisation-wide for shared connections). See the MCP overview for the full protocol specification.

Knowledge Base

The knowledge base is a collection of question-answer pairs that the AI references when composing replies. Entries are scoped to a workspace and organised by topic.

oHallo’s learning loop automatically proposes new KB entries based on resolved conversations. These proposals enter a pending_review status and can be approved or rejected via the dashboard or API.

You can also create, update, and manage KB entries programmatically — useful for keeping the knowledge base in sync with product documentation or support articles.

Policies

Policies are rules that govern how the AI behaves. Unlike KB entries (which provide factual answers), policies define constraints, procedures, and business rules.

Examples:

• “Always ask for the order number before looking up order status”
• “Quotes are valid for 14 days unless otherwise specified”
• “Escalate to a human agent if the customer mentions legal action”

Policies are managed the same way as KB entries — create, approve, reject, and search via the API. The Policy Agent retrieves relevant policies during each conversation turn.

Widget

A widget is an embeddable component that you add to your website so visitors can interact with oHallo directly. There are three widget types:

Type	Purpose
kb	Searchable knowledge base interface — visitors find answers without contacting support
contact	Contact form — visitors submit structured inquiries that become conversations
booking	Meeting scheduler — visitors pick a time slot and book a meeting with your team

Each widget has a public key used in the embed code and can be configured independently (styling, field mapping, calendar connection for booking). Widgets are scoped to a workspace.

Calendar Connection

A calendar connection links oHallo to a Google Calendar or Microsoft 365 calendar. Calendar connections power the booking widget and the Meeting Booking Agent.

When a booking is created, oHallo calculates availability from the connected calendar (working hours minus existing events minus buffer time), creates a tentative event, and sends a confirmation link. Once confirmed, a conferencing link (Google Meet or Microsoft Teams) is generated automatically.

Quality and CSAT

oHallo measures customer satisfaction across three dimensions:

Dimension	Weight	What it measures
Outcome	50%	Did the customer get the result they needed?
Process	30%	Was the interaction smooth and efficient?
Environment	20%	Was the communication channel and format appropriate?

Scores are measured relative to a baseline expectation. The gap between actual and expected performance is the disconfirmation score. The quality system also tracks account health (rolling 30-day composite with churn risk detection) and provides circuit breakers that automatically pause AI handling when quality drops below configured thresholds.

Consumption and Billing

oHallo meters two usage units:

Unit	What it counts
conversation_resolved	A conversation resolved autonomously by the AI
agent_completed	A specialist agent execution (each dispatch counts separately)

Each account has a subscription plan with monthly allowances. Usage beyond the allowance incurs overage charges.

Marketplace

The marketplace is a catalog of pre-built MCP connectors for popular business tools (Shopify, HubSpot, Xero, NetSuite, and others). Marketplace connectors provide guided setup with OAuth or API key authentication, so you can connect a business system without building an MCP server. The marketplace also includes paid add-ons — specialised capabilities operated by oHallo (logistics tracking, address validation, company registry enrichment, live currency conversion) that tenants subscribe to without managing infrastructure.