NAV Navbar
Logo
http shell

Messaging Service - V3

Messaging API

Overview



Authentication

API access is protected with HTTP Basic Authentication. Use the portal to acquire an API key. Provide the account id as the username and the api key as the password within the Basic authentication header.

BASIC Authentication

Username - account id
Password - apikey
HTTP Header
Authorization: Basic {accountId}:{apiKey}



API access is protected with HTTP Bearer Authentication. Use the portal to acquire an API key. Provide the api key as the data within the Bearer authentication header.

Bearer Authentication

HTTP Header
Authorization: Bearer {apiKey}



Messages

Resource Actions

Resource Create (POST) Read (GET) Update (PUT) Delete (DELETE)
/messages Send Message Error Error Error

Message - Create (Send Message)

POST
/sms/v3/messages
POST https://msgapi.messagepro.com/smsmms/v3/messages HTTP/1.1
Content-Type: application/json

{
    "body":"My first test",
    "from": "18135701000",
    "to": "18135791001"
}
curl -X POST https://msgapi.messagepro.com/smsmms/v3/ \
    -H "Content-Type: application/json" \
    -d '{
        "body":"My second test",
        "from": "18135701000",
        "to": "18135791001"
        }'

Example OK Response

{
    "statusUri": "",
    "data": {
        "accountId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "apiVersion": "v3",
        "messageInfo": [
            {
                "optStatus": "notIn",
                "dateCreated": "2019-03-20T14:26:28.767+0000",
                "numSegments": 1,
                "to": "+18135791001",
                "body": "My first test",
                "uuid": "5e1e9d34-8162-4a97-8422-51da505f7636",
                "status": "accepted"
            }
        ],
        "from": "+18135701000",
        "optLogic": true,
        "to": "+18135791001",
        "body": "My first test",
        "bulk": false
    },
    "statusMessage": "Message Create Successful",
    "status": "MessageCreateSuccessful",
    "statusCode": "200"
}

Example Error Response

{
    "statusUri": "",
    "data": {
        "error_message": "'from' is not valid account",
        "accountId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "apiVersion": "v3",
        "messageInfo": [
            {
                "optStatus": "",
                "dateCreated": "2019-03-27T12:55:48.011+0000",
                "numSegments": 1,
                "to": "+18135791001",
                "body": "test",
                "uuid": "78c250fc-259e-4495-9c2e-4e4f76ecf580",
                "status": "rejected"
            }
        ],
        "from": "+18135701002",
        "optLogic": true,
        "error_code": 404,
        "to": "+18135791001",
        "body": "test",
        "bulk": false,
        "error": "MissingAccount"
    },
    "statusMessage": "Message Create Successful",
    "status": "MessageCreateSuccessful",
    "statusCode": "200"
}

}

Messages - Attributes

Attribute Type Description
Fields related to telephone numbers
Must have one and only one of to and toArray
from string The originating telephone number (TN) required
to string Single terminating Telephone Number see notes below
toArray [string] An array of terminating Telephone Numbers see notes below
Fields related to the message content
Must have at least one or both of body and media
body string The message to be sentsee notes below
media [string] An array of URLs for media attachments (MMS) see notes below
Fields related to how the message will get processed
bulk boolean Indicates that the message should use bulk processing optional
Values: false (default), true
bulk messages have lower priority and will only be sent during normal hours
optLogic boolean Indicates that the message should use opt in/out processing optional
Values: false (default), true
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
sendStatus boolean Indicates whether to return status messages optional
Values: false (default), true
responseUrl string Provide a url for status callbacks for this specific message optional
Fields related to message tracking
referenceId string This is a user defined tracking string.
Length Limit = 40. Alphanumeric [no special characters or white space].optional
userId string Indicate the user that sent this message - only used for tracking purposedoptional
userType string Indicate the type of user that sent this message - only used for tracking purposedoptional

JSON Response Data

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)

JSON Response Data - statusCode, status, statusMessage

Status Status Code StatusMessage Notes
200 MessageCreateSuccessful Message Create Successful 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 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

JSON Response Data - data

Attribute Type Description
apiVersion string v3
messageInfo jsonArray details about each to or toArray

JSON Response Data - data.messageInfo

Attribute Type Description
Fields to identify the message
to string Destination Telephone Number for this object
body string Text message that was sent
For opt in/out processing, additional text may be added to the original
uuid string UUID assigned to the message
dateCreated string ISO format date/time of when the message received
Fields 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 string opt in/out status
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)
Fields related to the status of the message
status string Alpha status code
Values: accepted, rejected, blocked
result string whether message delivery was attempted
Values: pass, fail
reason string failure reason optional
Values: international-blocked, opt-out
errorMessage string error description optional
Values: international not allowed

Webhook

Message - Incoming Message

When the system receives an incoming message, it will be delivered via the defined webhook.

POST
/sms/v3/messages
POST {webhook_url} HTTP/1.1
Content-Type: application/json

{
    "body":"My first test",
    "from": "18135701000",
    "to": "18135791001"
}

TODO