Outbound SMS

Overview

Summit allows you to send outbound SMS messages and provide a callback URL for the response. By POSTing to the endpoint specified below, we will originate an SMS message to the destination(s) of your choice.

You can specify the source number, but this number must be validated from the Summit platform. Currently, only numbers ordered through the Summit platform are valid SMS senders. If you don’t specify a from_number, we will use one of your Summit registered numbers (the first number in the database).

If you specify multiple from_numbers, we will attempt to alternate senders. Since Summit SMS is limited to one SMS per second per sending number, this allows you to send a larger number of messages in a shorter time if you own multiple numbers.

Authentication

The Summit REST API uses HTTP Basic Authentication. You can generate your API key at platform.corvisa.com, in the Access section, on the API Keys screen.

Outbound SMS Endpoint

The SMS endpoint is flexible and will allow you to send single or multiple SMS messages from a single or multiple from numbers. It will also allow you to assign a callback url, which our API will POST JSON data to when sending messages.

https://api.us1.corvisa.io/sms/

Note

The only method currently allowed on this endpoint is POST

Fields

  • from_number { optional } : A number or list of numbers to display as the SMS sender. If absent, we will select a number from the list of approved SMS senders for your account. If present, it must exactly match an approved number. This will be the Caller ID number seen by the recipient of your message.
  • messages { required } : List of messages to send. The fields are described below
  • text { required } : The text of your message.
  • to_number { required } : A string or list of strings representing the phone numbers of message recipients.
  • callback_url { optional }: A URL. This URL will receive a POST when the message is sent. This will allow you to track messages as they go out. This message is detailed below

Note

It is possible to exclude from_number in your request data because the system will automatically use the first number it finds associated with your account. This could result in sending from an unintended number and thus, it is recommended that you always set this value when sending messages.

JSON Examples

Since you can specify a single or multiple from_number value as well as single or multiple to_number value, here are some examples of JSON you might POST for various situations.

Note

Be sure you set the request Content-Type to application/json when posting to the endpoint

Example 1: Single sender to single recipient

[
    {
        "from_number": "+15554447001",
        "messages": [
            {
                "text":  "text of message",
                "to_number": "+15551239876",
                "callback_url": "http://myserver.com/my/sms/callback/endpoint"
            }
        ]
    }
]

Example 2: Single sender to multiple recipients using the same text

[
    {
        "from_number": "+15554447001",
        "messages": [
            {
                "text":  "text of message",
                "to_number": [
                    "+15551239876",
                    "+15554561212",
                    "+15558527532",
                    "+15559513025"
                ],
                "callback_url": "http://myserver.com/my/sms/callback/endpoint"
            }
        ]
    }
]

Example 3: Single sender to multiple recipients using individualized text

[
    {
        "from_number": "+15554447001",
        "messages": [
            {
                "text":  "text of message for person1 and person 2",
                "to_number": [
                    "+15551239876",
                    "+15554561212"
                ],
                "callback_url": "http://myserver.com/my/sms/callback/endpoint"
            },
            {
                "text":  "text of message for person 3",
                "to_number": "+15558527532",
                "callback_url": "http://myserver.com/my/sms/callback/endpoint"
            },
            {
                "text":  "text of message for person 4",
                "to_number": "+15559513025",
                "callback_url": "http://myserver.com/my/sms/callback/endpoint"
            }
        ]
    }
]

Example 4: Multiple senders to multiple recipients using the same text

[
    {
        "from_number": [
            "+15554447001",
            "+15554447002"
        ],
        "messages": [
            {
                "text":  "this will alternate sending messages from the two senders",
                "to_number": [
                    "+15551239876",
                    "+15554561212",
                    "+15558527532",
                    "+15559513025"
                ],
                "callback_url": "http://myserver.com/my/sms/callback/endpoint"
            }
        ]
    }
]

Example 5: Multiple senders to multiple recipients using different text

[
    {
        "from_number": "+15554447001",
        "messages": [
            {
                "text":  "text of message for person1 and person 2",
                "to_number": [
                    "+15551239876",
                    "+15554561212"
                ],
                "callback_url": "http://myserver.com/my/sms/callback/endpoint"
            }
        ]
    },
    {
        "from_number": "+15554447002",
        "messages": [
            {
                "text":  "text of message for person3 and person4",
                "to_number": [
                    "+15558527532",
                    "+15559513025"
                ],
                "callback_url": "http://myserver.com/my/some/other/endpoint"
            }
        ]
    }
]

Response Body

The content of the response will look something like this. The value in from_number is what the API actually sent from. In the case that you did not specify a from_number or the tried to send from an unauthorized number, the API will automatically send from a number associated with your account. This could result in sending from an unintended number, so it’s best to always assign this value when using the API.

{
    sent: [
        {
            from_number: "+15554447001"
            messages: [
                {
                    text: "hey there. are we working?",
                    callback_url: "http://myhost/cgi-bin/sms_callback",
                    to_number: "+14145554444"
                }
            ]
        }
    ]
}

Callback URL

You can optionally specify a callback_url, which will recieve information about the SMS message(s) you are sending. You can set one per message item in the messages array (see the example 5). Provided you are sending JSON with multiple message values, you should include a callback_url in each one that you would like to receive callbacks for.

Setting a value will allow our API to POST JSON data to your endpoint in the following format for each SMS sent. Please ensure your endpoint can accept JSON data. Below is a sample of what that data might look like.

Note

The callback_url is your responsibility to maintain. If your URL is unreachable when the SMS is sent, the callback will fail and will not be retried. Your endpoint should also return response status code in the 200s. Anything 300 or above will be considered a failed request. A failure to your callback url does not indicate there was a failure sending the message. The SMS message already sent by this point.

Single-Part Message (less than 160 characters)

Sending a message 160 characters or less will result in the whole message being sent at once.

{
    "Type": "Single",
    "Success": true,
    "SMSMessageId": "7d89ee80-d8b1-11e4-8830-0800200c9a66",
    "From": "+15551230001",
    "To": "+15557654444",
    "Body": "Hello there. This is a text message."
}

Multi-Part Message (more than 160 characters)

Sending a message containing more than 160 characters must be broken into smaller parts creating a multi-part message. In the example below, the text posted to the API would be “Hello there. This is a text message that is really long and had to be broken up into a multi-part message. There are limitations to how many characters a single text message can contain.” and as you can see, the message would be broken into parts because it’s too long.

{
    "To": "+14145300495",
    "Type": "Multiple",
    "From": "+14145330069",
    "Messages": [
        {
            "Body": "(1/2) Hello there. This is a text message that is really long and had to be broken up into a multi-part message. There are limitations to how many characters a ",
            "Success": true
        },
        {
            "Body": "(2/2) single text message can contain.",
            "Success": true
        }
    ],
    "SMSMessageId": "7d89ee80-d8b1-11e4-8830-0800200c9a66"
}

Opt-Out Message

Sending a message to a number that has opted out of recieving messages from the number you are originating the message from.

{
    "Success": false,
    "SMSMessageId": null,
    "From": "+15551230001",
    "To": "+15557654444",
    "Body": "Hello there. This is a text message.",
    "Failure": "Cannot send... +15557654444 opted out of messages from +15551230001"
}

Note

You are responsible for maintaining your own opt-out records, however, if we detect that the first word of any response text is “STOP” (not case-sensative), we will add the sender of such a message to the opt-out list for the phone number the text was sent to. This will prevent the sending of any future messages to this recipient from the phone number you originally sent from.