TelAPI

InboundXML Documentation

View REST Docs

SMS Element

The <Sms> element can be used to send SMS messages. The SMS receiver (to attribute) must be a valid phone number and the sender (from attribute) must be one of your registered TelAPI numbers. Text of the message should be placed inside the element and can not be longer than 160 characters.

The action attribute can be used to direct the SMS to a new InboundXML document for processing. If directed to a new InboundXML using the action attribute, all InboundXML beneath the <Sms> element in the originating InboundXML document is disregarded. Similarly, the statusCallback attribute is provided to report the outcome of the SMS transmission.

Element Attributes

The attributes below can be used to change some <Sms> behaviors.

Attribute Description
to
optional
The phone number that will receive the SMS message. If this parameter is not specified, the SMS will be sent back to the number that made the request to the TelAPI number's SMS request URL.
from
optional
The number that will display as sending the SMS message. This should be one of your TelAPI numbers. If this parameter is not specified, the default from number is the TelAPI number hosting the SMS request URL.
action
optional
URL to direct TelAPI to once the <Sms> element is executed. Paramaters specific to <Sms> are sent here along with the request.
method
optional
Method used to request the action URL.
Default Value:
POST
Allowed Value:
POST or GET
statusCallback
optional
URL where the status of the SMS can be sent.

Nesting

The <Sms> element cannot be nested within any other verbs besides the default <Response> element.

The <Sms> element cannot nest any other elements within itself. It must only nest the text which is to be sent in the message.

Example InboundXML Document

The InboundXML below will send an SMS that reads "Test message sent from TelAPI!" to the designated from number. All secondary parameters are then forwarded the provided action and statusCallback URLs.

<Response>
    <Sms action="http://liveoutput.com/telapi-test-sms-action" method="POST" from="{phone_number}" statusCallback="http://liveoutput.com/telapi-test-status-callback" to="{phone_number}">Test message sent from TelAPI!</Sms>
</Response>

Helper Example

Our helper libraries simplify the task of generating InboundXML while programming. The code below will output the above InboundXML example.



Tips

  • There is a 70 character limit on SMS Messages which contain unicode symbols.
  • There is a 1 SMS per second rate limit on SMS Messages by default. If you need to send SMS messages at a higher rate, contact us.

SMS Filtering

All TelAPI numbers which haven't yet had a user supplied SMS request URL set are provided with the following default SMS filtering behaviors:

  • If a recipient replies to a TelAPI SMS message with STOP, QUIT, or UNSUBSCRIBE, they will no longer receive SMS messages from that number.
  • The keywords START, YES, or SUBSCRIBE revert this blocking.
  • HELP informs the recipient of the above keywords.
  • Once an SMS request URL is set, this default behavior stops, allowing developers to implement their own SMS filtering solution.