Skip to content

Receive messages

Every SMS that arrives on a SIM in a paired Android phone is uploaded to SMSFabric as an inbound message with direction: "inbound" and status: "received". Use it for replies, two-way support, keyword handling, or to read codes that services send to your numbers.

Field Value
direction inbound
status received
from The sender, in E.164 when it is a phone number, or an alphanumeric sender name such as ACME
to Your SIM’s number, when the phone knows it; otherwise an empty string
deviceId, simId The phone and SIM it arrived on
provider device
body The text

Subscribe an endpoint to message.received. Each inbound SMS is posted to it, signed, and retried until your endpoint answers 2xx.

Terminal window
curl https://api.smsfabric.com/v1/webhooks \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: inbound-webhook-v1" \
-d '{"url": "https://acme.example/hooks/smsfabric", "events": ["message.received"]}'

The delivery your endpoint receives:

{
"id": "evt_d8f1h3j5l7n9p2r4t6v8x1z3",
"type": "message.received",
"createdAt": "2026-11-19T11:02:41.903Z",
"orgId": "org_n5q8t1w4z7c0f3i6l9o2r5u8",
"data": {
"id": "msg_h3j5l7n9q2s4u6w8y1a3c5e7",
"direction": "inbound",
"to": "+201009876543",
"from": "+201001234567",
"body": "Can I change my delivery to Thursday?",
"status": "received",
"segments": 1,
"encoding": "GSM7",
"deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9",
"simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6",
"provider": "device",
"errorCode": null,
"createdAt": "2026-11-19T11:02:41.880Z",
"sentAt": null,
"deliveredAt": null,
"metadata": null
}
}

Always verify the signature before you trust the body.

To catch up after downtime, or without webhooks, list them:

Terminal window
curl "https://api.smsfabric.com/v1/messages?direction=inbound&from=2026-11-19T00:00:00Z" \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

GET /v1/messages returns newest first; follow nextCursor for more (see Pagination).

To answer on the number the customer wrote to, send with the inbound message’s simId:

{
"to": "+201001234567",
"body": "Done. Your delivery is now on Thursday.",
"simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6"
}

Under Settings → Sending (or PATCH /v1/preferences), forwardInbound copies every inbound SMS without code:

Field What happens
email An email with the sender, your number and the text.
phone An SMS to this number, Fwd from <sender>: <text>, sent through your phones.
webhook One unsigned POST of a message.received payload, with no retries.

When an inbound message’s whole text is a stop word, SMSFabric opts the sender out for you:

  • Stop words: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, and Arabic إيقاف, إلغاء, توقف. Case, spacing and trailing punctuation are ignored.
  • The number is added to the blacklist with source: "opt_out", the matching contact is marked opted out, and campaign messages to it that no phone has taken yet are blocked with errorCode: "opted_out".
  • START, UNSTOP, SUBSCRIBE or اشتراك removes an opt_out entry. A blacklist entry you added by hand stays.

The inbound message itself is still stored and still triggers message.received.