--- updatedAt: 2025-11-06T17:43:57.000Z agentTools: projectIndex: https://developer.marchex.io/llms.txt --- # SMS-To-Webhook Marchex provides the capability to configure an inbound SMS webhook for **[Tracking Numbers](https://developer.marchex.io/docs/creating-a-tracking-number)** and **[Number Pools](https://developer.marchex.io/docs/creating-a-number-pool)**. When configured, all inbound SMS messages sent to your tracking numbers configured to use SMS webhooks will be pushed via HTTP/HTTPS to the configured webhook payload URL. This feature is enabled via **[Tracking Number](https://developer.marchex.io/docs/creating-a-call-tracking-number)** and **[Number Pools](https://developer.marchex.io/docs/creating-a-number-pool)** end-points, and can be configured during the provisioning of a Tracking Number or applied later as an update. ## Creating Number/Number Pools with SMS-to-Webhook To create a Tracking Number, or Number Pool with the SMS-to-Webhook feature enabled, you must enable it in the SMS-Routing section of your request. The following fields are required for this feature:
Field Value
sms\_routes-> route\_type webhook
sms\_routes-> route-> inbound\_webhook\_url The webhook URL where inbound text messages will be forwarded to (Example: [https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5](https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5))
Using the end-points:\ **POST**\ **POST** Submit a request similar to the following to enable the SMS-To-Webhook feature on your Tracking Number or Number Pool when *provisioning*: ```json Create Tracking Line with SMS-to-Webhook { "name": "ABC Company - Main Business Line", "phone_number_request": { "match_type": "Tollfree" }, "sms_routes": { "route_type": "Webhook", "route": { "inbound_webhook_url": "https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5" } }, "call_routes": { "route_type": "Basic", "route": { "termination_number": "4075552958" } } } ``` ```json Create Number Pool with SMS-to-Webhook { "name": "ABC Company - Google AdWords Attribution", "phone_number_request": { "match_type": "localtonumber", "local_to_number": "2123932233" }, "match_period": 30, "quantity": 3, "replacement_configuration": { "numbers_to_replace": [ "905219CARS", "4045553434" ], "tracking_sources": [ { "referrer_domain": "any", "url_triggers": [ "gclid=%" ] } ] }, "sms_routes": { "route_type": "Webhook", "route": { "inbound_webhook_url": "https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5" } }, "call_routes": { "route_type": "Basic", "route": { "termination_number": "4165551234" } } } ``` A successful post will result in the creation of a tracking number/number pool with SMS-To-Webhook capabilities: ```json Response { "id": 8848979, "group_id": 11812328, "name": "ABC Company - Main Business Line", "status": "Active", "phone_number": "8003979906", "created_datetime": "2018-07-06T15:23:17.403", "modified_datetime": "2018-07-09T09:17:05.207", "sms_routes": { "route_type": "Webhook", "route": { "inbound_webhook_url": "https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5" } }, "call_routes": { "route_type": "Basic", "route": { "id": 30703449, "termination_number": "4075552958" } } } ``` ## Updating existing Number/Number Pools to use SMS-to-Webhook To update an existing Tracking Number, or Number Pool to use the SMS-to-Webhook feature enabled, you must enable it in the SMS-Routing section of your request. The following fields are required for this feature:
Field Value
sms\_routes-> route\_type webhook
sms\_routes-> route-> inbound\_webhook\_url The webhook URL where inbound text messages will be forwarded to (Example: [https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5](https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5))
Using the end-points:\ **PUT**\ **PUT** Submit a request similar to the following to enable the SMS-to-Webhook feature on an existing tracking line: ```json Update Tracking Number/Pool for SMS-to-Webhook { "sms_routes": { "route_type": "Webhook", "route": { "inbound_webhook_url": "https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5" } } } ``` A successful post will result in the creation/update of a tracking number with SMS-To-Webhook capabilities: ```json Response { "id": 8848979, "group_id": 11812328, "name": "ABC Company - Main Business Line", "status": "Active", "phone_number": "8003979906", "created_datetime": "2018-07-06T15:23:17.403", "modified_datetime": "2018-07-09T09:17:05.207", "sms_routes": { "route_type": "Webhook", "route": { "inbound_webhook_url": "https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5" } }, "call_routes": { "route_type": "Basic", "route": { "id": 30703449, "termination_number": "4075552958" } } } ``` ## Receiving Inbound SMS Webhooks All text messages sent to Tracking Numbers and Number Pools enabled with the SMS-to-Webhook feature, will be posted to the URL configured in the "inbound\_webhook\_url" field. In the event that the URL is not accessible, 3 retry attempts will be made to deliver the message. Below is an example of a Webhook POST: ```json SMS-to-Webhook POST body { "Id": "0f3f46c50d434dec930fcd3190b3e101", "Attempt": 1, "Properties": { "CollectionType": "SmsDetails", "UTC": "2018-11-05T21:20:38", "Organization": "4455", "RequestId": "83a45460-b2f0-4823-8aa2-0cf3ef7aa93f" }, "Notifications": [ { "action": "SmsDetails.smsOutboundRelay", "conversation_id": "1eb41f07-3d39-490e-b6a6-0bea7104dfee", "message_id": "6277dee2-f188-40ed-a9ee-4dd17857550d", "number_id": 8960460, "from": "+19055802958", "to": "+12012663293", "message": "What hours are you open today?", "direction": "Inbound", "date_received_utc": "2018-11-05T21:20:36.100", "reply_postback_url": "https://edgeapi.marchex.io/marketingedge/v5/api/conversations/message/1eb41f07-3d39-490e-b6a6-0bea7104dfee" } ] } } ``` Inbound SMS Webhook Field Definitions:
Id Unique Id of the request
Attempt Counter of how many times delivery of the message has been attempted
Properties-> CollectionType Defines the type of message. Will always be sent as: "SmsDetails"
Properties-> UTC Date/Time in UTC forwhen the message was queued for delivery
Properties-> Organization Marchex Organization ID
Notifications-> conversation\_id Unique conversation id (GUID) that is created between a mobile number and a tracking number
Notifications-> message\_id Unique message id (GUID) for the SMS message
Notifications-> number\_id Unique id of the Tracking Number that was texted
Notifications-> from Mobile user's that send the SMS message in E.164 format
Notifications-> to Tracking Number that received the SMS message in E.164 format
Notifications-> message Message sent by the mobile user
Notifications-> direction Direction of the message. Will always be "inbound" for this webhook
Notifications-> date\_received\_utc Date/Time in UTC that the message was received by Marchex
Notifications-> reply\_postback\_url A post-back URL that can be used to send reply SMS messages
## Sending Outbound SMS We also provide the ability to send an SMS message as a reply to an existing conversation. In every webhook message, a 'reply\_postback\_url' is supplied that can be used to send an SMS message to a mobile user. This URL is unique between a consumer number, and a tracking number. You may use the following end-point to send SMS replies to an existing SMS conversation: **POST** ```json Send SMS Message Request { "message": "We are open from 10am to 11pm, Monday to Saturday" } ``` If your request is successful, you will receive an HTTP 200 OK, similar to the following: ```json OK: HTTP 200 -Message received { "conversation_id": "1eb41f07-3d39-490e-b6a6-0bea7104dfee", "message_id": "1e338b1f-3e62-4743-ac43-717ab3941399", "number_id": 8960460, "from": "+12015553293", "to": "+19055552958", "message": "We are open from 10am to 11pm, Monday to Saturday", "direction": "Outbound", "date_sent_utc": "2018-11-05T21:23:26.464" } ``` Outbound SMS messages can fail for the following reasons: * The mobile user has declined to receive any further SMS messages from the tracking number * The mobile user has not explicitly opted in to receive SMS messages ```json ERROR: HTTP 400 - User opted out STOP : HTTP BadRequest 400 { "conversation_id": "1eb41f07-3d39-490e-b6a6-0bea7104dfee", "number_id": 8960460, "from": "+12015553293", "to": "+19055552958", "message": "We are open from 10am to 11pm, Monday to Saturday", "direction": "Outbound", "error_code": 11503, "error_message": "SMS user has decline to receive any futher requests. Your message will not be sent." } ``` ```json ERROR: HTTP 400 - User opt-in Pending { "conversation_id": "1eb41f07-3d39-490e-b6a6-0bea7104dfee", "number_id": 8960460, "from": "+12015553293", "to": "+19055552958", "message": "We are open from 10am to 11pm, Monday to Saturday", "direction": "Outbound", "error_code": 11502, "error_message": "SMS user has not yet accepted the opt-in request. Your message will not be sent." } ```