Get Started
Log In

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. Visit Provisioning Telephone Numbers to learn more.

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.

Parameter Data Type Required Description
endpoints list of strings required The endpoint(s) (shortcodes and/or longcodes) which are to have their webhook updated

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
{
    "endpoints": [ "+12161112222" ],
    "webhook": "https://www.myserver.com/myapp"
}
Response Codes
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:

{
    "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.
Example Code
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 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 code configured in the Customer Portal. Use this code to verify the message was sent from IntelePeer.
Example
{
    "refid": "ABCDEF1234567890ABCDEF1234567890",
    "from": "+7708675309",
    "to": "+13038675309",
    "message": "Hello World!",
    "signature": "SECRET CODE"
}
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.

Cart Overview