Send your first message
The integration runs on a trusted customer server. The credential and request identifiers below are placeholders; use the values issued for your own Project and Registered App.
Before you begin
- Create or select the Organization, Brand, and Project in the Customer Console.
- Register an app with platform Server and keep it active.
- Issue a credential with
messages.send, the required channel, and the correct test or production environment. - Copy the show-once secret directly into a server-side secret manager. Do not paste it into browser code, mobile code, logs, or a ticket.
- Confirm the account has an active price and provider route for the channel. MessageHop fails closed when a required price or route is unavailable.
1. Prepare the request
The credential fixes the Organization, Brand, Project, Registered App, actions, and allowed channels. The body repeats projectId and appId; they must exactly match that scope.
curl --request POST 'https://msghop.com/v1/messages' \
--header 'Authorization: Bearer <server-credential>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: checkout:order-8472:v1' \
--header 'X-Request-Id: checkout-order-8472' \
--data '{
"projectId": "project_checkout",
"appId": "app_server",
"channel": "sms",
"to": "+919876543210",
"templateId": "order_update",
"variables": {"order_id": "8472"},
"clientReference": "order-8472"
}'
2. Interpret the response
HTTP/2 202
{
"messageId": "msg_...",
"state": "ACCEPTED",
"acceptedAt": "2026-07-26T12:00:00.000Z",
"estimatedCharge": {
"amountMinor": 27,
"currency": "INR",
"status": "provisional",
"priceVersionId": "sms_inr_..."
},
"requestId": "checkout-order-8472"
}HTTP 202 means durable acceptance. The provider call happens asynchronously. It does not prove provider acceptance, delivery, recipient identity, or a final charge.
3. Read current state
Use a credential that includes messages.read and the same tenant/project scope.
curl 'https://msghop.com/v1/messages/msg_...' \ --header 'Authorization: Bearer <server-credential>' \ --header 'X-Request-Id: status-order-8472'
The response contains message ID, channel, current state, accepted and updated times, billing status, amount in integer minor units, currency, and request ID. A message outside the caller's scope is not enumerable.
4. Make production code reliable
- Generate the idempotency key from the business operation, not the HTTP attempt.
- Persist the key, message ID, request ID, and client reference together.
- On a timeout, repeat the same request and key; do not invent a new key.
- Do not retry a
409 idempotency_conflict; investigate the changed material. - Bound retries and preserve the original evidence for support.