Set up Hexagon with an AI agent
Developer setup lets you create a scoped Hexagon key for an agent helping configure an existing product. The public contract currently lists personal Milo and workspace WhatsApp Sales. Ordinary visual setup remains available at Start.
This interface reads product and billing status, prepares supported setup changes and returns hosted owner actions. It is not a general model API or an unrestricted connection to your business data.
Choose the correct identity
A Milo key is personal and tied to the person's Milo account. A Sales key is scoped to one selected workspace and product. Issuing a workspace key requires the appropriate owner or administrator authority.
Create the key through developer setup or Agent access. Store the hx_agent_ value in a secure environment variable such as HEXAGON_API_KEY; do not paste it into chat or place it in a URL, frontend code or logs. The full key is shown once. A merchant hx_live_ key is a different credential and cannot replace it.
If a key is exposed or no longer needed, revoke it in Agent access. Workspace keys belong to the workspace: leaving as the original creator is not a substitute for revocation. Current authority is checked on requests, and a workspace key can act through the current owner when its creator is no longer an owner or administrator.
Grant only the required scopes
| Scope | Authority |
|---|---|
products:read |
Read the selected product's status, setup version and next owner actions. |
billing:read |
Read the selected product's billing readiness and applicable agreement. |
checkout:create |
Prepare an eligible unpaid hosted checkout or management link for the customer. |
setup:write |
Read and save supported Sales drafts and reviewed instructions; prepare its inactive configuration. |
products:activate |
Activate, pause or retry ready Sales work under the workspace's accepted agreement. |
A checkout scope does not authorize payment. Activation can start real, billable automation under already accepted terms and therefore needs an explicit instruction matching the intended action.
Use the current public contract
Read the product catalog, OpenAPI reference and published agent setup guide. Authenticate with a bearer key only to the documented API base:
https://api.joinhexagon.com/api/v1/agent-commerce
Use milo or sales_v3 exactly as the product identifier. Start with GET /products/{product} and, if authorized, GET /billing/{product}. Follow returned owner links for missing account linking, provider authorization, business verification or billing consent.
For Sales, read the supported setup state, preserve the current version as expectedVersion, and submit only fields the OpenAPI permits. Save reviewed instructions only after the customer has reviewed them. Prepare verifies prerequisites without activating the assistant. Activate only when the current requirements are ready and the customer has authorized that outcome.
Shopify and Meta authorization, dedicated iMessage connection consent, business verification submission and new billing acceptance remain in the human setup flow. Never request provider secrets or raw payment card details in chat.
Handle retries without duplicating actions
On a version conflict, read the current state and reconcile the intended change. Retry activation uses the saved version; it does not create a different intent. operationPending: true means the result is unconfirmed. A pending pause is not a confirmed stop.
For an eligible checkout request, preserve its UUID requestKey and selection on retry. Inspect the returned result: a management link is not a purchase, a hosted checkout still needs the customer, and a completed-payment receipt should not lead to a second payment request. Respect any Retry-After response.
Keep product billing separate
For Milo, resolve an existing account link and subscription first. If the company already covers the person, do not offer a duplicate plan. Use the returned management or hosted subscription destination and its current terms.
Sales outcome enrollment uses the exact owner link returned by billing. Existing prepaid agreements have separate credit and automatic-reload terms. Do not buy credits as a prerequisite for an outcome agreement or treat an old balance as proof that a new agreement is active.