NAV

Receiving Inbound Message(Last Updated : 01/11/2017)

Overview

Our API allows two-way communication with mobile text messages. Our system will notify you when a keyword has been texted and a reply has been sent in return. Our system 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 a URL set is active. Please return a status of 200OK when an empty GET/POST is received.

This feature has many applications, 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. This provision allows customers to text in the keyword followed by any message. This message is forwarded to your server along with the keyword.

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

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 XML String to the Receiving URL

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>

Inbound Reply Message PUSH

When a recipient replies back to a message, the following XML is pushed to the receiving URL.

Example PUSH

<?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.

Example PUSH

<?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>

Keyword Message PUSH

When a subscriber sends a keyword message, the following XML is pushed to the receiving URL.

Example PUSH

<?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.

Example PUSH

<?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>

Vote Reply PUSH

When a voting participant replies back with a voting choice, the following XML is pushed to the receiving URL.

Example PUSH

<?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>

OSP Verification PUSH

When a subscriber signing up from an OSP sends back an 'VERIFY' message to the OSP Verification message, the following XML is pushed to the receiving URL.

Example PUSH

<?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>

Stop Message(Request) PUSH

When a subscriber sends a STOP request, the following XML is pushed to the receiving URL.

Example PUSH

<?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, the following XML is pushed to the receiving URL.

Example PUSH

<?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, the following XML is pushed to the receiving URL.

Example PUSH

<?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>