Messaging Service - V3
Messaging API
- Send / Receive Messages
- SMS - text only message
- MMS - message with multimedia
- Session Detail Records
- Provision numbers
Concepts
Message segments
The SMS network limits the size of messages. These size limits vary based on the content of the message. When the size limit is exceeded, messages are split into segments so that they can traverse the SMS network. When all of these segments reach the destination, they are merged back into a single message. From a user perspective, it appears as though a single long message was sent and received. From a technical and billing perspective, it is important to note that each segment is treated as a separate message.
SMS content can be sent using different alphabets. MessagePro will always send the message using the alphabet that uses the fewest possible segments. Here is a link to a description about SMS alphabets: SMS Alphabets.
Here are simple hightlights regarding SMS lengths and segments:
- GSM7 alphabet messages can hold 160 characters before multiple segments are required
- Latin1 alphabet messages can hold 140 characters before multiple segments are required
- Other alphabets / emojis can hold 70 characters before multiple segments are required
Throttling
MessagePro imposes rate restrictions on outbound SMS messages. These limits vary based on account configuration. Check the portal for current limitations. Messages that exceed these limits will be queued and sent as soon as the limitations allow.
Bulk Messages
Bulk messages have lower priority and will only be sent during normal hours. Bulk messages will not use the entire quota of messages throttling limitations. This allows scheduling a large batch for broadcast on best-effort basis while allowing adhoc messages to be sent within the throttling limitations.
When sending a message to a single number, bulk processing is off by default. When sending a message to a group of numbers, bulk processing is on by default. These defaults can be overridden by setting the bulk
flag.
The MessagePro system may also set the message to bulk
based on other factors such as sending the same content to many users.
Conversational Messages
Conversational messages show up in the GUI as if a human typed it. They should be used to automate human actions.
Non-conversational messages do not automatically create conversations in the GUI.
All inbound messages are added to conversations.
Opt in/out
When sending messages from an application (as opposed to a human generated message), it is important to allow the destination user to opt-out of receiving these messages. Industry standards require compliance and failure to do so will result in denial of SMS service.
MessagePro allows automatic opt in/out processing by setting a flag on outgoung messages. When setting optLogic
to true
, the system will add opt-out footers on outgoing messages as needed and register the responses for appropriate handling.
An example opt-out footer: Reply STOP to opt-out
Overview
- Base URL: https://msgapi.MessagePro.com/smsmms/v3/
- Version: v3
Authentication
API Key Authentication
API access is protected by using an API key in a HTTP header. Use the portal to acquire an API key. Provide the api key as the data for a header named 'apikey'.
- HTTP Header
- apikey: {apiKey}
Messages
Resource Actions
Resource | Create (POST) | Read (GET) | Update (PUT) | Delete (DELETE) |
---|---|---|---|---|
/messages | Send Message | Get Messages | Error | Error |
Message - Send Message
/sms/v3/messages
POST https://msgapi.MessagePro.com/smsmms/v3/messages HTTP/1.1
Content-Type: application/json
{
"from": "18135701000",
"to": "18135791001",
"body":"My first test"
}
curl -X POST https://msgapi.MessagePro.com/smsmms/v3/messages \
-H "Content-Type: application/json" \
-d '{
"from": "18135701000",
"to": "18135791001",
"body":"My second test"
}'
Messages - Attributes
Attribute | Type | Description |
---|---|---|
Attributes related to telephone numbers
Must have one and only one of `to` and `toArray` |
||
from | text | The originating telephone number (TN) required E164 format |
to | text | Single terminating Telephone Number E164 format |
toArray | [text] | An array of terminating Telephone Numbers E164 format |
Attributes related to the message content
Must have at least one or both of `body` and `media` |
||
body | text | The message to be sent |
media | [text] | An array of URLs for media attachments (MMS) |
Attributes related to how the message will get processed | ||
conversational | boolean | Indicates whether the message should added to conversations in the GUI optional
Values
|
bulk | boolean | Indicates whether the message should use bulk processing optional
Bulk messages have lower priority and will only be sent during normal hours Values
|
optLogic | boolean | Indicates whether the message should use opt in/out processing optional
`optLogic` indicates that destinations can opt-out of receiving messages. The system will manage the opt-in/out footers on outgoing messages and register the responses for appropriate handling Values
Example message footer Reply STOP to opt-out |
Attributes related to message tracking | ||
referenceId | text | This is a user defined tracking text. Length Limit = 40. Alphanumeric [no special characters or white space].optional |
userId | text | Indicate the user that sent this message - only used for tracking purposesoptional |
userType | text | Indicate the type of user that sent this message - only used for tracking purposesoptional |
Example OK Response
{
"status": "MessageCreateSuccessful",
"statusCode": 200,
"statusMessage": "Message Create Successful",
"statusUri": "",
"data": {
"apiVersion": "v3",
"accountId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"from": "+18135701000",
"to": "+18135791001",
"body": "My first test",
"optLogic": true,
"bulk": false,
"messageInfo": [
{
"messageId": "5e1e9d34-8162-4a97-8422-51da505f7636",
"dateCreated": "2019-03-20T14:26:28.767+0000",
"to": "+18135791001",
"body": "My first test",
"optStatus": "notIn",
"numSegments": 1,
"status": "accepted"
}
]
}
}
Example Error Response
{
"status": "MessageCreateSuccessful",
"statusCode": 200,
"statusMessage": "Message Create Successful",
"statusUri": "",
"data": {
"apiVersion": "v3",
"accountId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"from": "+18135701002",
"to": "+18135791001",
"body": "test",
"optLogic": true,
"bulk": false,
"error_code": 404,
"error": "MissingAccount",
"error_message": "'from' is not valid account",
"messageInfo": [
{
"messageId": "78c250fc-259e-4495-9c2e-4e4f76ecf580",
"dateCreated": "2019-03-27T12:55:48.011+0000",
"to": "+18135791001",
"body": "test",
"optStatus": "",
"numSegments": 1,
"status": "rejected"
}
]
}
}
Messages - Response - JSON
Attribute | Type | Description |
---|---|---|
statusCode |
number | Numeric status code (see below) |
status |
text | Alpha status code (see below) |
statusMessage |
text | Status description (see below) |
statusUri |
text | URL for getting additional information |
data |
json | specific JSON results (see below) |
Messages - Response - JSON - statusCode, status, statusMessage
Status | StatusCode | StatusMessage |
---|---|---|
200 | MessageCreateSuccessful | Message Create Successful Note: Messages get queued to make sure only 1 text per second is sent by any given originating ( from ) number. |
400 | MissingAccountId | "'accountId' is required" |
400 | MissingFrom | 'from' is required |
400 | MissingTo | 'to' or 'toArray' is required |
400 | MissingBody | 'body' is required Note: Not required if sending media |
400 | InvalidNumber | 'from' is not valid number |
400 | MissingJSON | JSON required |
400 | ResourceNotAllowed | Resource not allowed on POST |
400 | UnknownResource | Unkown Resource on POST |
400 | InvalidJSON | The JSON request is not valid. |
400 | InvalidRequest | Invalid Request |
500 | SystemFailure | General System Failure |
Messages - Response - JSON - data
- the response data will include everything from the incoming request data in addition to the following
Attribute | Type | Description |
---|---|---|
apiVersion |
text | v3 |
messageInfo |
jsonArray | details about each to or toArray |
Messages - Response - JSON - data.messageInfo
Attribute | Type | Description |
---|---|---|
Attributes to identify the message | ||
to | text | Destination Telephone Number for this object E164 format |
body | text | Text message that was sent
For opt in/out processing, additional text may be added to the original message |
messageId | text | UUID assigned to the message |
dateCreated | text | ISO format date/time of when the message received |
Attributes related to the processing of the message | ||
numSegments | number | Number of segments required to send the message
|
optStatus | text | opt in/out status
Values
|
Attributes related to the status of the message | ||
status | text | Alpha status code
Values
|
reason | text | Reason for message rejection
Values
|
Message - Incoming (Webhook)
When the system receives an incoming message, it will be delivered via the defined webhook. The portal allows for the Webhook URL and an HTTP header to be specified.
Authentication is handled by adding URL parameters or using HTTP Header information. Implementation details allow for Basic Authentication, Bearer Authentication, APIKey or others.
{user-specified URL}
POST {webhook_url} HTTP/1.1
Content-Type: application/json
{
"accountId": "967415de-9052-4759-a221-83a8a1172288"
"timestamp": "2019-05-22T21:37:57.344+0000",
"messageId": "d51f1667-c520-417c-b28b-c2fb6fd5572e",
"from": "18135791001",
"to": "18135791000",
"messageType": "sms",
"numSegments": 1,
"body": "Inbound",
"media": []
}
Messages - Attributes
Attribute | Type | Description |
---|---|---|
API Information | ||
apiVersion | text | v3 |
Attributes related to message identity | ||
messageId | text | UUID assigned to the message |
timestamp | text | ISO format date/time of when the message was received |
Attributes related to telephone numbers | ||
from | text | The originating telephone number (TN) E164 format |
to | text | Terminating Telephone Number E164 format |
accountId | text | The accountId associated with the `to` number |
Attributes related to the message content | ||
body | text | The message that was received |
media | [text] | An array of URLs for media attachments (MMS) |
messageType | text | The type of incoming message
Values
|
numSegments | number | Number of segments required for the message
|
Message - Status (Webhook)
When the system sends an outgoing message, it will receive status messages about the delivery from the network. The status updates will be delivered via the defined webhook. The portal allows for the Webhook URL and an HTTP header to be specified.
Authentication is handled by adding URL parameters or using HTTP Header information. Implementation details allow for Basic Authentication, Bearer Authentication, APIKey or others.
{user-specified URL}
POST {webhook_url} HTTP/1.1
Content-Type: application/json
{
"apiVersion": "v3",
"messageId": "7d5fd0dd-9b6e-418c-b307-fac270d019b2",
"referenceId": "51839",
"timestamp": "2019-05-22T21:34:29.944+0000",
"segmentNumber": 0,
"from": "18778425042",
"to": "18135791001",
"accountId": "b4c52b73-c394-482e-88f5-f7e011224822"
"status": "delivered",
"statusMsg": "Message Delivered (stat=DELIVRD)",
"numSegments": 1,
"bulk": false
}
Messages - Attributes
Attribute | Type | Description |
---|---|---|
API Information | ||
apiVersion | text | v3 |
Attributes related to message identity | ||
messageId | text | UUID assigned to the message |
referenceId | text | The user-assigned reference number for the outgoing message |
timestamp | text | ISO format date/time of when the status was received |
segmentNumber | number | The segment number for this status message |
Attributes related to telephone numbers | ||
from | text | The originating telephone number (TN) E164 format |
to | text | Terminating Telephone Number E164 format |
accountId | text | The accountId associated with the `to` number |
Attributes related to the message status | ||
status | text | The status code regarding message delivery
Values
|
statusMsg | text | The status message regarding message delivery. This provides more details about the status of the message. There are many different status messages, most of which come from the serving carriers.
Examples
|
Attributes related to the message content | ||
numSegments | number | Number of segments required for the message
|
Message - Get Messages
/sms/v3/messages
GET https://msgapi.MessagePro.com/smsmms/v3/messages HTTP/1.1
GET https://msgapi.MessagePro.com/smsmms/v3/messages/?start=0&count=50&to=18135791000 HTTP/1.1
curl -X GET https://msgapi.MessagePro.com/smsmms/v3/messages
Messages - Parameters
Parameter | Description | |
---|---|---|
Parameters related to filtering results | ||
messageId | Return only messages with this messageId | |
referenceId | Return only messages with this referenceId | |
from | Return only messages with this originating telephone number (TN) - E164 format | |
to | Return only messages with this terminating telephone number (TN) - E164 format | |
messageType | Return only messages with this message type
Values
|
|
direction | Return only messages with this direction
Values
|
|
status | Return only messages with this status
Values
|
|
body | Return only messages with this value within the body | |
timestampBegin | Return only messages after this timestamp | |
timestampEnd | Return only messages after before timestamp | |
Parameters related to paging the results | ||
start | Return messages starting with this result offset | |
count | Return only this number of messages | |
Parameters related to sorting the results | ||
sortBy | Return messages sorted by this field | |
sortDir | Return values sorted in this direction
Values
|
Example OK Response
{
"status": "QueryCompletedSuccessfully",
"statusMessage": "Query Completed Successfully",
"statusCode": 200,
"data": {
"total": 459,
"apiVersion": "v3",
"position": 0,
"results": [
{
"accountId": "00000000-1111-2222-3333-4444444444444",
"messageType": "sms",
"numSegments": 1,
"messageId": "bf98e4bc-bbd4-4426-bc62-7ca3fc176500",
"from": "18135791000",
"to": "18135791001",
"timestamp": "2019-05-10 20:08:46.820 EDT",
"media": [],
"body": "my outbound test",
"direction": "outbound",
"status": "delivered"
},
{
"accountId": "00000000-1111-2222-3333-4444444444444",
"messageType": "sms",
"numSegments": 1,
"messageId": "70e50e99-ff0b-4402-b32a-6bded789d4b4",
"from": "18135791000",
"to": "18135791001",
"timestamp": "2019-05-10 19:44:06.531 EDT",
"media": [],
"body": "another outbound test",
"direction": "outbound",
"status": ""
},
{
"accountId": "00000000-1111-2222-3333-4444444444444",
"messageType": "sms",
"numSegments": 1,
"messageId": "d3a7b850-7798-40bb-a372-5a2ee331d521",
"from": "18135791000",
"to": "18135791001",
"timestamp": "2019-05-10 20:02:46.427 EDT",
"media": [],
"body": "yet another outbound test",
"direction": "outbound",
"status": ""
}
]
}
}
Example Error Response
{
"statusUrl": "https://office.messagepro.com/apidocs/",
"statusMessage": "General System Failure",
"statusCode": 500,
"status": "SystemFailure"
}
Messages - Response - JSON
Attribute | Type | Description |
---|---|---|
statusCode |
number | Numeric status code (see below) |
status |
text | Alpha status code (see below) |
statusMessage |
text | Status description (see below) |
statusUri |
text | URL for getting additional information |
data |
json | specific JSON results (see below) |
Messages - Response - JSON - statusCode, status, statusMessage
Status | StatusCode | StatusMessage |
---|---|---|
200 | QueryCompletedSuccessfully | Query Completed Successfully |
400 | MissingAccountId | "'accountId' is required" |
400 | ResourceNotAllowed | Resource not allowed on POST |
400 | UnknownResource | Unkown Resource on POST |
400 | InvalidRequest | Invalid Request |
500 | SystemFailure | General System Failure |
Messages - Response - JSON - data
- the response data will include everything from the incoming request data in addition to the following
Attribute | Type | Description |
---|---|---|
apiVersion |
text | v3 |
total |
number | total number of results for the query |
position |
number | offset of this resultset used for paging |
results |
jsonArray | query results |
Messages - Response - JSON - data.results
Attribute | Type | Description |
---|---|---|
Attributes to identify the message | ||
from | text | The originating telephone number (TN) - E164 format |
to | text | Destination Telephone Number for this object - E164 format |
accountId | text | The accountId |
messageId | text | UUID assigned to the message |
timestamp | text | ISO format date/time of when the message was received |
messageType | text | The type of incoming message
Values
|
direction | text | The type of incoming message
Values
|
body | text | The message body |
media | [text] | An array of URLs for media attachments (MMS) |
numSegments | number | Number of segments required for the message
|
Session Detail Records
Session Detail Records
As a message gets processed by the MessagePro system, status updates will be generated. These status updates provide information about the progress of the message and any failures in may have encountered.
/sms/v3/sdrs
GET https://msgapi.MessagePro.com/smsmms/v3/sdrs/967415de-9052-4759-a221-83a8a1172288/bf98e4bc-bbd4-4426-bc62-7ca3fc176500 HTTP/1.1
curl -X GET https://msgapi.MessagePro.com/smsmms/v3/sdrs/967415de-9052-4759-a221-83a8a1172288/bf98e4bc-bbd4-4426-bc62-7ca3fc176500
SDRs - Parameters
The SDR request does not take any formal parameters. The URL is constructed to ask for a specific set of SDRs.
This is the basic format: https://msgapi.MessagePro.com/smsmms/v3/sdrs/{accountId}/{messageId}
Substitute the actual accountId for {accountId}.
Substitute the actual messageId for {messageId}.
Example OK Response
{
"data": {
"accountId": "1ea00b4e-fa80-4657-a15f-3cbb8ca3fb90",
"apiVersion": "v3",
"messageId": "aa7b3928-db8d-4dc7-b16a-84ebc826512f",
"results": [
{
"delta": "00.000",
"statusDetails": "",
"referenceId": "51913",
"timestamp": "2019-05-28 15:58:15.062 EDT",
"status": "accepted"
},
{
"delta": "00.034",
"statusDetails": "",
"timestamp": "2019-05-28 15:58:15.096 EDT",
"status": "queued"
},
{
"delta": "00.035",
"statusDetails": "",
"timestamp": "2019-05-28 15:58:15.097 EDT",
"status": "sending"
},
{
"delta": "00.088",
"statusDetails": "",
"timestamp": "2019-05-28 15:58:15.150 EDT",
"status": "message_sent"
},
{
"delta": "00.089",
"statusDetails": "",
"timestamp": "2019-05-28 15:58:15.151 EDT",
"status": "wait_dlr"
},
{
"delta": "00.346",
"statusDetails": "Message Delivered (stat=ACCEPTD)",
"referenceId": "51913",
"timestamp": "2019-05-28 15:58:15.408 EDT",
"status": "delivered"
},
{
"delta": "00.383",
"statusDetails": "",
"timestamp": "2019-05-28 15:58:15.445 EDT",
"status": "dlr_received"
},
{
"delta": "00.384",
"statusDetails": "",
"timestamp": "2019-05-28 15:58:15.446 EDT",
"status": "status_sent"
}
]
},
"statusMessage": "Query Completed Successfully",
"status": "QueryCompletedSuccessfully",
"statusCode": 200
}
Example Error Response
{
"results": {
"errorUrl": "https://office.messagepro.com/apidocs/",
"errorMessage": "accountId required on GET",
"errorCode": 400,
"error": "accountId missing"
}
}
SDRs - Response - JSON
Attribute | Type | Description |
---|---|---|
statusCode |
number | Numeric status code (see below) |
status |
text | Alpha status code (see below) |
statusMessage |
text | Status description (see below) |
statusUri |
text | URL for getting additional information |
data |
json | specific JSON results (see below) |
SDRs - Response - JSON - statusCode, status, statusMessage
Status | StatusCode | StatusMessage |
---|---|---|
200 | QueryCompletedSuccessfully | Query Completed Successfully |
400 | MissingAccountId | "'accountId' is required" |
400 | ResourceNotAllowed | Resource not allowed on POST |
400 | UnknownResource | Unkown Resource on POST |
400 | InvalidRequest | Invalid Request |
500 | SystemFailure | General System Failure |
SDRs - Response - JSON - data
- the response data will include everything from the incoming request data in addition to the following
Attribute | Type | Description |
---|---|---|
apiVersion |
text | v3 |
accountId |
text | The accountId used for the query |
messageId |
text | The messageId used for the query |
results |
jsonArray | query results |
SDRs - Response - JSON - data.results
Attribute | Type | Description |
---|---|---|
delta | number | Time offset from the start of the message |
timestamp | text | ISO format date/time of when the status was generated |
segmentNumber | number | The segment number for this status message |
referenceId | text | This is the user defined tracking text |
status | text | The status update |
statusDetails | text | Additional information about the status |