AI agents | Hams AI Docs

AI agents are designed, tested and updated in the HAMS platform: their prompts or conversation flow, voice, call behaviour, security settings and post-call analysis all live there, and so does every change you make to them. The API does not create or edit agents. What your integration needs is the agent ID, and the platform gives you that.

Finding an agent’s ID

Open the agent in the platform and copy its ID from the agent’s page. Chat agents and voice agents are separate agents with separate IDs; an integration that does both needs one of each.

Where the ID is used

Agent	What you want to do	Where the ID goes
Chat	Run chat sessions from your own systems	`/ai-agents/{agent_id}/chat/…` with a secret key; see Chat sessions and widget
Chat	Chat from your web pages, or embed the widget	`/v1/ai-agents/{agent_id}/chat/…` and `/v1/ai-agents/{agent_id}/widget-config` with a public key
Chat	Change how the widget looks and behaves	`PUT /ai-agents/{agent_id}/widget-config` with a secret key
Voice	Answer inbound calls	Assign the agent to a number or a call flow in the platform; there is nothing to call
Voice	Dial a list of numbers	Set the agent as the outbound agent of a telephony extension in the platform, then create outbound batches on that extension

Events such as completed calls and chat sessions are delivered to the webhook configured on the agent in the platform, so a change of agent behaviour never requires a change on your side.

Keep the agent ID in configuration, not in code. Swapping an integration to a new agent, for example a new version you tested in the platform, is then a configuration change.