REST API Overview

Hook Mobile REST API is designed to enable customer to quickly add SMS and MMS capabilities to their application and service. The REST API supports inbound and outbound SMS/MMS traffic as well as delivery and read status notification. Currently, client SDK or library is not available for integration with REST API; therefore, customer must develop the application logic to communicate with the REST API service. There are two components to be developed for this integration: Client and Webhook. Functionally, client component is responsible for sending outbound SMS/MMS to mobile subscriber, while the Webhook component is responsible for receiving inbound SMS/MMS as well as outbound message status update.

rest integration

Client Integration

Client integration is essential for sending outbound SMS/MMS to mobile subscriber. Hook Mobile provides complete API documentation including Authentication Requirement and Error Codes. Developer Test Console is also available for customer to explore and try out individual API methods

Webhook Integration

Webhook integration is essential for customer to receive inbound SMS/MMS from mobile subscriber. Additionally, if customer wish to be notified of outbound message status as well as other events, customer will need to complete Webhook integration. Hook Mobile provides API documentation for Webhook integration.

Authentication

Hook Mobile REST API resources are only accessible via HTTPS to ensure API call data is encrypted between Hook Mobile and your application. To protect against unauthorized access, Hook Mobile requires call level authentication for customer identity. Hook Mobile REST API supports two levels of authentication: Level 1 (Basic Authentication), or Level 2 (Basic Authentication + Signature). You can choose either authentication option based on your comfort level and your specific use case

Level 1

Basic Authentication is an industry standard for enforcing access control to HTTP resource. When API customer creates a new service, an SERVICEKEY and SECRET token pairs are assigned per service. For Level 1 authentication, SECRET token is not needed. The SERVICEKEY token is passed as the User element of basic authentication header. Below is an example of a Send SMS API request with SERVICEKEY value of 64ec992adab340dfbbbd7a1384a48824 using cURL command:

curl --user 64ec992adab340dfbbbd7a1384a48824: --data "from=13022021006&to=13012223333&text=Hello+world&deliveryReceipt=1&readReceipt=1" "https://api-max40.hookmobile.com/v1/message/sms"

Level 2

Level 2 authentication is very similar to Level 1 option above. The key difference is the additional signature needed to generate basic authentication token. Like Level 1 option, SERVICEKEY value is passed as the User element of basic authentication header. Additionally, you will need to pass the computed signature as the Password element. The signature is the RFC 2104 HMAC-SHA1 of selected elements from the request, and so the signature will vary from request to request. If the signature calculated by the Hook Mobile matches the signature submitted by the requester in the API request, the you will have demonstrated possession of the SECRET token. The request will then be processed under the identity, and with the authority of the customer to whom the key was issued. Level 2 authentication does not require whitelisting your REST client IP address.

Signature is computed using following formula:

SECRET : Secret token assigned to your for a specific service
from: Sender phone number parameter
to: Destination phone number parameter
text: Message content parameter

Signature = Base64( HMAC-SHA1( SECRET, UTF-8-Encoding-Of( from + to + text ) ) );

Below is an example of cURL command with computed signature value of frJIUN8DYpKDtOLCwo//yllqDzg=

curl --user mykey:frJIUN8DYpKDtOLCwo//yllqDzg= --data "from=13022021006&to=13012223333&text=Hello+world&deliveryReceipt=1&readReceipt=1" "https://api-max40.hookmobile.com/v1/message/sms"

Webhook Integration

Webhook is a mechanism for Hook Mobile to send events to your application. There are currently 4 types of events sent via webhook. The first 2 types of events is inbound SMS or MMS originated from mobile subscriber to a virtual number assigned to your service. The third type of event is outbound message status updates, including delivery, read and failed status. The fourth event type is an opt-out notification that informs end-user intent to opt-out from receiving future mobile message.

To enable webhook notification, you must register a URL address for accepting HTTP POST request from Hook Mobile. Each service can be configured with its own webhook URL. Updates to webhook URL may take upwards of 3 minutes to propagate into production environment.

After updating your webhook URL, you can use the Developer Test Console to validate your webhook implementation with simulated notifications. Alternatively, you can simulate a POST request with JSON payloads against your webhook URL using cURL command as follow:

curl -v -H "Accept: */*" \
        -H "Content-Type: application/json" \
        -X POST \
        -d '{"type":"sms","from":"+15125551234","to":"+1555666777", "text":"the message body"}' \
        #Your webhook URL here#

Inbound SMS Event

An inbound SMS message event is POSTed as a JSON object as follows.

{"type":"sms",
 "from":"+15125551234",
 "to":"+1555666777",
 "text":"the message body"}
                    

The JSON attributes of an inbound SMS message are as follows.

Attribute Description
type This must be sms to indicate an incoming SMS message from one of the service's users.
from The sender phone number of the message.
to The recipient phone number of the message, which is a shortcode or virtual number belonging to a service provisioned under your service.
text The body of the SMS text message.

Inbound MMS Event

For inbound MMS message event, the notification POST JSON is more complex since it contains slides inside the MMS message.

{"type":"mms",
 "from":"+15125551234",
 "recipient":"+1555666777",
 "text":"This is a text part",
 "mediaUrls":["http://xyz.com/linkyyy.jpg",
 	"http://xyz.com/linkzzz.jpg",
 	]
 }
                    

As indicated by the example, the mediaUrls attribute is an array. Each element in the array represents a slide in the MMS message. Currently, media slides are passed on as is with no alteration from upstream carrier. Media mime type is identified in the response header of individual media url.

The JSON attributes of an inbound MMS message are as follows.

Attribute Description
type This must be mms to indicate an incoming MMS message from one of the service's users.
from The sender phone number of the message.
to The recipient phone number of the message, which is a shortcode or virtual number belonging to a service provisioned under your service.
text (If present)Text content of the MMS message. There could be additional text slides passed in mediaUrls attribute
mediaUrls Array of media slides in MMS message.

Outbound Message Status Update Event

An outbound message status update event is POSTed as a JSON object as follows.

{"type":"status",
 "status":"fail",
 "errorCode":112,
 "timestamp":1481206212,
 "messageId":2897392,
 "refId":"a2l3kj4osf"}
                    

The JSON attributes of an outbound message status update are as follows.

Attribute Description
type This must be status to indicate a status update of previously sent outbound SMS/MMS.
status Status of message. Possible values include: delivery,read and fail
errorCode If status attribute contains value fail, then this attribute shall be present. Possible values for errorCode are defined in the Error Codes page
timestamp The UNIX timestamp of message status event.
messageId Message ID assigned by Hook Mobile to sent message.
refId Message ID assigned by customer to sent message.

Recipient Service Opt-Out Event

A recipient opt-out event is POSTed as a JSON object as follows.

{"type":"optOut",
 "serviceKey":"ABEASDKLVLKSADKFASLFASLFDASDF",
 "from":"+15125551234",
 "recipient":"+1555666777",
 "text":"stop"}
                    

The JSON attributes of an opt-out notification are as follows.

Attribute Description
type This must be optOut to indicate a mobile subscriber intent to opt-out your service.
serviceKey SERVICEKEY identifying the service, which user intent to opt-out from
from The phone number of the mobile subscriber opting out of your service.
to The shortcode or virtual number belonging to a service provisioned under your service.
text Message text sent by the mobile subscriber

Error Codes

REST API method call can result in failure at different stages for various reasons. An error response can be returned synchronously in the API call response or asynchronously in the webhook request. In this section, we detail the error codes and its definition.

Category Description
1xx Indicates client request format or validation error. Not retryable.
2xx Indicates client authentication errors. Not retryable.
3xx Indicates routing related error, including undefined route, blocked routes or network. Not retryable.
4xx Indicates temporary error that should be retried by caller.
5xx Indicates server side error. Not retryable.
Status code Description
101 Malformed SMS or MMS message. For SMS it could be caused by malformed GSM concatenated SMS.
102 Invalid parameter. Invalid Input parameter(s) of REST API call.
103 Invalid phone. Phone number must be in E.164 format.
104 Invalid destination address. May be caused by invalid format or invalid telephone number.
105 Invalid source address. May be caused by invalid format or invalid telephone number.
106 Asset size exceeded or message too long.
107 Unsupported address format for MMS or SIP.
201 Bad signature. Signature provided in API request does not compute correctly.
202 User authentication failure.
203 Unauthorized source IP address.
204 Destination phone number not found in whitelist.
205 Unauthorized operation.
206 Account disabled.
301 Destination network error.
302 Handset delivery error.
303 Recipient opt-ed out from service.
304 No delivery route found for given destination.
305 No Virtual Number is assigned to customer's service.
306 Blocked virtual long code. Customer must stop using this virtual long code to send message.
307 Message blocked by SPAM filter.
308 Content not approved by destination carrier.
309 Message expired before delivery by destination carrier.
310 Message blocked due to recipient opt-out.
401 Service temporary unavailable.
402 Service throughput threshold exceeded.
500 Internal system error.