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

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.

 

ParameterData TypeRequiredDescription
endpointslist of stringsrequiredThe endpoint(s) (shortcodes and/or longcodes) which are to have their webhook updated
 
see: Code Formatting
webhookstringrequiredThe 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

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

 

400One 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:

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

 

Bulk Request

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

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

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

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.

see: Securing Inbound SMS Webhooks
Example

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