Zoom Connect REST API

Getting Started

Our REST API helps developers integrate Zoom Connect with their existing systems quickly and easily.

Here's the short version of what you need to do:

  • Register - once you have created your Zoom Connect account, create an API token on the Developer Settings page
  • Be a good API citizen - read, understand, and abide by the terms of use
  • Authenticate - all API requests need to be authenticated
  • Build cool stuff :)
Code snippets
Get started in no time at all with our PHP, Java, C#, Python, and Node code snippets: view code snippets

Authentication

Requests to Zoom Connect are authenticated by providing your account email address and API token as request header attributes named email and token respectively. Your API key is securely encrypted by the SSL channel. Basic Authentication is also supported, using your email address and API token as the username and password.

You may also provide the email and token as URL parameters, although this only recommended for testing purposes as your API token will not be encrypted.

Character Encoding

Please note that SMS uses GSM7 character encoding by default, which allows for 160 characters in a single SMS. Should you send messages in non-GSM7 character encoding, the available character count is reduced to 70.

You are able to get the credit cost of an SMS, the number of SMS parts that it would require to send a specific message, as well as the encoding which would be used through the frontend or via API. It is your responsibility to ensure you are sending using the desired character encoding.

Interactive API Documentation

Our Interactive API provides detailed documentation and allows live interaction with the following functions:

  • Retrieving your account balance
  • Sending and scheduling an SMS
  • Managing your contacts
  • Managing your groups
  • Managing your messages
  • Managing your templates

All methods are relative to the following base URL: https://www.zoomconnect.com/app/


Receiving a reply

Zoom Connect provides two possible methods for receiving replies by API, either by Webhooks or by Polling. Using Webhooks is the preferred method as it allows messages to be received efficiently and in real-time.

When using webhooks, all replies received are sent as a POST request to a specified URL. To set the message forward URL please login to Zoom Connect, click on your company name, click on “Developer settings” and paste the URL to which inbound replies are to be forwarded.

Note that while polling the server for new replies is possible, should this result in high server load, the requests may be rate limited resulting in a delay in receiving replies.

          
	http://yourserver.com/receive-sms.php?
	  from=+27725551234
          &repliedToMessageId=121212
	  &messageId=124567
	  &message=REPLY
	  &date=201404282055
	  &campaign=shoe campaign
	  &dataField=custom
	  &nonce=89430dc5-cac1-4795-9dd0-46c9b8233e52
	  &nonce-date=20140428210027
	  &checksum=180f27d80dd05886e81da0c2ccebf830bc85c7ae
          
        

Receiving a delivery report

Similar to receiving replies, all delivery reports received are sent as a POST request to a specified URL. To set the delivery report URL please login to Zoom Connect, click on your company name, click on “Developer settings” and paste the URL to which delivery reports are to be forwarded.

          
	http://yourserver.com/delivery/report.php?
	  nonce=6110900b-a3e3-4ae7-9c80-c446086f8882
	  &status=DELIVERED
	  &messageId=40124213
	  &checksum=195e39edfffed7e5ac87e85f3a6dd70ed8684b22
	  &nonce-date=20160120103235
          
        

Validating a received message

A shared secret key is used to generate an HMAC-SHA1 checksum based on the unencoded parameter data sent from Zoom Connect to your server. This checksum is sent as a parameter with the other data. If an attacker were to alter any of the parameters, the checksum will no longer match and you should reject the request.

An expiry date field named nonce-date, also included in the checksum, is sent as a parameter with each request. This expiry date may be used to ensure requests are not resent.

          
            $privateKey = 'secret';
            $params['to']='+27725551234';
            $params['from']='+27726661234';
            $params['campaign']='campaign'; // (if not null)
            $params['dataField']='data'; // (if not null)
            $params['date']='201405161005';
            $params['messageId']='24567';
            $params['message']='Test + Message';
            $params['nonce']='e273f177-6275-974f-1a12-0d8b92c5b3cb';
            $params['nonce-date']='2014051610050102'; // format: yyyyMMddHHmmss

	    ksort($params);
	    $message = "";
	    foreach ($params as $key => $val) { $message .= "$key=$val&"; }
	    $message = substr($message, 0, -1);
	    $checksum = hash_hmac('sha1', $message, $privateKey);

	    /**

              Expected message to be hashed (i.e. $message, split across lines for readability)
              campaign=campaign
		&dataField=data
		&date=201405161005
		&from=+27726661234
		&message=Test + Message
		&messageId=24567
		&nonce=e273f177-6275-974f-1a12-0d8b92c5b3cb
		&nonce-date=2014051610050102
		&to=+27725551234

	      Expected checksum (i.e. $checksum):
	      9d0e933a457eabf94a73d7e15dd8849e89834464

            **/