Incoming Message Documentation

Learn about Keyword Submissions & Inbox Reply Messages

Understanding The Difference Between 
Keyword Submissions And Inbox Replies

Ez Texting allows you to implement your own APIs to receive and/or forward incoming messages to your server. Please check out the list of parameters which Ez Texting sends to your server, which your APIs must accept.

When someone sends in your keyword [space] message or just replies without a keyword within 12 hours of you sending a message to them, the Inbox Reply API is used where the variable is called from. If someone sends in only your keyword then theKeyword API is invoked and that variable is called Phone Number.

**Please note that if you are testing your API implementation with the same phone number again and again, when you send in your keyword submission and you get a reply back then the keyword reply is considered as an outgoing message. Consequently, if you send in keyword [space] message again through the same phone number, The Inbox Reply API will be invoked and NOT the Keyword API.

Many of our API clients use different scripts to process forwarded messages (messages that are replies or keyword [space] message) vs just keywords. This is the cause of the difference between the name of the variables.

If you have Send Unique Requests Checked then your Keyword URL will only be called once and not your Forwarding URL in cases when a message is considered to be a keyword submission and not a reply to an outbound message from your account.

If you have Wait for Response From My Server Checked then the system will wait for output to send back to the person who texted in. We suggest that you have both these Checked as it would work for most applications.

We have provided code examples of common implementations of the receiving APIs. They are available in the HTTP API Code Examples.

PLEASE NOTE: The Inbox management functions available via the REST API (/developers/sms-api-documentation/rest) are different than the APIs described on this page. If you use the Ez Texting Web App, you are able, via the REST API, to manage the contents of your Inbox and its folders.

 

Receiving Keyword Submissions

Description

Ez Texting allows SMS messages to be received using HTTP through the means of keywords on one of our short codes. The Ez Texting SMS Server pushes received SMS messages by making an HTTP GET request to the provided URL to indicate the receipt of an SMS message.  You can input your URL on the Keywords section (or on the API section) of your Ez Texting account.

Example URL

On receipt of an SMS we will send an HTTP GET request to your server, using the parameters included in the table below:

Parameters

PhoneNumber
10 digit phone number message originated from.

Message
The body of your message that was texted in by the originating phone number prefaced by your keyword.

Example Request Sent:
//www.yourdomain.com/receivesms.php?PhoneNumber=5554443333&
Message=Hello%20my%20friend

Return Values

When the GET post is made to your server, your script MUST output your SMS response in plain text format (max 160 characters for US accounts, and 136 characters for Canadian accounts) that will be sent back to the originating phone number through one of our shared short codes. No additional calls to our servers are necessary.

Note: The response must be given in a timely manner (sub 60 seconds) or it will be abandoned. Your server must also respond with a 200 OK Status

Note: The list of allowed characters for messages and subjects is: a-z, A-Z, 0-9 and these special characters: .,:;!?()~=+-_\/@$#&%'"

Note: The following characters count as two characters when used: ~, @, #, %, +, =, /, \, \r\n

Receiving Inbox Message Replies

Description

All replies to your inbox are forwarded to the URL you specify. The Ez Texting SMS Server pushes received SMS messages by making an HTTP GET request to the provided URL.

Example URL

On receipt of an SMS we will send an HTTP GET request to your server, using the parameters included in the table below:

Parameters

from

10 digit phone number message originated from.

message

The body of receiving message that was texted in by the originating phone number.

Example Request Sent:
//www.yourdomain.com/receivesms.php?from=5554443333&
message=Hello%20my%20friend

Options

Send unique request

Check this if you have both keyword URL and forwarding URLs setup and you do not wish to receive duplicate message forwards.

Wait for response from my server

If you require an incoming reply to have an auto-reply, select this option. We will send this response as an auto-reply to the message.

Note: Whether you have the Wait For Response From My Server option turned on or off, your server must respond with a 200 OK Status within 60 seconds or it will be abandoned.

Note: The list of allowed characters for messages and subjects is: a-z, A-Z, 0-9 and these special characters: .,:;!?()~=+-_\/@$#&%'"

Note: The following characters count as two characters when used: ~, @, #, %, +, =, /, \, \r\n