Edge provides a generic API interface to let customers to integrate with their own SMS solutions. Here, in this document you will be provided a guideline of integrating your current system with Edge's API.
CURRENT VERSION
Requests are made with v1 version via the Accept header.
Accept: application/vnd.faraday.edge.sms.v1+json
SCHEMA
Communication with Edge is done in JSON format, every request and response must have Content-Type: application/json;charset=UTF-8 in header.
SECURITY
Edge takes security of customers' services seriously, some security measures are taken to let remote service to be sure that requests belongs to Edge.
Every customer is given two system-wide-unique keys: public and secret keys.
Every request sent from Edge contains a timestamp and a hash value along with the public key. Private key resides in service to be integrated. It's used by customer to verify request is sent by Edge.
Accept → application/vnd.faraday.edge.sms.v1+json
Content-Type → application/json;charset=UTF-8
X-Api-Key → fJLFhUWTxF8LdNZnvG23
X-Timestamp → 1501570580
X-Auth → ae41c2a45ca420f5552830eeee99f8901d56b05280d450c02000d8122a3b396a
X-FN-Account → 123
X-FN-SSID → My SSID Name
{
"data": [
{
"to": "+12025550165",
"message": "1234 is the code for Faraday Networks WiFi"
}
]
}
Private key resides in service to be integrated. It's used to verify response is generated by customer.
Edge expects to get two headers in response:
- X-Timestamp, UNIX timestamp value.
- X-Api-Key, key value defined on Edge
- X-Auth: Value of following function: SHA-256(<API Secret>-<UNIX Timestamp>)
Example: If your API secret is OeaH2OTRCJa8REtSvKXb then you can use following Java code to generate X-Auth value.
char[] DIGITS = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' }; MessageDigest digest = MessageDigest.getInstance("SHA-256"); byte[] bytes = digest.digest("fJLFhUWTxF8LdNZnvG23-OeaH2OTRCJa8REtSvKXb-1501580580".getBytes()); int length = bytes.length; char[] out = new char[length << 1]; int i = 0; for (int j = 0; i < length; i++) { out[(j++)] = DIGITS[((0xF0 & bytes[i]) >>> 4)]; out[(j++)] = DIGITS[(0xF & bytes[i])]; } return new String(out);
200
Content-Type → application/json;charset=UTF-8
{"result": [{"success":true,"tx_id":12345}]}
ENDPOINTS
- Send
Description
Send request is sent from Edge to consumer service to send one or multiple SMS messages. This endpoint shall return a unique transaction id and a success flag for each message sent in request. Success flag does not determine actual sending of SMS is completed or not, it shall only represent if SMS request is added to queue successfully or not.
- Phone number will begin with country code, without leading plus or zeros.
- Using HTTPS URLs is highly recommended for your own safety.
Example Request 1
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.faraday.edge.sms.v1+json' \
-H 'X-Api-Key: fJLFhUWTxF8LdNZnvG23' \
-H 'X-FN-SSID: My SSID Name' \
-H 'X-Timestamp: 1501570580' \
-H 'X-FN-Account: 123' \
-H 'X-Auth: ae41c2a45ca420f5552830eeee99f8901d56b05280d450c02000d8122a3b396a' \
--data '{"data":[{"to":"+12025550165","message":"1234 is the code for Faraday Networks WiFi"}]}' \
'https://example.com/api/sms/send'
Example Response
200
Content-Type → application/json;charset=UTF-8
{"result": [{"success":true,"tx_id":12345}]}
Example Request 2
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.faraday.edge.sms.v1+json' \
-H 'X-Api-Key: fJLFhUWTxF8LdNZnvG23' \
-H 'X-FN-Account: 123' \
-H 'X-FN-SSID: My SSID Name' \
-H 'X-Timestamp: 1501570580' \
-H 'X-Auth: ae41c2a45ca420f5552830eeee99f8901d56b05280d450c02000d8122a3b396a' \
--data '{"data":[{"to":"+12025550165","message":"Message 1"},{"to":"+12025550690","message":"Message 2"}]}' \
'https://example.com/api/sms/send'
Example Response
200 Content-Type → application/json;charset=UTF-8 {"result":[{"success":false},{"success":true,"tx_id":12345}]}
SERVER RESPONSES
- 200 OK - the request was successful
- 201 Created - the request was successful and a resource was created.
- 204 No Content - the request was successful but there is no representation to return (i.e. the response is empty).
- 400 Bad Request - the request could not be understood or was missing required parameters.
- 401 Unauthorized - authentication failed or client doesn't have permissions for requested operation.
- 403 Forbidden - access denied.
- 404 Not Found - resource was not found.
- 405 Method Not Allowed - requested method is not supported for resource.
Comments
0 comments
Article is closed for comments.