Our API makes it easy for developers to send and receive ad-supported SMS messages from any website.
Want to use all 160 chars. of each message? Sign up for a monthly ad-free plan.
From $9.95/month.
Events are posted to your callback url whenever your users interact with Zeep via their phone or our settings panel. The Content-type of the POST is application/x-www-form-urlencoded. This means you can treat it almost exactly as if it were a form post from a web page. The only difference you'll notice is in how you respond.
Each post will contain an argument named event. The value of which tells you what type of mobile event you are receiving and which arguments will be present.
In most cases, if you receive an event from us your user is expecting a response. You must respond to every mobile-event with an HTTP 200 within 30 seconds of receiving it. The Content-type of the response should always be text/plain. Unless otherwise stated, anything you return in the body of the response will be sent directly to your users phone.
We do not want to keep your user waiting for a response. If an error occurs we will send them this message "<your app name> is experiencing technical difficulties, please try again later." Keep in mind we consider it an error if your server responds with any status code other than 200, takes longer than 30 seconds to respond or uses the wrong Content-type.
This event is sent to you when a user subscribes to your app or changes their mobile number using the zeep panel, or when a user subscribes to your app via SMS by using the JOIN command from their mobile device. Your response to this event should welcome them to your application.
There are two ways a user can trigger the SUBSCRIPTION_UPDATE event:
| uid | The user id you passed to us in the settings panel |
| min | User's mobile device number in e164 format |
POST /api/send_message HTTP/1.1 Host: zeepmobile.com Authorization: Zeep cef7a046258082993759bade995b3ae8:XGPPx8+Me8RBoEUTPO6LSiSLDn4= Date: Thu, 11 Mar 2010 07:01:22 GMT Content-Type: application/x-www-form-urlencoded Content-Length: 72 event=SUBSCRIPTION_UPDATE&uid=joeblow@zeepmobile.com&min=+1555555555
For your user to use the JOIN command, they simply text "JOIN <your sms prefix>" to 88147.
The only difference for your application with this method is that the uid is set to the subscriber's mobile number.
| uid | User's mobile device number in e164 format |
| min | User's mobile device number in e164 format |
POST /api/send_message HTTP/1.1 Host: zeepmobile.com Authorization: Zeep cef7a046258082993759bade995b3ae8:XGPPx8+Me8RBoEUTPO6LSiSLDn4= Date: Thu, 11 Mar 2010 07:01:22 GMT Content-Type: application/x-www-form-urlencoded Content-Length: 72 event=SUBSCRIPTION_UPDATE&uid=+1555555555&min=+1555555555
200 OK Date: Thu, 11 Mar 2010 07:01:22 GMT Content-Type: text/plain Content-Length: 18 Welcome to my app!
MO stands for "Mobile Originated". This event is sent to you when a user texts "<your sms prefix> [some message]" to 88147. You are free to respond to this any way you see fit.
There are two types of the MO event:
| uid | The user id you passed to us in the settings panel. |
| sms_prefix | Your app's SMS Prefix. |
| body | The contents of the SMS message. |
POST /api/send_message HTTP/1.1 Host: zeepmobile.com ... Content-Type: application/x-www-form-urlencoded Content-Length: 54 event=MO&uid=joeblow@zeepmobile.com&body=Hello!
When an MO comes in from an unsubscribed user, we don't pass the "uid" (userid). You can send one response to this kind of MO, but won't be able to use SEND_MESSAGE to send to this user until they've subscribed to your app.
| sms_prefix | Your app's SMS Prefix. |
| body | The contents of the SMS message. |
POST /api/send_message HTTP/1.1 Host: zeepmobile.com ... Content-Type: application/x-www-form-urlencoded Content-Length: 54 event=MO&body=Hello!
200 OK Date: Thu, 11 Mar 2010 07:01:22 GMT Content-Type: text/plain Content-Length: 7 Hi Joe!