MessageHop

Home / Developers / Agent guide

Build through the MessageHop API

Use only https://msghop.com. A user access token manages account resources; a scoped Registered App credential operates the messaging data plane. Neither principal can expand its own authority.

Machine-readable contracts

Download the OpenAPI 3.1 contract and capability registry. Both describe only supported MessageHop concepts, principals, paths, and operation names.

1. Create a user session

POST https://msghop.com/v1/sessions
Content-Type: application/json
X-Request-Id: agent-session-0001

{"email":"operator@example.com","password":"<password>"}

Protect the returned access and refresh tokens. Never write passwords, tokens, OTP values, invitation tokens, show-once credentials, recipients, or message content to agent logs. Refresh with POST /v1/sessions/refresh.

2. Call the Customer control API

POST https://msghop.com/v1/control/getCustomerContext
Authorization: Bearer <access-token>
Content-Type: application/json
X-Request-Id: agent-run-0001

{"requestId":"agent-run-0001"}

Requests and responses are direct JSON. Inspect HTTP status and success. MessageHop rechecks session activity, email verification, membership, tenant lifecycle, resource ancestry, and permission for every operation.

3. Register the integration

  1. Call getCustomerContext and reuse server-returned Organization, Brand, and Project IDs.
  2. If authorized onboarding is required, call createOrganization, then reload context.
  3. Call registerApp; backend integrations use platform server.
  4. Call createServerCredential with matching scope/environment, least-privilege actions/channels, expiry, label, and stable request ID.
  5. Put the show-once secret directly into a managed server-side secret store.
  6. Verify it with GET /v1/auth/check.
  7. Submit a test message with a stable Idempotency-Key and read its status.

4. Verify effective Registered App authority

GET https://msghop.com/v1/auth/check
Authorization: Bearer mh_<environment>_<selector>_<secret>
X-Request-Id: integration-check-0001

A successful response returns only the server-owned Organization, Brand, Project, Registered App, environment, actions, and channels. 401 means authentication failed. 403 means the scope is not active or authorized.

Customer operation directory

Prefix each name with POST /v1/control/.

  • Context: getCustomerContext, createOrganization
  • Apps: registerApp
  • Credentials: createServerCredential, listServerCredentials, rotateServerCredential, revokeServerCredential
  • Billing/history: getCustomerBalance, listCustomerBillingActivity, listCustomerMessageHistory
  • Budgets: listOrganizationBudgets, saveOrganizationBudget
  • Team: invite, list, accept, and revoke Organization membership
  • Support: tickets, customer-visible replies, safe attachments, and chat

Workforce and platform-administration commands are deliberately excluded from application integrations.

Data-plane actions

  • messages.send → POST /v1/messages
  • messages.read → GET /v1/messages/{messageId}
  • billing.read → GET /v1/balances
  • usage.read → GET /v1/usage

All money is integer minor units with explicit currency. 202 ACCEPTED is not delivery or final billing. Preserve idempotency key, request material, request ID, message ID, and client reference for safe retries.

Fail closed

Stop on missing authorization, tenant mismatch, inactive scope, idempotency conflict, unavailable price/provider/entitlement/balance, or a production step-up requirement. Never retry with broader credentials or invent live operational values.

Download OpenAPI ↓