Zipwhip Software API

Zipwhip’s Software API allows Zipwhip software customers to integrate Zipwhip into their proprietary CRM or line-of-business app. The Software API includes the ability to send and receive text messages on a Zipwhip text-enabled line, and to sync contacts and conversations with the Zipwhip apps.

*PLEASE NOTE: Your Zipwhip account will be charged additional fees for messages sent via the Software API. Please contact us for more information on our Software API pricing plans.*

API Specs

Zipwhip APIs are available in both OpenAPI and Postman format.

Authentication

If you are using the Zipwhip API for the first time please start by using the /user/login call to generate a session key. A session key is required for all messaging API calls to authenticate the user and phone line. A unique session key is required for every phone line that you wish to use (if you use multiple lines). The session key does not expire so make sure to record it.

Single-User vs. Multi-User Authentication

The Zipwhip Messaging API supports both single-user and multi-user authentication. They have different login requirements and allow for a different number of API user types.

Single-User Authentication

Single-user authentication means that there is a single username and password assigned to the line. Logging in with this username and password starts a session that has full administrative access. All users who share the account will be administrators.

The username for single-user logins must be the text-enabled phone number. The following is an example of a single-user login request:

$ curl -X POST \
  https://api.zipwhip.com/user/login \
  -d username=5556661234 \
  -d password=mypassword

Multi-User Authentication

Multi-user authentication means that there are several tiers of authentication. Each text-enabled line can be assigned only a single phone number, but it can be assigned multiple usernames and multiple passwords. In a multi-user scenario, you can authenticate as:

System - Uses the phone number assigned to the line and the account password to log in. As the System, you have full administrative rights. The system is meant only to perform administrative tasks, update software, or troubleshoot system issues. There is no username associated with a system session.

Administrator - The Admin username is a combination of a personal prefix and the phone number assigned to the line as the suffix: scott@5556661234. Admins have full administrative rights, the same rights as when you log in as the System. However, a username is associated with the session.

Operator - The Operator username is the same format as the Admin username. Operators have limited rights: they can send and receive messages. The Operator’s username is associated with the session. This is the suggested session for sending/recieving text messages. You can create more operator accounts by logging into your web app, going to settings and then going to the operators section.

The following is an example of an Operator login request:

$ curl -X POST \
  https://api.zipwhip.com/user/login \
  -d username=scott@4255551212 \
  -d password=scottpassword

SMS vs. MMS

The Zipwhip Software API supports two types of message requests – SMS and MMS. Text only messages are sent as SMS. Messages with file attachments are sent as MMS.

Feature SMS MMS
Maximum text body size 600 bytes 600 bytes
Maximum file attachment size NA 600 kb

If you need to send text bodies larger than 700 bytes you can send it as an MMS with a .txt attachment.

If a message does not include an attachment, it will be sent and billed as an SMS message. If it does include an attachment, it will be sent and billed as an MMS message.

File Attachments

Attachments can be added to MMS messages in .jpg, .png, .gif and .txt formats. You can send up to two attachments at a time. The maximum payload for a message is 600kb.

Message Send Status Codes

The status codes listed in this section are returned immediately when sending an SMS or MMS request via message/send or messaging/send.

If an error occurs in the send request, a "success": false message will be returned with a response object describing the error. The response object will be formatted in one of two ways.

It will include a desription of the error in the reponse.

{
  "success": false,
  "response": "Required String parameter 'body' is not present"
}

Or it will include a response object containing a nested description and status code.

{
  "success": false,
  "response": {
    "desc": "You cannot send to line opted out numbers: +XXXXXXXXXX !",
    "code": -1234
  }
}

The list of status codes that are returned in response to a send request are shown in the table below:

Code Description State Retry
-1234 Recipient sent “STOP” message, must send “UNSTOP” to resolve Failure No
-855 Internal Error Failure Yes
-704 Internal Error Failure No
-703 Internal Error - Bad argument (incorrect/invalid input) Failure No
-700 Internal Error Failure No
-394 Invalid Parameter Length Failure No
-124 Unable to Determine Carrier Failure No
-1 Unknown Error Unknown Yes

Message Delivery Status Codes

After a message has been sent, a statusCode field will be added to the message object representing its delivery status. The statusCode will change as the message flows from Zipwhip to the carrier to the handset. The delivery status can be fetched via conversation/get, message/list, and message/get APIs, or via Webhooks.

Status Code Description State Final State
0 Successful transmission - no acknowledgment from carrier Success True
1 In Process Transient False
2 Queued Transient False
4 Successful delivery to carrier Success True
5 Failed delivery to carrier Failure True
6 Successful delivery to handset (toll-free numbers only) Success True
7 Failed delivery to handset (toll-free numbers only) Failure True

messageStatus values

In addition to the statusCode, a messageStatus provides additional detail, as described in the table below.

statusCode messageStatus Description
0 1002 Message has been sent
1 999 Message queued without receipt
2 1001 Message queued for delivery
4 1003 Message accepted by Carrier
5 1005 Message rejected
5 1006 Message expired
5 1007 Message failed
5 1008 Permanent Send Error
5 1009 PARTIAL_SEND_FAILURE
5 1100 Unknown error
5 1101 Source Carrier Invalid
5 1102 Destination Carrier Invalid
5 1103 Source Not Authorized
5 1104 Source Carrier Disabled
5 1105 Destination Carrier Disabled
5 1106 No Valid Route
5 1107 Invalid Source TON
5 1108 Invalid Destination TON
5 1109 Route Denied
5 1110 User Opted Out (STOP)
5 1111 Temporary Resolution Failure
5 1112 Permanent Resolution Failure
5 1115 No Handler found
5 1116 Destination Address is not text enabled
5 1150 Spam
5 1152 Spam Reject
5 1200 Unknown error
5 1201 Message too long
5 1202 Invalid Priority Flag
5 1204 System error
5 1205 Invalid source address
5 1206 Invalid destination address
5 1207 Message ID is invalid
5 1208 Cancelling message failed
5 1209 Message replacement failed
5 1210 Message queue full
5 1211 Invalid service type
5 1212 Invalid number of destinations
5 1213 Invalid distribution list name
5 1214 Invalid destination flag
5 1215 Invalid submit with replace request
5 1216 Invalid esmeclass set
5 1217 Invalid submit to distribution list
5 1218 Submitting message has failed
5 1219 Invalid source address type of number (TON)
5 1220 Invalid source address numbering plan (NPI)
5 1221 Invalid destination address type of number (TON)
5 1222 Invalid destination address numbering plan (NPI)
5 1223 Invalid replace_if_present flag
5 1224 Invalid number of messages
5 1225 Throttling error
5 1226 Invalid scheduled delivery time
5 1227 Invalid Validity Period value
5 1228 ESME Receiver temporary error
5 1229 ESME Receiver permanent error
5 1230 ESME Receiver reject message error
5 1231 Message query request failed
5 1232 Error in the optional part of the PDU body
5 1233 TLV not allowed
5 1234 Invalid parameter length
5 1235 Expected TLV missing
5 1236 Invalid TLV value
5 1237 Transaction delivery failure
5 1238 Specified servicetype is unavailable
5 1239 Specified servicetype is denied
5 1240 Invalid data coding scheme
5 1241 Invalid source address subunit
5 1242 Invalid destination address subunit
5 1243 Insufficient credits to send message
5 3120 Invalid registered delivery flag
6 1004 Message delivered to handset
7 998 Group message was invalid or partially failed