MessageHop

Home / Developers / Agent guide

Automate MessageHop with one Agent key

Create a least-privilege key in the MessageHop website, store it in your agent's secret environment, and call https://msghop.com/v1/agent/{operation}. MessageHop keeps Customer automation, super-admin automation, and message sending as three separate trust boundaries.

Machine-readable discovery

Read the capability registry for every Customer and Admin Agent operation, scope, permission, request identity, idempotency, reason, and approval policy, and the OpenAPI 3.1 contract for HTTP behavior. Do not guess operation names or underlying infrastructure.

1. Create the key in the website

  • Existing Customer Organization: sign in to Customer Console, open the Organization, then Agent keys.
  • First Organization: use Account → Agent keys for a one-day bootstrap key limited to account onboarding; after creation, replace it with an Organization key.
  • Super admin: complete MFA in Admin Console, then open Security → Agent keys.

For an Organization or Admin key, select one year, a specific expiry date, or an explicitly acknowledged never-expiring lifetime. One year is the recommended default. A chosen date expires at the end of that date in the website user's local timezone. A never-expiring key remains valid until it is revoked or its sponsor loses authority, so schedule reviews and revoke it when the workload retires. The raw key is shown once. MessageHop stores a verifier, not the raw secret, and rechecks the sponsoring user's current status and permission on every request.

export MESSAGEHOP_AGENT_KEY='<show-once-agent-key>'
chmod 600 "<your-secret-environment-file>"

Use a managed secret store for shared or production workloads. Never place an Agent key in browser code, a mobile app, source control, prompts, screenshots, support messages, or logs.

2. Make the first request

curl --fail-with-body --silent --show-error \
  https://msghop.com/v1/agent/getCustomerContext \
  -H "Authorization: Bearer ${MESSAGEHOP_AGENT_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: agent-context-0001' \
  --data '{"requestId":"agent-context-0001"}'

Requests and responses are direct JSON. Always inspect the HTTP status and success. A key can invoke an operation only when it is in the public registry, in that key's immutable allowlist, and still allowed by the sponsor's current authority.

3. Build the customer hierarchy

The canonical hierarchy is Organization → Brand → Project → Registered App. Reuse only IDs returned by MessageHop and include a stable request ID on every mutation.

# One-day account bootstrap key only
POST /v1/agent/createOrganization
{"requestId":"agent-org-0001","displayName":"Example Workspace","legalName":"Example Private Limited","brandName":"Example","projectName":"Messaging","environment":"test"}

# Organization-scoped Customer Agent key
POST /v1/agent/createCustomerBrand
{"requestId":"agent-brand-0001","organizationId":"<returned-organization-id>","name":"Retail"}

POST /v1/agent/createProject
{"requestId":"agent-project-0001","organizationId":"<organization-id>","brandId":"<brand-id>","name":"Order updates","environment":"test"}

POST /v1/agent/registerApp
{"requestId":"agent-app-0001","organizationId":"<organization-id>","brandId":"<brand-id>","projectId":"<project-id>","name":"Order service","platform":"server","restrictions":{}}

Use saveCustomerAppBillingProfile for bounded client billing identity metadata and saveOrganizationBudget for spending guardrails. The Organization remains the tenant and billing owner; neither operation creates money, changes price, or selects a provider.

4. Author and approve templates

  1. Use saveCustomerTemplateDraft for an SMS, email, or WhatsApp body and bounded variable schema.
  2. Use submitCustomerTemplateDraftForReview with the returned version.
  3. Poll listCustomerTemplateDrafts. Internal approval is always required.
  4. When that provider/channel requires external approval, MessageHop moves the template to pending_vendor for manual DLT/provider registration. Otherwise an authorized reviewer records the direct registration IDs.
  5. Use only an approved template returned by listCustomerMessageTemplates. The result contains the safe MessageHop ID, variable schema, and provider registration mapping needed by an integration.

Agents can define and submit templates, but cannot self-approve them. Provider secrets and raw provider request envelopes are never returned.

5. Create the sending credential

Call createServerCredential through the Customer Agent API with the exact Organization, Brand, Project, and Registered App scope; matching test/production environment; least-privilege actions and channels; expiry; label; and stable request ID. Capture that second show-once secret into the sending service's secret store.

export MESSAGEHOP_SENDING_KEY='<show-once-registered-app-key>'

curl --fail-with-body --silent --show-error \
  https://msghop.com/v1/auth/check \
  -H "Authorization: Bearer ${MESSAGEHOP_SENDING_KEY}" \
  -H 'X-Request-Id: sending-check-0001'

An Agent key cannot send messages. A Registered App sending key cannot create Organizations, Brands, Projects, apps, billing profiles, templates, or more credentials.

6. Send and observe

  • POST /v1/messages or POST /v1/otp requires the Registered App key, messages.send, an approved template, and a stable Idempotency-Key.
  • GET /v1/messages/{messageId} requires messages.read.
  • GET /v1/balances and GET /v1/usage require their explicit read grants.

All money is integer minor units with explicit currency. 202 ACCEPTED proves API acceptance only; provider delivery and billing finality are later, distinct states. Preserve the idempotency key, exact request material, request ID, message ID, and client reference for safe retries.

Admin Agent boundary

An Admin Agent key can invoke only the selected operations in operations.adminAgent. The sponsor must remain an enabled super admin with the current required permission. Maker/checker, reason, audit, version, provider-secret release, and financial controls continue inside the canonical handlers. Break-glass commands, credential lifecycle, and legacy mutations remain interactive-only.

Rotate, revoke, and fail closed

Rotate in the same website that issued the key, install the new show-once key, prove a harmless read, and revoke the old key with a reason. Customer rotation overlap is bounded to 24 hours; Admin overlap is bounded to one hour. Stop on 401, 403, tenant mismatch, idempotency conflict, missing price/provider/entitlement/balance, or unavailable audit/configuration evidence. Never retry with broader credentials or invent live values.

Download OpenAPI ↓