SMS / MMS Message Management

As a best practice, we recommend securing your inbound SMS/MMS webhooks to ensure that they are being triggered by IntelePeer and not a third party. There are two ways you can secure your webhooks, which are not mutually exclusive:

• Securing inbound SMS/MMS through basic authentication
• Validating that an inbound SMS/MMS originates from IntelePeer

Securing Inbound SMS/MMS Through Basic Authentication

The first way to secure your inbound webhook is entirely in your hands.

IntelePeer supports webhooks which contain basic authentication built into the URL. For example: https://tomhanks:megryan@joeversusthevolcano.org/sms-app/secure-webhook.php

Because the URL contains the credentials, it is HIGHLY recommended (but not currently required) that the HTTPS protocol be used, which will naturally encrypt the credentials during transmission. Since IntelePeer is now in possession of those credentials, it is also recommended that any endpoint on your web server OTHER than the inbound-sms-webhook should not use the same credentials.

You can also configure your authorized webhook using the IntelePeer SMS/MMS Management App:

• Log into your customer account at customer.intelepeer.com.
• Click the webhook icon next to the number and enter in the URL.

Validating an Inbound SMS/MMS Originates from IntelePeer

On the other hand, if you are worried that somebody is trying to pretend to be IntelePeer and send inbound SMS/MMS messages to your webhook maliciously, but you have opted not to use basic authentication (or your basic authentication credentials are compromised), don’t fret, this is where your account secret comes into play.

If your account secret is set, IntelePeer will supplement each inbound-sms message with a signature. This signature is an hmac-derivation from three things:

• The reference ID of the SMS/MMS messages
• The message body
• Your account secret

The first two are part of the payload sent to your webhook. The account secret is something that only you and IntelePeer are aware of and is not part of the payload by design.

Note: The maximum length for a secret is 32 ASCII characters.

To calculate the expected signature, you can execute the following in your language of choice. Once you have the expected signature, you can compare it to the actual signature provided by IntelePeer and if the two match, you have validated the authenticity of the message.

Example Code

1
2
3
4
5
6
7
8
9
10
11
12
13
import hmac, hashlib

  def get_expected_signature(message_body: str, reference_id: str, account_secret: str):    
     
  The string to be signed is a concatenation of the reference ID and the body.
     
  signing_string: bytes = reference_id.encode() + message_body.encode()
  resulting_hmac = hmac.new(
  account_secret.encode(),
  signing_string,
  hashlib.sha1,
  )
  return resulting_hmac.hexdigest()

A concrete example of using this function is below:

Example Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
ACCOUNT_SECRET = 'shhhhhhhhhh!'

  INBOUND_SMS = {
  'to': '',
  'message': 'This is a security test',
  'from': '',
  'refid': 'SM5ACE21340001006568000044A9F800',
  'signature': '67e6b7fdbed0fd11cf90de310d3bb8c0cca5650e',
  }

  expected_signature = get_expected_signature(
  INBOUND_SMS['message'],
  INBOUND_SMS['refid'],
  ACCOUNT_SECRET
  )
  authenticated = expected_signature == INBOUND_SMS['signature']

  print('authenticated' if authenticated else 'not authenticated')

Note

• Messages are signed at the time of receipt. While changing your account secret is an atomic action, any messages that have already been signed but not yet delivered, will not be re-signed with the new signature prior to delivery.
• This nifty tool is a quick validator for your code-correctness: Freeformatter (select SHA1)
• If just the message body was used as the string to be signed, then two identical messages would produce identical signatures and with enough data points, the security of the account secret could be compromised. Thus, we concatenate the reference ID and the message body together as the string to be signed, which results in unique signatures, even in the case of identical messages.

All phone numbers on the IntelePeer network can be used to send and receive SMS/MMS messages. You can enable SMS/MMS over your phone number by:

• Configuring a number through the IntelePeer Customer Portal
• Configuring a number through the API

This page discusses SMS/MMS enablement via API for long codes only. Enablement allows you to send SMS/MMS messages using a phone number (long code) using the SMS/MMS send API, and also makes the webhook API available for use on the long code to receive SMS/MMS messages.

Short codes can be ordered by contacting IntelePeer directly. Learn more about number enablement through the IntelePeer Customer Portal in the SMS/MMS Messaging Quick Start Guide.

Configuring Numbers via API

Configuring a phone number through the API requires the following steps:

1. Explicitly enable SMS/MMS for the phone number
2. Create and set the webhook for processing of inbound SMS/MMS messages

Checking Number Configuration via API

You can check the current configuration of a number through the API:

• Get the SMS/MMS enablement status of a phone number
• Get the current webhook for a phone number

Enabling SMS/MMS for Single Phone Number via API

URI

POST https://api.intelepeer.com/_rest/v4/my/did/sms/provision

Parameters

This API method requires an Authorization Token. To learn more about the Authorization token, check out API Authentication.

Request Example

1
2
3
{
  "endpoints": [ "+13031112222" ]
  }

Response Example

1
2
3
4
5
6
{
  "code": 202,
  "provisioning": {
  "state": "requested"
  }
}

Behavior

Enabling of numbers for SMS/MMS typically happens within minutes; however, there are some cases where a number may take longer to enable:

• Toll free numbers for which IntelePeer is not the resporg
• DIDs and Toll Free Numbers already being used for SMS/MMS within another service

Example Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import requests

  # update these accordingly 
  AUTH_TOKEN = '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/provision' 
  headers = { 
  'Authorization': 'Bearer {}'.format(AUTH_TOKEN),
  'Content-Type': 'application/json',  
  } 
  json = {
  'endpoints': [TN],
  } 

  # execute the task and parse results 
  response = requests.post(url, json=json, headers=headers) 
  print('{}: {}'.format(response.reason, response.text))

Checking the SMS/MMS Enablement Status of a Phone Number

URI

GET https://api.intelepeer.com/_rest/v4/my/did/sms/provision?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 configure the webhook for +17208675309 by GET-ing from the URL:

GET https://api.intelepeer.com/_rest/v4/my/did/sms/provision?endpoint=%2B17208675309

Multiple endpoints can be provided by adding additional endpoint parameters in the URL, separated with an ampersand.

Parameters

None, however, this API method requires an Authorization token. To learn more about the Authorization token, check out API Authentication.

Response Example

1
2
3
4
5
6
{
  "code": 200,
  "provisioning": {
  "state": "requested"
  }
}

If multiple endpoints are provided, the response code will change to 207 (multi-status) and a list of responses matching the above format will be returned, in the same order of the query parameters provided.

Response Variable Values

Example Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
package main.java.mdr;

  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import java.util.ArrayList;
  import java.util.List;

  import org.apache.http.HttpHeaders;
  import org.apache.http.HttpResponse;
  import org.apache.http.NameValuePair;
  import org.apache.http.client.HttpClient;
  import org.apache.http.client.entity.UrlEncodedFormEntity;
  import org.apache.http.client.methods.HttpPost;
  import org.apache.http.impl.client.HttpClientBuilder;
  import org.apache.http.message.BasicNameValuePair;

  public class MdrStatus {
  public static void main(String... args) throws Exception {
  final String url = "https://api.intelepeer.com/_rest/v4/app/sms/mdr";
  final String AUTH_TOKEN = "INSERT_AUTH_TOKEN_HERE";
  final String REFID = "INERT_REFID_HERE";
  HttpClient httpclient = HttpClientBuilder.create().build();
  HttpPost httpPost = new HttpPost(url);

  // add header
  httpPost.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
  httpPost.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + AUTH_TOKEN);

  // Data to be posted
  List urlParameters = new ArrayList();
  urlParameters.add(new BasicNameValuePair("refid", REFID));

  // add data to post
  httpPost.setEntity(new UrlEncodedFormEntity(urlParameters));

  // execute post
  HttpResponse response = httpclient.execute(httpPost);

  // show post results
  System.out.println("nSending 'POST' request to URL : " + url);
  System.out.println("Post parameters : " + httpPost.getEntity());
  System.out.println("Response Code : " + response.getStatusLine().getStatusCode()
  );

  BufferedReader rd = new BufferedReader(
  new InputStreamReader(response.getEntity().getContent())
  );

  StringBuffer result = new StringBuffer();
  String line = "";
  while ((line = rd.readLine()) != null) {
  result.append(line);
  }

  System.out.println(result.toString());
  }
  }

Disabling a Number for SMS/MMS via API

URI

DELETE https://api.intelepeer.com/_rest/v4/my/did/sms/provision

Parameters

This API method requires an Authorization Token. To learn more about the Authorization token, check out API Authentication.

1
2
3
{
  "endpoints": [ "+13031112222" ]
}                    

Response Example

1
2
3
4
5
6
{
  "code": 202,
  "provisioning": {
  "state": "derequested"
  }
}

Behavior

Deprovisioning can only be requested when a number is in the provisioned state.

Example Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import requests

  # update these accordingly
  AUTH_TOKEN = 'INSERT_AUTH_TOKEN_HERE'
  TN         = 'INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'

  # leave these alone
  url = 'https://api.intelepeer.com/_rest/my/did/sms/provision'
  headers = {
  'Authorization': 'Bearer {}'.format(AUTH_TOKEN),
  'Content-Type': 'application/json',
  }
  json = {
  'endpoints': [TN],
  }

  # execute the task and parse results
  response = requests.delete(url, json=json, headers=headers)
  print('{}: {}'.format(response.reason, response.text ))

The Messaging API makes it simple to send and receive SMS/MMS messages through your IntelePeer Short Codes and Long Codes.

All IntelePeer Short Codes and Long Codes can be used to send and receive SMS/MMS messages. Alphanumeric sender IDs cannot receive SMS/MMS messages.

Note: For specific instructions on sending MMS messages, check out Understanding MMS Messaging.

Sending a Single SMS/MMS Message

You can send an SMS/MMS message with a single call to the Messaging API.

Note: Ensure you are following IntelePeer API conventions.

URI

POST https://api.intelepeer.com/_rest/v4/app/sms/send

Parameters

This API method requires an Authorization Token. Learn more about the Authorization token in API Authentication. For details on sending MMS, check out Understanding MMS Messaging.

Request Examples for SMS

The from parameter when sending to Long Codes must be in the Short Code-formatted number format (CountryCode-ShortCode)

1
2
3
4
5
6
{
  "from": "1-12345",
  "to": "+13038675309",
  "text": "Hello World!",
  "guid": "1123123123123123"
}

The from parameter when sending to Long Codes must be in E.164 format

1
2
3
4
5
6
{
  "from": "+12191112222",
  "to": "+13038675309",
  "text": "Hello World!",
  "guid": "1123123123123123"
}

The from parameter when sending to non-US Long Codes must be in the Short Code-formatted number format (CountryCode-Alphanumeric)

1
2
3
4
5
6
{
  "from": "57-MyCompany",
  "to": "+573132341111",
  "text": "Hello World!",
  "guid": "1123123123123123"
}

Request Example for MMS

The following sample shows the request for an MMS message including media:

Note: For more information, check out Understanding MMS Messaging.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "eid": "1234567",
  "from": "+14155551212",
  "to": "+18145551212",
  "text": "Here are the pictures you requested.",
  "media": [
    {
      "link": "https://i.imgur.com/faMls9L.png"
    },
    {
      "link": "https://i.imgur.com/Kil4uKz.jpeg"
    },
    {
      "link": "https://i.imgur.com/ofClDwt.jpg"
    },
    {
      "link": "https://d2hmxmws0mtfmy.cloudfront.net/menus/menu-CO11.pdf"
    },
    {
      "link": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRY3A1R5TNEyYs_YYwXKarigeXmneFqU9LDeA&usqp=CAU"
    }
  ]
}

Response Codes

Response Example

1
2
3
4
5
6
{
  "state": "Queued",
  "code": 202,
  "refid": "SM5C804F0D000999999910009AD59930",
  "numparts": 1
}

Behavior

Messages sent through the Messaging API are queued for quick and reliable delivery to the destination carrier and ultimately to the end-user’s phone.

You can check the status of a message at any time after sending it. Learn more about Checking Message Status.

The message’s lifecycle is as follows:

1. Message queued for delivery
2. Message delivered to the mobile carrier
3. Message delivered to the desired recipient

There may be delays in delivery of a message to the end-customer due to:

• Throttling enforced by IntelePeer to improve message delivery
• The end customers handset being out of service area, turned off, or in airplane mode

There may be message delivery failures due to carrier SPAM filters or the carrier-specific restrictions.

Sending SMS Messages in Bulk

Important: MMS messages can't be sent in bulk.

The same API above can also be used to send messages in bulk. The following describes the differences between the single-API and the bulk-API:

Changes to the Request for Bulk API

The single-send API requires a single object which contains the message parameters. The same API can be used to create a bulk send request by passing a list of requests in the request body. To use the bulk-send API, simply turn your JSON into a list of these objects:

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
  {
  "from": "1-12345",
  "to": "+13038675309",
  "text": "Hello World test 1",
  "guid": "1123123123123123"
  },
  {
  "from": "1-98765",
  "to": "+13038678888",
  "text": "Hello World test 2",
  "guid": "myguid1"
  }
]

Changes to the Response for Bulk API

The send API responds with a reference identifier (refid) as well as status information about the request.

Corresponding with the change of the request to a list, the API returns a list of responses in the object-key, responses, where each response corresponds to the associated request.

When utilizing the bulk request format of the API, the response code will generally be 207 regardless of the status of individual messages unless an error occurs at the overall request level.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "code": 207,
  "responses": [
    {
      "state": "Queued",
      "code": 202,
      "refid": "SM5C804F0D000999999910009AD59930",
      "numparts": 1
    },
    {
      "state": "Queued",
      "code": 202,
      "refid": "SM5C804F0D000999999910009AD59930",
      "numparts": 1
    }
  ]
}

The Messaging API makes it easy to send and receive SMS messages through your IntelePeer DID or Toll-Free phone numbers. Short Codes and Alphanumeric Codes are also available. Send-only for SMS messages through Alphanumeric Codes. In this document, you’ll find instructions on how to configure your numbers to send SMS messages with delivery receipts.

Important: Delivery receipts (DLRs) are not enabled for MMS messaging.

Sending a Single SMS Message

You can send an SMS message with a single call to the Messaging API. Please ensure you are following IntelePeer API conventions.

URI

POST https://api.intelepeer.com/_rest/v4/app/sms/send

Parameters

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

Request Example for Long Codes

The to parameter for sending from Long Codes must be in E.164 format.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[
  {
    "from": "+12191112222",
    "to": "+13038675309",
    "text": "Hello World!",
    "dlr": true,
    "guid": "1123123123123123"
  },
  {
    "from": "+13032225555",
    "to": "+172034448888",
    "text": "Hello World",
    "dlr": true,
    "dlroptions": {
      "include_accepted": true
    },
    "guid": "1122334455667788"
  }
]

Sending a SMS Message with Delivery Receipts

A Delivery Receipt (DLR) provides you the details of success or failure of your outbound SMS messages. There are three phases at which progress can be confirmed:

• API Acknowledgment – IntelePeer sends an acknowledgment to the API call to our systems. A 202 message means the message is progressing. More details on response codes can be found here.
• Checking Message Status – Once the IntelePeer Servers have sent a message downstream, the Message Detail Records (MDR) is updated with a further status. For more details, check out the Checking Message Status section.
• Optional Delivery Receipt – IntelePeer provides an optional parameter on an outbound message to receive a Delivery Receipt (DLR) from the Mobile Provider to which the message is sent.

Delivery Receipt Message States

• Delivery Receipt Message States are provided to IntelePeer by mobile carriers and we pass them to our customers unaltered. More information about Delivery Receipts can be found on the SMS Delivery Receipts page.

• The Message State sent for Carrier DLR and Handset DLR are the same.

Setting Up Your System to Receive DLRs

SMS DLRs are delivered in the same way that an inbound message is delivered – to a customer dedicated webhook.

There are three steps to set up and test delivery receipts, after SMS has been set up on an account and (at least) one number has been SMS provisioned.

The format for DLRs are application/json to and they are sent to your DLR webhook in the following format:

When sending an SMS, the message may be split into multiple segments in transit. If the final carrier supports DLRs, you should expect to receive a DLR webhook POST for each segment. The number of segments your message is split into is returned in the original send request.

Task 1: Set up your webserver to receive DLR webhooks

Just like your inbound SMS webserver, it should support receiving HTTP POST messages on an endpoint with an expected content type of application/json.

Task 2: Configure Your Account’s DLR webhook

Unlike inbound SMS messages, where each code can have a unique webhook for delivery, all DLRs are delivered to the same webhook. To set up this webhook, provide the URL through the existing account configuration endpoint, but provide a dlrwebhook parameter to your JSON request.

Example DLR

{
  "content": "DLR",
  "from": "+18001112222",
  "to": "+12223334444",
  "refid": "SM5C59B99900012345671000F9170FDB",
  "status": "DELIVRD",
  "message_state": "DELIVERED"
}

Sample Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import requests

  # update these accordingly
  AUTH_TOKEN  = 'INSERT_AUTH_TOKEN_HERE'
  DLR_WEBHOOK = 'INSERT_DLR_WEBHOOK_URL_HERE'

  # leave these alone
  url = 'https://api.intelepeer.com/_rest/v4/app/sms/accountcfg'
  headers = {
  'Authorization': 'Bearer {}'.format(AUTH_TOKEN),
  'Content-Type': 'application/json',
  }
  json = {
  'dlrwebhook': DLR_WEBHOOK,
  }

  # execute the task and parse results
  response = requests.post(url, json=json, headers=headers)
  print(response.text)

This same endpoint is also used to set up your account secret which can be provided in the same request under the parameter, secret.

Task 3: Send an SMS message using the API (with DLR enabled in the request)

Task 4: Validate Delivery Receipts are being delivered to your webhook

Upon sending an SMS message, and receiving it on a cellphone, you should expect to see your webhook receive one request per segment which that SMS was split into.

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

Telling 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 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/MMS Messages via API

URI

POST 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 API Authentication.

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

1
2
3
4
5
6
{
  "endpoints": [
    "+12161112222"
  ],
  "webhook": "https://www.myserver.com/myapp"
}

Example Responses

Single Request

1
2
3
4
5
6
7
8
{
  "code": 201,
  "tnkey": "+12161112222",
  "webhook": "https://www.myserver.com/myapp",
  "provisioning": {
    "state": "provisioned"
  }
}

Bulk Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import requests

  # update these accordingly
  AUTH_TOKEN  = 'INSERT_AUTH_TOKEN_HERE'
  TN          = 'INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'
  WEBHOOK_URL = 'INSERT_WEBHOOK_URL_HERE'

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

  # execute the task and parse results
  response = requests.post(url, json=payload, headers=headers)
  print('{}: {}'.format(response.reason, response.text ))

Learn more about webhook security in Securing Inbound SMS/MMS Webhooks.

Checking the Webhook for Receiving SMS/MMS Messages via API

URI

GET 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 API Authentication.

Response Example

1
2
3
4
5
6
7
8
{
  "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

Response Codes

Example Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import requests

  # update these accordingly
  AUTH_TOKEN = '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'
  headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {}'.format(AUTH_TOKEN)
  }
  params = {
  'endpoint': TN,
  }

  # execute the task and parse results
  response = requests.get(url, headers=headers, params=params)
  print('{}: {}'.format(response.reason, response.text))

Receiving Messages via API

When a message is received on an SMS/MMS-enabled number, 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:

Example

1
2
3
4
5
6
7
{
  "refid": "ABCDEF1234567890ABCDEF1234567890",
  "from": "+7708675309",
  "to": "+13038675309",
  "message": "Hello World!",
  "signature": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Behavior

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:

• 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/MMS reporting dashboard.

You can check the status of an outbound message any time after it has been sent.

Visit Sending Messages to learn more about sending an SMS/MMS message.

Checking Outbound Message Status

You can check the delivery status of a message with a single call to the Messaging API.

URI

POST https://api.intelepeer.com/_rest/v4/app/sms/mdr

Parameters

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

Request Example

{
  "refid": SM5AC09A610001006568100005C32E9D",
}

200 OK Examples

{
  "code": 200,
  "RCC_en": "Queued",
  "RCC": 0
}

{
  "code": 200,
  "RCC_en": "Processing",
  "RCC": 2031
}

{
  "code": 200,
  "RCC_en": "Sent",
  "RCC": 10000
}

{
  "code": 200,
  "RCC_en": "DLR:Delivered",
  "RCC": 210000
}

{
  "code": 200,
  "RCC_en": "Failed",
  "RCC": 6009
}

401 Unauthorized Examples

{
  "detail": "unauthorized"
  }
  {
  "error": "token has expired"
}

Response Variable Values

Note: For more information about DLR values see Table B-2: Delivery Receipt Short Message Text Format of the Short Message Peer to Peer Protocol Specification v3.4

Response Codes

Behavior

Messages sent through the Messaging API are queued for quick and reliable delivery to the destination carrier and ultimately to the end-user’s phone.

The message’s lifecycle is as follows:

1. Message queued for delivery
2. Message delivered to the mobile carrier
3. Message delivered to end-customer

Note: In some cases, message delivery may fail due to carrier SPAM filters or other carrier-specific restrictions. With Verizon specifically, message delivery may fail due to the destination number being deactivated (“rccdata”: “deactivatedmdndb”)

There may be delays in delivering a message to the end-customer due to:

• Throttling enforced by IntelePeer to improve message delivery
• Throttling or SPAM controls enforced by the mobile carrier
• The end customers handset being out of service area, turned off, or in airplane mode

Example Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import requests

  # update these accordingly
  AUTH_TOKEN  = 'INSERT_AUTH_TOKEN_HERE'
  TN          = 'INSERT_TELEPHONENUMBER_HERE_IN_E.164_FORMAT'
  WEBHOOK_URL = 'INSERT_WEBHOOK_URL_HERE'
  
  # leave these alone
  url       = "https://api.intelepeer.com/_rest/v4/my/did/sms/webhook"
  headers      = {
  'Authorization': 'Bearer {}'.format(AUTH_TOKEN),
  'Content-Type': "application/json",
  }
  payload   = {
  'endpoints': [TN],
  'webhook': WEBHOOK_URL,
  }

  # execute the task and parse results
  response = requests.post(url, json=payload, headers=headers)
  print('{}: {}'.format(response.reason, response.text ))