NAV Navbar
Logo
http shell

Messaging Service - V3

Messaging API

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:

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



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

POST
/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
  • false - the message will not be added to a GUI conversationdefault
  • true - the message will be added to a GUI conversation
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
  • false - bulk processing will not be used (default if using `to` attribute)
  • true - bulk processing will be used (default if using `toArray` attribute)
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
  • false - opt in/out processing will not be used default
  • true - opt in/out processing will not be used


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

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
  • 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
optStatus text opt in/out status

Values
  • notIn - destination has not responded yet (messages will be delivered)
  • out - destination has opted out (messages will not be delivered)
  • in - destination has opted in (messages will be delivered)
Attributes related to the status of the message
status text Alpha status code

Values
  • accepted - the message was accepted for delivery
  • rejected - the message will not be delivered - check `reason`
reason text Reason for message rejection

Values
  • opt-out - The destination has explicitely opted-out of receiving messages
  • international-blocked - The destination was to an invalid international destination

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.

POST
{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
  • sms - text only message
  • mms - message with multi-media content
numSegments number Number of segments required for the message
  • 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

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.

POST
{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
  • accepted - the message was accepted for delivery
  • delivered - the message was delivered successfully
  • failed - the message was not delivered successfully
  • rejected - the message was not delivered successfully
  • spam - the message was not delivered successfully
  • expired - the message was not delivered successfully
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
  • Too many unique recipients during time period
  • Invalid Destination Address (err=720)
  • Message Delivered (stat=DELIVRD)
  • Unknown err code (err=45c)
Attributes related to the message content
numSegments number Number of segments required for the message
  • 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

Message - Get Messages

GET
/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
  • sms - return only sms messages
  • mms - return only mms messages
direction Return only messages with this direction

Values
  • inbound - return only incoming messages
  • outbound - return only outgoing messages
status Return only messages with this status

Values
  • accepted - the message was accepted for delivery
  • delivered - the message was delivered successfully
  • failed - the message was not delivered successfully
  • rejected - the message was not delivered successfully
  • spam - the message was not delivered successfully
  • expired - the message was not delivered successfully
  • inbound_sent - the incoming message was delivered successfully
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
  • asc - sort ascending
  • desc - sort descending

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

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
  • sms - text only message
  • mms - message with multi-media content
direction text The type of incoming message

Values
  • inbound - incoming messages
  • outbound - outgoing messages
body text The message body
media [text] An array of URLs for media attachments (MMS)
numSegments number Number of segments required for the message
  • 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

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.

GET
/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

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