Receive inbound SMS

POSTWebhook receiveryour callbackUrlAPI v1

Strategic Mobile sends a webhook POST request to your callbackUrl when an inbound SMS message is received. The request body follows the InboundSmsWebhook schema and is sent as Content-Type: application/json. Your endpoint should return any 2xx response after it accepts the message.

Overview

This page documents the inbound webhook contract for SMS and recommended handling behavior. Your inbound webhook URL is configured on your SMS service plan; contact support to set or change it. Acknowledge each inbound event with a 2xx response after you accept it. Webhook endpoint authentication is customer-controlled: if your inbound SMS webhook endpoint requires authentication, configure the required headers or credentials for your account or webhook URL. SMSCPR does not require a fixed authentication scheme for inbound SMS webhooks.

Webhook request

Inbound events are sent as an HTTP POST with Content-Type: application/json to your configured callback URL.

POST https://client.example.com/sms/inbound
Content-Type: application/json

{
  "accountId": "111111111111111111111111",
  "servicePlanId": "222222222222222222222222",
  "msgId": "019f0000-aaaa-bbbb-cccc-000000000001",
  "channel": "SMS",
  "direction": "MO",
  "from": "+15550002222",
  "to": "+15550001111",
  "keyword": "Need",
  "body": "Need status update for order 12345",
  "receivedAt": "2026-06-22T05:10:03.120Z"
}

Webhook payload

Content-Type: application/json

{
  "accountId": "111111111111111111111111",
  "servicePlanId": "222222222222222222222222",
  "msgId": "019f0000-aaaa-bbbb-cccc-000000000001",
  "channel": "SMS",
  "direction": "MO",
  "from": "+15550002222",
  "to": "+15550001111",
  "keyword": "Need",
  "body": "Need status update for order 12345",
  "receivedAt": "2026-06-22T05:10:03.120Z"
}

Payload fields

Field	Type	Description
`accountId`required	`string`	Resolved account identifier (business partner) that owns the inbound message.
`servicePlanId`required	`string`	Service plan associated with the inbound message.
`msgId`required	`string`	Unique message identifier.
`channel`required	`string`	Message channel. Value for this endpoint: SMS.
`direction`required	`string`	Message direction. Value for inbound messages: MO.
`from`required	`string`	Sender MSISDN in E.164 format.
`to`required	`string`	Receiving SMS number in E.164 format.
`keyword`	`string`	Matched keyword, or first keyword/token if applicable. Present when the inbound message matches a configured keyword.
`body`required	`string`	Inbound SMS text.
`receivedAt`required	`string<date-time>`	Timestamp when the inbound message was received (ISO 8601, UTC).

Example inbound message

{
  "accountId": "111111111111111111111111",
  "servicePlanId": "222222222222222222222222",
  "msgId": "019f0000-aaaa-bbbb-cccc-000000000001",
  "channel": "SMS",
  "direction": "MO",
  "from": "+15550002222",
  "to": "+15550001111",
  "keyword": "Need",
  "body": "Need status update for order 12345",
  "receivedAt": "2026-06-22T05:10:03.120Z"
}

Recommended response

Return a fast 200 OK after minimal validation and durable acceptance (storage/queue). An empty body or a minimal JSON acknowledgement is sufficient. Avoid blocking on additional business processing in the request path.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true
}

Delivery/retry notes

Respond quickly with a 200 OK after basic validation so the delivery is acknowledged.
Use msgId as the idempotency key; treat webhook handling as idempotent in case the same message is delivered more than once.
Use keyword for routing when present.
Persist or queue first, then process the message asynchronously to reduce timeout risk.
Your inbound webhook URL is configured on your SMS service plan; contact support to set or change it.