SMS / MMS Message Management
Important: To avoid having your MMS messages rejected, make sure you (1) keep your message size to 5MB or less for all attachments, and (2) check to make sure the URLs you use for your media go directly to the media file and the URLs are publicly accessible over the internet.
Base URL
All of the following endpoints share the same base URL:
https://api.intelepeer.com
To use the APIs, you must have an SMS/MMS-capable number associated with your CPaaS Portal account.
Important: For numbers to send successfully, you must use e.164 formatting; for example, +15551212.
For information on accessing SMS/MMS from the Customer Portal, check out the SMS/MMS Messaging Quick Start Guide. Multimedia Messaging Service (MMS) is available for SmartCommunicator™, SmartFlows™, SmartEngage™, and APIs.
Note: While there are similarities between SMS and MMS messages, it is important that you understand the differences if you intend on sending MMS messages as well. For more information, check out Understanding MMS Messaging.
Generate Authentication Token
To use any of the IntelePeer APIs, you must access the IntelePeer Authentication API to generate a token. This API requires your CPaaS Portal credentials (the username and password used to sign up for your CPaaS account).
For more information on receiving your token, check out API Authentication.
Use the SMS/MMS APIs
The API URLs and their corresponding documentation are below. These URLs are referenced in the table below next to the corresponding API functionality.
Note: While the documentation is the same, the API URL is different for users in the CPaaS Portal.
Functionality | API URL | More Information |
---|---|---|
Send SMS/MMS | POST https://api.intelepeer.com /_rest/v4/app/sms/send | See Sending SMS/MMS Messages |
Receive SMS/MMS | POST https://api.intelepeer.com /_rest/v4/my/did/sms/webhook | See Receiving SMS/MMS Messages |
Check Message Status | GET https://api.intelepeer.com /_rest/v4/app/sms/mdr | See Checking Message Status |

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
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
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:
- Explicitly enable SMS/MMS for the phone number
- 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.
Parameter | Data Type | Required | Description |
---|---|---|---|
endpoints | list of strings | required | A list of E.164 format of the long codes (TNs) you want to provision. Only a single E.164 can be submitted to this list. |
Request Example
{
"endpoints": [ "+13031112222" ]
}
Response Example
{
"code": 202,
"provisioning": {
"state": "requested"
}
}
Response Code | Description |
---|---|
202 | The provisioning request has been accepted and is pending completion. |
400 | The reason for the error is contained within the response. |
401 | The reason for the error is contained within the response. |
409 | Provisioning (or deprovisioning) of the number is in progress. |
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
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
{
"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
Variable | Available Values |
---|---|
code | matches the http response code |
provisioning.state |
requested provisioning provisioned derequested deprovisioning error |
Response Code | Description |
---|---|
200 | Status 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
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.
{
"endpoints": [ "+13031112222" ]
}
Response Example
{
"code": 202,
"provisioning": {
"state": "derequested"
}
}
Response Code | Description |
---|---|
202 | The deprovisioning request has been accepted and is pending completion |
400 | The reason for the error is contained within the response |
401 | The reason for the error is contained within the response |
409 | Provisioning (or deprovisioning) of the number is in progress |
Behavior
Deprovisioning can only be requested when a number is in the provisioned state.
Example Code
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.
Field | Type | Description |
---|---|---|
eid |
STRING |
The Customer ID; provided by the authenticator |
from | STRING |
[Required] Properly formatted customer inventory code (long code, short code, alphanumeric sender id) for example, 1-12345, 57-Hello8, +13031112222) See Code Formatting for more information Important: Only long codes are supported for MMS. |
to | STRING | [Required] E.164-formatted number to which the message is being sent to (for example, +13038675309) |
text | STRING | [Required for SMS; optional for MMS] For SMS, the message to be sent; for MMS, the message-text-block can also be included in media as a text-block or in place of a URL link; encoding is UTF-8 |
media |
ARRAY |
[For MMS only] The media array contains objects that describe the text, data, or links to send |
content-type |
STRING |
[For MMS only] An content-type; the default is default:<detect> |
filename |
STRING |
[For MMS only] Associated with the link; the default is default:<detect> |
data |
STRING |
[For MMS only] A data-block encoded using the method stated in the encoding field |
encoding |
STRING |
[For MMS only] The encoding of the data, supporting either base64 or raw; the default value is raw |
guid | STRING |
[Optional for SMS only] An identifier to be appended to the message in the Message Detail Record for correlation with other system records |
Request Examples for SMS
The from parameter when sending to Long Codes must be in the Short Code-formatted number format (CountryCode-ShortCode)
{
"from": "1-12345",
"to": "+13038675309",
"text": "Hello World!",
"guid": "1123123123123123"
}
The from parameter when sending to Long Codes must be in E.164 format
{
"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)
{
"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.
{
"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 Code | Description |
---|---|
202 | SMS/MMS message has been successfully queued for delivery to the destination phone number. |
400 |
One of the following errors occurred:
|
401 |
One of the following errors occurred:
|
403 | The international destination is not available |
404 | The telephone number is not available for use by the customer |
Response Example
{
"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:
- Message queued for delivery
- Message delivered to the mobile carrier
- 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
[
{
"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
{
"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.
Parameter | Data Type | Required | Description |
---|---|---|---|
from | STRING | Required |
Properly formatted customer inventory code (long code, shortcode, alphanumeric sender id) For example, 1-12345, 57-Hello8, +13031112222 See Code Formatting for more information |
to | STRING | Required | E.164-formatted number to which the message is being sent to (for example, +13038675309) |
text | STRING | Required | The message to be sent |
dlr | BOOLEAN | Optional | Set to True enable delivery receipt on this request (default=False) |
dlroptions | Object | Optional | May be optionally supplied when dlr is set to true to set additional DLR options beyond the standard behavior |
dlroptions.include-accepted | BOOLEAN | Optional |
If set to True, the system will generate an additional intermediary DLR which indicates when the MT message is successfully enqueued into the SMS network. This DLR will reflect the state ACCEPTD when received. This DLR represents a positive-confirmation DLR and not negative-confirmation. As such, if requested, the lack of receipt of this DLR is an indication of failure to enqueue the message to the SMS network. This is primarily used when final delivery status through the carrier/handset is unavailable in the destination country. |
guid | STRING | Required | An identifier to be appended to the message in the Message Detail Record for correlation with other system records. |
Request Example for Long Codes
The to parameter for sending from Long Codes must be in E.164 format.
[
{
"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
Message State | Status | Description | Explanation |
---|---|---|---|
DELIVERED | DELIVRD | Message is delivered to destination | Message has been successfully delivered to the handset (in case of handset DLRs), or to the carrier (in case of carrier DLRs). |
EXPIRED | EXPIRED | Message validity period has expired | Message was not delivered during the default validity period of X hours. This might indicate the phone has been switched off for a long period of time. The validity period is the minimum value between IntelePeer’s validity period and the carrier’s validity period. |
DELETED | DELETED | Message has been deleted | Message has been canceled or deleted by the carrier Short Messaging Service Center (SMSC). |
UNDELIVERABLE | UNDELIV | Message is undeliverable | Message cannot be delivered to the destination number, usually due to carrier content filtering or the availability of the destination handset being unavailable. |
ACCEPTED | ACCEPTD | Message is in accepted state (i.e., has been manually read on behalf of the subscriber by customer service) | Message has been accepted for delivery but has not been delivered to the handset yet. Not supported by all carriers. |
UNKNOWN | UNKNOWN | Message is in invalid state | No useful information is available. |
REJECTED | REJECTD | Message is in a rejected state | Message is rejected by the carrier, usually due to number being blacklisted by the carrier. |
-
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
{
"refid": "SM1-1727714026-123-10-9e046440",
"from": "+12172107440",
"to": "+17204228552",
"content": "DLR",
"status": "delivered",
"message_state": "Message delivered to handset",
"guid": "210",
"termination_country": "United States of America",
"termination_carrier": "Verizon Wireless"
}
Field Name | Description |
---|---|
content | “Always DLR” |
from | The sending code |
to | The receiving SMS-enabled handset |
refid | The reference identifier for the message, which was passed back in the original send request |
status | The final status of the message. Values per SMPP Protocol Specification v3.4, Table B-2 |
message_state | Should be present for SMSC Delivery Receipts and Intermediate Notifications. Will be set to null when not available. Values per SMPP Protocol Specification v3.4, 5.2.28 |
guid |
A customer-created ID that allows you to enter your own information; can be anything but must be a string |
termination_carrier |
The carrier of the destination number (for example, |
termination_country |
The country of the destination number (for example, |
Sample Code
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.
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
{
"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:
|
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
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
{
"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
# 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:
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/MMS Webhooks |
Example
{
"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.
Parameter | Data Type | Required | Description |
---|---|---|---|
refid | STRING | Required | The refid of the message returned by calling the send method. |
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
Variable | Available Values |
---|---|
RCC_en |
Queued Processing Failed Sent DLR:Delivered DLR:Expired DLR:Deleted DLR:Undeliverable DLR:Accepted DLR:Unknown DLR:Rejected |
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
Response Code | Description |
---|---|
200 | MDR Returned |
401 | Authorization token has expired or invalid |
404 | Record not found |
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:
- Message queued for delivery
- Message delivered to the mobile carrier
- 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
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 ))