Messages


Message are all the outgoing interaction you've had with your subscribers through TextCarrier. All your auto-replies, sent campaigns, and messages to individual subscribers can be accessed via the API. The following actions can be performed on this resource...

Retrieve All Messages

Retrieves all messages associated with your account. This is for all groups and subscribers. By default, the first set of 20 groups will be returned, but you can modify this number with the limit and offset values in the query string. The max limit for a single request is 10,000.

GET https://api.textcarrier.com/v1/messages?limit=30&offset=0

Example response:


      {
            "meta":
            {
                "limit": 30,
                "offset": 0,
                "total": 1
            },
            "links":
            {
                "self": "https:\/\/api.textcarrier.com\/v1\/messages\/"
            },
            "messages":
            [
                {
                    "id":2236355334,
                     "name":"School Cancellations",
                     "body":"Attention parents... After school activitites are cancelled due to the snow / poor road conditions. See you tomorrow!",
                     "mediaUrl":null,
                     "groups":null,
                     "subscriberId":null,
                     "isAutoReply":0,
                     "isStandardMessage":1,
                     "isPollMessage":0,
                     "count":432,
                     "sent":"2017-03-02 18:20:18",
                     "scheduled":null,
                     "status":"sent",
                     "reasonFailed":null
                }
            ]
        }
        

Retrieve a Specific Message

Retrieves the single message with an ID equal to {id}.

GET https://api.textcarrier.com/v1/messages/{id}

Example response:


      {
            "links":
            {
                "self": "https:\/\/api.textcarrier.com\/v1\/messages\/2236355334"
            },
            "message":
            {
                "id":2236355334,
                 "name":"School Cancellations",
                 "body":"Attention parents... After school activitites are cancelled due to the snow / poor road conditions. See you tomorrow!",
                 "mediaUrl":null,
                 "groups":null,
                 "subscriberId":null,
                 "isAutoReply":0,
                 "isStandardMessage":1,
                 "isPollMessage":0,
                 "count":432,
                 "sent":"2017-03-02 18:20:18",
                 "scheduled":null,
                 "status":"sent",
                 "reasonFailed":null
            }
        }
        

Send a Message

Immediately sends a campaign / message to the provided group.

POST https://api.textcarrier.com/v1/messages/

Arguments

Parameter Description
action (mandatory) The action for this specific request type is SEND. This must be included or the request will fail.
groupIds (mandatory) The ID of the groups to which you want to send to. If you want to send to more than one group, simply provide a comma separated list of ids. This will send the message to the entire group or list of groups. If more than one group is specified and there are subscribers on more than one list, all duplicates will be filtered out so the message is only sent to each person once.
name The name of the message that you are sending. End users will not see this.
body (mandatory) The body of the text message you want to send. The string length may not exceed the max number of characters set on your account. That may be 132, 160 or 320. Reference the account resource to see how you can find your account's character limit. By default, its 160 unless a TextCarrier team member has changed it for you.
mediaUrl A publicly accessible url for any piece of rich media that you want to include with your message. When this parameter is used, your message is no longer an SMS but an MMS message. MMS message are allowed up to 1,200 characters in length regardless of the character limit imposed on your account.

Supported file types are: jpg, jpeg, png, gif, pdf. Other formats may work but are not guaranteed. All files must be 490 kb or less in size and return a HTTP status of 200.

It's also important to note that your file should be hosted in a place where it can be accessed heavily and at a fast rate. Our platform will retrieve your file once per subscriber and up to a rate of 250 concurent requests per second.
scheduled If you would like to schedule the message in advanced instead of sending it immediately, this parameter should be provided. It should be the America/Los_Angeles time stamp at which to send the message. Scheduled messages only send every 15 minutes and therefore can only be scheduled every 15 minutes.

Example response:


        {
            "meta":
            {
                "success": true
            },
            "links":
            {
                "self": "https:\/\/api.textcarrier.com\/v1\/messages\/356533346434"
            },
            "message":
            {
                "id":2236355334,
                 "name":"School Cancellations",
                 "body":"Attention parents... After school activitites are cancelled due to the snow / poor road conditions. See you tomorrow!",
                 "mediaUrl":null,
                 "groups":null,
                 "subscriberId":null,
                 "count":432,
                 "sent":"2017-03-02 18:20:18",
                 "scheduled":null,
                 "status":"sent",
                 "reasonFailed":null
            }
        }