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