SMS API Banner

Trumpia
Inbound Message

(Last Updated: 01/26/2016)
Incoming SMS Message

Our API allows two-way communication for mobile text messages. Our system will notify you when a keyword is texted and reply has been sent in return. Our system also parses all incoming text messages, identifies the keywords, then forwards them to the web URL via HTTP GET. The incoming web URL can be set under Account -> API Settings.

Please note that the API server has an activity URL checker in place. This URL checker will send empty HTTP GETs/POSTs to see if the URL set is active. Please return a status of 200OK when an empty GET/POST is received.

There are many applications of this feature, including the ability to generate an automated response to a customer's text message based on the contents of the text message. You can also use this feature to trigger a procedure or some action on your server whenever a customer sends a text message to your keyword.

Keywords can be set up via our website or the API and can be configured to accept a message after the keyword. So, customers can text in the keyword followed by any message. This message is also forwarded to your server.

A simple example would be a search engine application where the keyword is "search" and the message would be the search criteria. Our system would forward this text message to the client's server and the client's server would run the query and send the results back to the customer using our API.

Receiving URL
Set a URL to which Trumpia can push inbound messages to with the GET method and a query string.
Inbound Message
This flag needs to be turned on to push inbound messages to the Receiving URL.
Sign-up via Keyword
If this flag is disabled, people who text in your keyword will not be added to any distribution list.
Notification for Keyword Sign-up or Message
If this flag is disabled, push notifications for keyword signups and inbound SMS messages will not be forwarded to your server.
Notification for Data Capture
If this flag is disabled, push notifications for Data Capture will not be forwarded to your server.
Auto-response for Keyword Sign-up or Message
If this flag is disabled, auto-response messages for keywords will not be sent.
Inbox for Keyword Messages
If this flag is disabled, inbound SMS messages will not be stored in your API account inbox.
Trumpia REST API Inbound PUSH xsd
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="API">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="PHONENUMBER" type="xs:phoneNumber" />
        <xs:element name="KEYWORD" type="xs:keyword" />
        <xs:element name="SUBSCRIPTION_UID" type="xs:unsignedLong" />
        <xs:element name="CONTENTS" type="xs:string" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name="phoneNumber">
    <xs:simpleType>
      <xs:restriction base="xs:nonNegativeInteger">
        <xs:minLength value="10" />
        <xs:maxLength value="20" />
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name="keyword">
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:pattern value="[0-9a-zA-Z]{5,50}" />
      </xs:restriction>
    </xs:simpleType>
  </xs:element>
</xs:schema>
Example URL Call:

Sample GET call to PUSH a message from a subscriber;

http://www.yourserver.com/inboundsms.php?xml=<?xml version="1.0" encoding= "UTF-8" ?><API><PHONENUMBER>2003004000</PHONENUMBER><KEYWORD /><SUBSCRIPTION_UID /><CONTENTS><![CDATA[contents]]></CONTENTS></API>
Keyword Message PUSH

When a subscriber sends a keyword message, the following XML is pushed to the 'Receiving URL':

<?xml version="1.0" encoding="UTF-8" ?>
<API>
  <PUSH_ID>1234561234567asdf123</PUSH_ID>
  <INBOUND_ID>9996663330001</INBOUND_ID>
  <SUBSCRIPTION_UID>987987987980</SUBSCRIPTION_UID>
  <PHONENUMBER>7777722222</PHONENUMBER>
  <KEYWORD>KEYWORDNAME</KEYWORD>
  <CONTENTS><![CDATA[Keyword Message]]></CONTENTS>
  <ATTACHMENT />
</API>
Data Capture PUSH

When a subscriber submits Data Capture information, the following XML is pushed to the 'Receiving URL':

<?xml version="1.0" encoding="UTF-8" ?>
<API>
  <PUSH_ID>1234561234567asdf123</PUSH_ID>
  <INBOUND_ID>9996663330001</INBOUND_ID>
  <SUBSCRIPTION_UID>987987987980</SUBSCRIPTION_UID>
  <PHONENUMBER>7777722222</PHONENUMBER>
  </KEYWORD>
  <DATA_CAPTURE>DATA_FIELD_LABEL</DATA_CAPTURE>
  <CONTENTS><![CDATA[Data Capture Response]]></CONTENTS>
  <ATTACHMENT />
</API>
Reply Message PUSH

When a recipient replies back to a message, the following XML is pushed to the 'Receiving URL':

<?xml version="1.0" encoding="UTF-8" ?>
<API>
  <PUSH_ID>1234561234567asdf123</PUSH_ID>
  <INBOUND_ID>9996663330001</INBOUND_ID>
  <SUBSCRIPTION_UID>987987987980</SUBSCRIPTION_UID>
  <PHONENUMBER>7777722222</PHONENUMBER>
  <KEYWORD>REPLY</KEYWORD>
  <CONTENTS><![CDATA[A sample reply message]]></CONTENTS>
  <ATTACHMENT />
</API>

When a recipient replies back to a landline number and not a short code, the <RECIPIENT> data is included in the XML data pushed to the receiving URL.

<?xml version="1.0" encoding="UTF-8" ?>
<API>
  <PUSH_ID>1234561234567asdf123</PUSH_ID>
  <INBOUND_ID>9996663330001</INBOUND_ID>
  <SUBSCRIPTION_UID>987987987980</SUBSCRIPTION_UID>
  <RECIPIENT>2222200000</RECIPIENT>
  <PHONENUMBER>7777722222</PHONENUMBER>
  <KEYWORD>REPLY</KEYWORD>
  <CONTENTS><![CDATA[A sample reply message]]></CONTENTS>
  <ATTACHMENT />
</API>
Stop Message(Request) PUSH

When a subscriber sends a STOP request;

<?xml version="1.0" encoding="UTF-8" ?>
<API>
  <PUSH_ID>1234561234567asdf123</PUSH_ID>
  <INBOUND_ID>9996663330001</INBOUND_ID>
  <SUBSCRIPTION_UID>987987987980</SUBSCRIPTION_UID>
  <PHONENUMBER>2003004000</PHONENUMBER>
  <KEYWORD>STOP</KEYWORD>
  <CONTENTS><![CDATA[stop]]></CONTENTS>
  <ATTACHMENT />
</API>
Deactivate Number PUSH

When a subscriber is unsubscribed due to a deactivate notification from the carrier:

<?xml version="1.0" encoding="UTF-8" ?>
<API>
  <PUSH_ID>1234561234567asdf123</PUSH_ID>
  <INBOUND_ID />
  <SUBSCRIPTION_UID>987987987980</SUBSCRIPTION_UID>
  <PHONENUMBER>2003004000</PHONENUMBER>
  <KEYWORD>Deactivate By Carrier</KEYWORD>
  <CONTENTS />
  <ATTACHMENT />
</API>
Blocked Number PUSH

When a subscriber is blocked by the carrier:

<?xml version="1.0" encoding="UTF-8" ?>
<API> 
  <PUSH_ID>1234561234567asdf123</PUSH_ID>
  <INBOUND_ID />
  <SUBSCRIPTION_UID>987987987980</SUBSCRIPTION_UID>
  <PHONENUMBER>7777722222</PHONENUMBER>
  <KEYWORD>BLOCKED</KEYWORD>
  <CONTENTS />
  <ATTACHMENT />
</API>
OSP Verification PUSH

When a subscriber signing up from an OSP sends back an 'OK' message to the OSP Verification message:

<?xml version="1.0" encoding="UTF-8" ?>
<API>
  <PUSH_ID>1234561234567asdf123</PUSH_ID>
  <INBOUND_ID>9996663330001</INBOUND_ID>
  <SUBSCRIPTION_UID>987987987980</SUBSCRIPTION_UID>
  <PHONENUMBER>2003004000</PHONENUMBER>
  <KEYWORD>VERIFICATION</KEYWORD>
  <CONTENTS><![CDATA[ok]]></CONTENTS>
  <ATTACHMENT />
</API>
Vote Reply PUSH

When a voting participant replies back with a voting choice:

<?xml version="1.0" encoding="UTF-8" ?>
<API>
  <PUSH_ID>1234561234567asdf123</PUSH_ID>
  <INBOUND_ID>9996663330001</INBOUND_ID>
  <SUBSCRIPTION_UID>987987987980</SUBSCRIPTION_UID>
  <PHONENUMBER>2003004000</PHONENUMBER>
  <KEYWORD>VOTE</KEYWORD>
  <CONTENTS><![CDATA[1]]></CONTENTS>
  <ATTACHMENT />
</API>
TOP
REST Technical Guidelines HTTP(Ver.2) Technical Guidelines