Receiving SMS Messages

Atmosphere® Messaging makes it simple to receive SMS messages through your IntelePeer phone numbers. Messages received on your IntelePeer number are delivered via HTTP Post to the destination of your choice.

Telling Atmosphere® Messaging Where to Send Inbound Messages

You can configure a destination webhook for each of your phone numbers by:

  • Setting the webhook in the Customer Portal.
  • Setting the webhook by making a call to the configuration API.

If your telephone number or shortcode are enabled for Atmosphere® CPaaS, setting the webhook will result in inbound messages no longer being delivered to the CPaaS platform.

Configuring the Webhook for a Longcode or a Shortcode to Receive SMS Messages via API

URI

For EU numbers, POST to https://eu.api.intelepeer.com/_rest/v4/my/did/sms/webhook

For all other numbers, POST to https://api.intelepeer.com/_rest/v4/my/did/sms/webhook

Parameters

This API method requires an Authorization token. Learn more about the Authorization token in Atmosphere® API Authentication.

Parameter Data Type Required Description
endpoints list of STRING Required

The endpoint(s) (shortcodes and/or longcodes) which are to have their webhook updated

For more information see, Code Formatting
webhook STRING Required The URL to where inbound messages will be posted by IntelePeer

Note: If multiple endpoints are provided, the HTTP response status will be changed to 207 and the response will contain a list of responses, each one of which correlates to an endpoint in the request.

Example

Copy 
{
    "endpoints": [ "+12161112222" ],
    "webhook": "https://www.myserver.com/myapp"
}

 

Response Code Description
201 Webhook configuration successfully updated.
207 Multiple statuses for bulk request. A different status is provided per endpoint requested in the response.
400

One of the following errors occurred:

  • The telephone number is not in the proper E.164 format
  • The telephone number has not been enabled for SMS
400 Improperly-formatted URL provided for the webhook.
404 The telephone number is not available for use by the customer.

Example Responses

Single Request

Copy 
{
    "code": 201,
    "tnkey": "+12161112222",
    "webhook": "https://www.myserver.com/myapp",
    "provisioning": {
        "state": "provisioned"
    }
}

Bulk Request

Copy 
{
    "code": 207,
    "endpoints": [
        {
            "status": 201,
            "endpoint": "+12161112222",
            "response": {
                "tnkey": "+12161112222",
                "webhook": "https://www.myserver.com/myapp",
                "provisioning": {
                    "state": "provisioned"
                }
            }
        },
        {
            "status": 201,
            "endpoint": "+12161112223",
            "response": {
                "tnkey": "+12161112223",
                "webhook": "https://www.myserver.com/myapp",
                "provisioning": {
                    "state": "provisioned"
                }
            }
        }
    ]
}

Example Code

Copy 
import requests

###############################################################################
### update these accordingly                                                ###
###############################################################################
authtoken = 'INSERT_AUTH_TOKEN_HERE'
tn        = 'INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'
webhook   = 'INSERT_WEBHOOK_URL_HERE'

###############################################################################
### leave these alone                                                       ###
###############################################################################
payload   = { 'webhook': webhook, 'endpoints': [ tn ] }
url       = "https://api.intelepeer.com/_rest/v4/my/did/sms/webhook"
hdrs      = {
    'Content-Type': "application/json",
    'Authorization': 'Bearer {}'.format(authtoken)
    }

###############################################################################
### execute the task and parse results                                      ###
###############################################################################
response = requests.post(url, json=payload, headers=hdrs)
print u'{}: {}'.format('OK' if response else 'ERROR', response.text )

Learn more about webhook security in Securing Inbound SMS Webhooks.

Checking the Webhook for Receiving SMS Messages via API

URI

GET to https://api.intelepeer.com/_rest/v4/my/did/sms/webhook?endpoint=%2B{tn}

  • “%2B” is the URL-encoded ‘+’ component of E.164 format.
  • {tn} is the phone number being queried, including the leading country-code

For example, you would retrieve the webhook for +12161112222 by GET-ing from the URL https://api.intelepeer.com/_rest/v4/my/did/sms/webhook?endpoint=%2B12161112222

Parameters

None, however this API method requires an Authorization token. Learn more about the Authorization token in Atmosphere® API Authentication.

Response Example

Copy 
{
    "code": 200,
    "tnkey": "+12161112222",
    "webhook": "https://www.yourcompany.com/sms/webhook",
    "provisioning": {
        "state": "provisioned"
    }
}

Note: If multiple endpoints are provided, the HTTP response status will be changed to 207 and the response will contain a list of responses, each one of which correlates to an endpoint in the request.

Response Variable Values

Variable Available Values
state

requested

provisioning

provisioned

derequested

deprovisioning

error

Response Codes

Response Code Description
200 Webhook returned in the response.
400 The telephone number is not in the proper E.164 format.
404 The telephone number is not available for use by the customer.

Example Code

Copy 
import requests
from urllib import quote
###############################################################################
### update these accordingly                                                ###
###############################################################################
authtoken = 'INSERT_AUTH_TOKEN_HERE'
tn        = 'INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'

###############################################################################
### leave these alone                                                       ###
###############################################################################
url = "https://api.intelepeer.com/_rest/v4/my/did/sms/webhook?endpoint={}".format(quote(tn)) 
hdrs = {
    'Content-Type': "application/json",
    'Authorization':  {}'.format(authtoken)
    }

###############################################################################
### execute the task and parse results                                      ###
###############################################################################
response = requests.get(url, json={}, headers=hdrs)
print u'{}: {}'.format('OK' if response else 'ERROR', response.text )

Receiving Messages via API

When a message is received on an SMS-enabled number, Atmosphere® Messaging attempts to deliver the message to the webhook URL you specified when configuring the number.

The message is delivered as a POST to your URL.

Parameters

The following data is delivered in the body of the POST:

Parameter Data Type Description
refid STRING 32-character identifier of this message. This identifier can also be found in the MDR.
from STRING The number from which the text was sent in E.164 format. This can also be in short code format {countrycode}-{shortcode}; example: 1-1234.
to STRING The number to which the text was sent in E.164 format. This can also be in short code format {countrycode}-{shortcode}; example: 1-1234.
message STRING The contents of the text message.
signature STRING The shared secret configured in the Customer Portal or by API. Use this code to verify the message was sent from IntelePeer. For more information, see: Securing Inbound SMS Webhooks

Example

Copy 
{
    "refid": "ABCDEF1234567890ABCDEF1234567890",
    "from": "+7708675309",
    "to": "+13038675309",
    "message": "Hello World!",
    "signature": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Behavior

Atmosphere® Messaging expects an HTTP 200 response from your application. This response indicates that you received the message successfully.

When an HTTP 200 is not received from your application, the following will happen:

  • Atmosphere® Messaging will attempt to resend the message, up to a total of 5 attempts.
  • Each failed attempt will be reflected as a failed attempt in the SMS reporting dashboard.