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.
What an inbound message looks like
Section titled “What an inbound message looks like”| 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 |
Get inbound messages by webhook
Section titled “Get inbound messages by webhook”Subscribe an endpoint to message.received. Each inbound SMS is posted to it, signed, and retried until your endpoint answers 2xx.
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"]}'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const hook = await sf.webhooks.create({ url: 'https://acme.example/hooks/smsfabric', events: ['message.received'],});// Store this now: it is shown only once.console.log(hook.id, hook.signingSecret);import osimport requests
res = requests.post( "https://api.smsfabric.com/v1/webhooks", headers={"X-Api-Key": os.environ["SMSFABRIC_API_KEY"], "Idempotency-Key": "inbound-webhook-v1"}, json={"url": "https://acme.example/hooks/smsfabric", "events": ["message.received"]}, timeout=30,)res.raise_for_status()hook = res.json()print(hook["id"], hook["signingSecret"]) # store the secret now<?php$ch = curl_init('https://api.smsfabric.com/v1/webhooks');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'url' => 'https://acme.example/hooks/smsfabric', 'events' => ['message.received'], ]), CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: inbound-webhook-v1', ], CURLOPT_RETURNTRANSFER => true,]);$hook = json_decode(curl_exec($ch), true);echo $hook['id'] . ' ' . $hook['signingSecret'] . "\n"; // store the secret nowThe 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.
List inbound messages
Section titled “List inbound messages”To catch up after downtime, or without webhooks, list them:
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).
Reply from the same SIM
Section titled “Reply from the same SIM”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"}Forward inbound messages
Section titled “Forward inbound messages”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. |
STOP and START
Section titled “STOP and START”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 witherrorCode: "opted_out". START,UNSTOP,SUBSCRIBEorاشتراكremoves anopt_outentry. A blacklist entry you added by hand stays.
The inbound message itself is still stored and still triggers message.received.