Specification for SMS Service

Check out the specification below to see how easy it is to integrate full SMS services into your solutions.

Specification

Each request to a feedzon web service requires a number of parameters, all listed below. All requests require an Service Key which was generated when you activated a key for that service. You can create multiple keys for each service, if required.

feedzon methods and parameters names are all case sensitive,e.g. SendMessage will work but sendMessage will not; ServiceKey=abc123 will work and SERVICEKEY=abc123 will not.

Send Message

To send an SMS message to a mobile phone.

Request Format

https://api.feedzon.com/sms/1.1/SendMessage.fz?{parameters}

Example

https://api.feedzon.com/sms/1.1/SendMessage.fz?key=uYt892VbNBmKLE2K9upE83HhjeR6342L&number=447956111222&message=Thanks for booking your portrait appointment for 2:30 pm on May 12, 2014 at the feedzon Studio. We look forward to seeing you there. T: 01923 294 955 www.feedzon.com

Returns

"0"
"112233445556677"

Where "0" means successful and "112233445556677" is the unique reference number for this SMS message. You will need this number if you later wish to check the delivery status. Note that Bulk SMS IDs are numeric and Clickatell IDs are alphanumeric.

Parameters

Name Type Description Example
ServiceKey String Your Service Key uYt892VbNBmKLE2K9upE83HhjeR6342L
Number String Phone number of recipient, use full international code, digits only. 447956111222
Message String Your SMS message Thanks for booking your portrait appointment for 2:30 pm on May 12, 2014 at the feedzon Studio. We look forward to seeing you there. T: 01923 294 955 www.feedzon.com
Sender String Optional: Sender name or mobile number. Max 11 alphanumeric characters. Do not specify this optional parameter if you want to receive replies directly to your database. Specify a mobile number if you want any replies to come only to that mobile. Replies cannot be made at all if you specify a name containing any non-numeric characters. feedzon
Repliable Numeric Optional: Use 1 to allow a reply, 0 for no replies. Note that you can only allow a reply if you do not specify a sender name or number (see notes for the sender parameter). 1

Get Message List

Download incoming messages. This includes replies to any previous outgoing messages (where the 'sender' parameter was not specified and the 'repliable' parameter was enabled - see notes for 'Send Message' function) and also incoming messages if you have a personal incoming number on your SMS provider account.

Request Format

https://api.feedzon.com/sms/1.1/GetMessageList.fz?{parameters}

Example

https://api.feedzon.com/sms/1.1/GetMessageList.fz?key=uYt892VbNBmKLE2K9upE83HhjeR6342L&cursor=112233445566

Returns

"0"
"8568639", "348274050", "2014.03.06 16:06:36", "447956653152", "Thanks for the appointment confirmation."
"8655866", "349847407", "2014.03.07 14:58:58", "447805864204", "That's fine thank you, Jane"
"8657245", "349890352", "2014.03.07 16:55:02", "447585008339", "Thx 4 reminding me.\n\nWe look forward to seeing you there :)"
etc.

Where "0" means successful; "8568639" is the cursor value (a unique reference for the incoming message - this is important, see notes below); For replies to outgoing messages, "348274050" is the unique reference number of the original outgoing message to which this is a reply, enabling you to keep conversations organised and link the incoming message to the original recipient in your solution; "2014.03.06 16:06:36" is the timestamp in YYYY.MM.DD HH:MM:SS format the message was received; "447956653152" is the full international version of the sender's phone number and "Thanks for the appointment confirmation." is the incoming message.

Note 1: Each incoming message will be on a separate line.

Note 2: To ease parsing of replies, any new paragraph or new line in an incoming message is converted to '\n'.

Note 3: If no cursor value is specified, all incoming messages in the account will be returned. You should therefore store the last cursor value and specify it when next using this function.

Parameters

Name Type Description Example
ServiceKey String Your Service Key uYt892VbNBmKLE2K9upE83HhjeR6342L
Cursor String ID of the last downloaded message 1234

Get Message Status

Get the delivery status of an outgoing message. Identifies whether the message has been delivered to the phone, is still in transit or some other status.

Request Format

https://api.feedzon.com/sms/1.1/GetMessageStatus.fz?{parameters}

Example

https://api.feedzon.com/sms/1.1/GetMessageStatus.fz?key=uYt892VbNBmKLE2K9upE83HhjeR6342L&reference=112233445556677

Returns

"0"
"112233445556677", "11"

Where "0" means successful; "112233445556677" is the unique reference for the SMS and "11" is the status of the SMS. The status value varies depending on which one of our supported gateways you're using.

Parameters

Name Type Description Example
ServiceKey String Your Service Key uYt892VbNBmKLE2K9upE83HhjeR6342L
Reference String Unique reference for the SMS 112233445556677

Bulk SMS Status Values

0 = In progress (a normal message submission, with no error encountered so far)
10 = Delivered to network
11 = Delivered to mobile
12 = Delivered upstream unacknowledged (assume message is in progress)
22 = Internal fatal error
23 = Authentication failure
24 = Data validation failed
25 = You do not have sufficient credits (with the supported gateway)
26 = Upstream credits not available
27 = You have exceeded your daily quota
28 = Upstream quota exceeded
29 = Message sending cancelled
31 = Message unroutable (probably because of invalid phone number)
32 = Blocked (probably because of recipient's request to not receive further messages from you)
33 = Failed: censored
40 = Status temporarily unavailable
50 = Delivery failed - generic failure
51 = Delivery to phone failed
52 = Delivery to network failed (probably because of invalid phone number)
53 = Message expired (probably because recipient's phone turned off for too long)
54 = Failed on remote network
56 = Failed: remotely censored
57 = Failed due to fault on handset (e.g. SIM full)
60 = Transient upstream failure (transient)
61 = Upstream status update (transient)
62 = Upstream cancel failed (transient)
63 = Queued for retry after temporary failure delivering (transient)
64 = Queued for retry after temporary failure delivering, due to fault on handset (transient)
70 = Unknown upstream status
201 = Maximum batch size exceeded

Clickatell SMS Status Values

001 = Unknown or delayed
002 = Undelivered but queued for delivery
003 = Delivered to the upstream gateway or network
004 = Confirmation of receipt on the handset of the recipient
005 = There was an error with the message, probably caused by the content of the message itself
006 = The message was terminated by a user (stop message command)
007 = An error occurred delivering the message to the handset
008 = Message received by gateway
009 = The routing gateway or network has had an error routing the message
010 = Message expired before we were able to deliver it to the upstream gateway
011 = Message has been queued at the gateway for delivery at a later time (delayed delivery)
012 = The message cannot be delivered due to a lack of funds in your Clickatell account. Please re-purchase credits
014 = The allowable amount for MT (mobile terminated) messaging has been exceeded

Response Errors

 

Error Description Cause Resolution
-1 Function doesn't exist The function name doesn't exist or has been spelled incorrectly. Please check your syntax for any errors since all function names and parameter names are case sensitive.
1000 Service Key is invalid The Service Key used to access feedzon was not recognised or has been disabled. Please check your Service Key, re-enable the service or contact us for further assistance.
1010 Missing parameters One or more parameters are missing Please check the parameters section to identify which parameters are required for the specified method.
1020 Authentication failed One of more of the SMS settings in the feedzon SMS service page are incorrect. Please check your SMS account settings in the feedzon SMS service page
1030 No messages to download A possible response to the getMessageList function when there are no incoming messages to download. N/A