Documentation.
Reference material for building with the Hamia API. For a quick start, generate a test key from the developer dashboard and follow Getting Started below.
Getting Started
Introduction
Hamia API gives developers and agencies direct access to the same AI engine that powers Hamia Agent. Every request is scoped to a business, authenticated with an API key, and processed through the same Business Knowledge Engine, Action Layer, and escalation logic Hamia Agent itself uses, so a response built through the API behaves exactly like a response sent through the dashboard.
Authentication
Every request carries your API key as a bearer token in the Authorization header. Test keys are prefixed hma_test_, live keys hma_live_. Keys are shown once at creation and stored as a hash, never in plain text, so keep a copy somewhere safe when you generate one.
Your first API call
Generate a test key from the developer dashboard, then call the agent respond endpoint with a businessId, a platform, a customerId, and a message. The response comes back as JSON with the assistant's reply, generated through the exact same pipeline a real customer conversation goes through.
Sandbox vs Production
Test keys run against a sandbox environment with a 1,000 call monthly ceiling and no domain verification required. Live keys run against production and require verifying a domain you control, either with a DNS TXT record or a meta tag, before they can be issued.
Core Concepts
Agents
An agent is the AI assistant configured for a specific business: its personality, its knowledge, and the actions it's allowed to take. Every API call operates on behalf of one agent, identified by that business's businessId.
Conversations
A conversation is one customer thread on one platform, identified by a customerId. The API tracks conversation history the same way the dashboard does, so a follow up message from the same customer continues the same thread rather than starting a new one.
Knowledge Base
A business's knowledge base, its FAQs, products, pricing, and policies, shapes every response the API returns. Knowledge base content is managed through the business's own dashboard, not through the API directly.
Webhooks
Register a webhook URL to receive real time events as they happen, rather than polling for them. Every webhook delivery is signed so you can verify it actually came from Hamia.
API Reference
Authentication
How API keys are issued, verified, and rotated, and what happens when a key is revoked mid request.
Messages
Send a message on behalf of a customer and receive the assistant's reply, or fetch the message history for a given conversation.
Conversations
List, fetch, and update conversation state, including manually pausing or resuming the AI for a specific conversation.
Knowledge Base
Read a business's active knowledge base entries. Writing new entries currently happens through the dashboard, not this endpoint.
Platforms
Check which platforms are connected and active for a given business, and their current webhook verification status.
Webhooks
Register, test, and remove webhook subscriptions, and review recent delivery logs for a given endpoint.
Analytics
Pull conversation, platform, and language breakdowns for a business over a given date range.
SDKs
JavaScript
An official Node.js and browser compatible client library.
Python
An official client library for server side Python integrations.
PHP
An official client library for PHP based backends.
Guides
Connecting a business's WhatsApp number and verifying the webhook.
Connecting an Instagram business account for DM and comment handling.
Website Chat Widget
Embedding the Hamia Agent chat widget on your own website, including its voice to text input.
Payment Integration
How the send payment link action uses a business's own saved payment details.
Changelog
Changelog
A running log of API changes. Nothing has shipped to the public API yet, this section will list real, dated entries once it does.
Ready to build? Get a free sandbox key and start making calls.
Go to developer dashboard