SMS-To-Webhook

Telmetrics provides the capability to configure an inbound SMS webhook for Tracking Numbers and Number Pools. 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 and Number Pools 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:

FieldValue
sms_routes-> route_typewebhook
sms_routes-> route-> inbound_webhook_urlThe webhook URL where inbound text messages will be forwarded to (Example: https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5)

Using the end-points:
POST https://api.telmetrics.com/v3/api/groups/{groupid}/numbers
POST https://api.telmetrics.com/v3/api/{groupid}/numberpool

Submit a request similar to the following to enable the SMS-To-Webhook feature on your Tracking Number or Number Pool when provisioning:

{
    "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"
        }
    }
}
{
    "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:

{
    "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:

FieldValue
sms_routes-> route_typewebhook
sms_routes-> route-> inbound_webhook_urlThe webhook URL where inbound text messages will be forwarded to (Example: https://webhook.site/#/0a0b3cf6-a16f-4f89-a8ee-6f0ea7c41bf5)

Using the end-points:
PUT https://api.telmetrics.com/v3/api/numbers/{numberid}
PUT https://api.telmetrics.com/v3/api/numberpools/{numberpoolid}

Submit a request similar to the following to enable the SMS-to-Webhook feature on an existing tracking line:

{
    "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:

{
    "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:

{
    "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://api.telmetrics.com/v3/api/conversations/message/1eb41f07-3d39-490e-b6a6-0bea7104dfee"
      }
    ]
  }
}

Inbound SMS Webhook Field Definitions:

IdUnique Id of the request
AttemptCounter of how many times delivery of the message has been attempted
Properties-> CollectionTypeDefines the type of message. Will always be sent as: "SmsDetails"
Properties-> UTCDate/Time in UTC forwhen the message was queued for delivery
Properties-> OrganizationTelmetrics Organization ID
Notifications-> conversation_idUnique conversation id (GUID) that is created between a mobile number and a tracking number
Notifications-> message_idUnique message id (GUID) for the SMS message
Notifications-> number_idUnique id of the Tracking Number that was texted
Notifications-> fromMobile user's that send the SMS message in E.164 format
Notifications-> toTracking Number that received the SMS message in E.164 format
Notifications-> messageMessage sent by the mobile user
Notifications-> directionDirection of the message. Will always be "inbound" for this webhook
Notifications-> date_received_utcDate/Time in UTC that the message was received by Telmetrics
Notifications-> reply_postback_urlA 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 https://api.telmetrics.com/v3/api/conversations/{conversation_id}/messages

{
	"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:

{
  "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
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."
}
{
  "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."
}