Key takeaways

  • Managing Zipwhip credentials
  • Retrieving API credentials
  • Managing credential lifecycle

Zipwhip authentication

Almost every organization that looks into using Zipwhip for automated text messaging is going to look at Zipwhip’s API. Having assisted several customers make the crawl, walk, run steps through interfacing with Zipwhip’s API, there are a few hurdles you should be aware of before you embark on the process of integrating Zipwhip into your system.

  • Undestanding Zipwhip’s authentication mechanism
  • Understanding the lifecycle of Zipwhip’s authentication token

Managing lines and authentication

Zipwhip’s API relies on a session to authenticate API requests for our Messaging API. This is different from other messaging APIs that use an apiKey in conjunction with a secret. In Zipwhip’s case, when a request is made with a session, then the system performs the action based on the static phone number associated with the provided session.

A Zipwhip session does not expire. To expire a session, you must use the user/logout API request.

Because a session does not expire, we recommend that you persist the retrieved session in a database. In the database, you must map the text-enabled phone number to the session.

We recommend that you do not hardcode this session into your code base. If an infinite loop occurs in your system, then it is much easier to delete a database row than redeploying code.

 

User login

User login allows you, as the caller, to retrieve a session and then make additional API Requests, such as sending a message or adding a new contact to your account.

A session can be tied to either a phone number or a specific Operator assigned to a phone number.

An example request for a line level session

$ curl -X POST https://api.zipwhip.com/user/login \

  --data-urlencode username=8448982526 \

  --data-urlencode password='yourReallyStrongPassword'

An example response to a line level request

{

  "response": "d7c4f618-23de-4655-8fca-fdfbe1530c21:123456789",

  "success": true

}

The response value is the session for this line.

An example request for an operator level session

$ curl -X POST https://api.zipwhip.com/user/login \

  --data-urlencode username='user@8448982526' \```SH

  --data-urlencode password='yourReallyStrongPassword'

An example response to an operator level request

{

  "response": "a3a2aa43-45ca-7879-8afa-aebcf1530e32:123456789",

  "success": true

}

The response value is the session for this user associated with a specific line.

User logout

As mentioned previously, a Zipwhip session does not expire. Therefore, as the implementer, you must to forcibly expire a session when it is appropriate for your business. Once a session is expired, all further Messaging API requests fail. The failure is due to an authorization error.

We recommend performing a key rotation on a regular basis. This rotation includes re-authenticating a line and then expiring the previous valid session. We typically see businesses perform this action monthly.

An example logout request

$ curl -X POST https://api.zipwhip.com/user/logout \

  --data-urlencode session='d7c4f618-23de-4655-8fca-fdfbe1530c21:123456789'

An example logout response

{

"response": null,

"success": true

}

More API support + readings here.


Alan Capps

Alan Capps

Alan Capps is a Solutions Engineer at Zipwhip. Zipwhip compliments their software with an API to extend the power of texting. Alan works with customers to implement full-feature texting solutions that blend the power of conversational texting and automated messaging.
Alan Capps