TelAPI

InboundXML Documentation

View REST Docs

SMS Element

TelAPI allows SMS messages to be sent during a call using the <Sms> element. 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.

action URL Parameters

In addition to the default voice request parameters, these parameters are forwarded to the action URL.

Attribute Description
SmsSid
The Sid TelAPI has assigned for the SMS message.
SmsStatus
The current status of the SMS message. Either sent or failed.
Body
The text of the SMS message you want to send. 160 character limit.

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 say "I will now send an SMS!" and then send an SMS that reads "Test message sent from TelAPI!" to the specified from number.

<Response>
	<Say>I will now send an SMS!</Say>
	<Sms from="{phone_number}" 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.