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:

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)

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:

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)

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:


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