## SMS SMS is used widely all over the world as a direct way to communicate with your customers. The robustness of the SMS-infrastructure guarantees that a message is delivered almost anywhere in the world. The fact that a SMS cut’s though the information blur and is for the vast majority of messages read within 5 minutes makes it a perfect information channel for critical and personal information. Our SMS API allows you to send international SMS messages for both security and business critical communications as well as general customer notifications and crm-communication. Features include: -Send custom messages. -Send standard or custom messages containing a random verification code created by ZignSec or generated by you. -Set your own sender-id’s or originators as a phone number, a text or a shortcode. -Send standard or custom messages using a broad range of languages specific characters. Some markets are more difficult then others when it comes to SMS delivery. ZignSec have many years of experience in the field of SMS and a very flexible platform supporting your special needs. If you are unsure of the special restrictions for a particular markets reach out to us at [email protected]. Example’s of countries requiring special setups are: -France. Special T&C needs to be followed including use of pre-defined shortcode or alpha nummeric sender-id. -Most of Middle East. Most countires require pre-registration of sender-id’s for best delivery. -Russia. Pre-registration of sender-ids are required for best delivery -Turkey. Pre-registration of sender-ids are required for best delivery -US & Canada. Messages need to be send using a pre-defined toll-free number or Shortcode. ### API Documentation An API for sending SMS or One-time verification codes. ### API Calls **Send SMS**:`POST` to https://(env).zignsec.com/v2/mmessaging **SMS status**:`GET` from https://(env).zignsec.com/v2/mmessaging/(id)/(code) where `(env)` is API or test. The `id` is the message identifier from send call’s response.`(code)` is optional when OTP validation is performed. ### Overview of Use Cases The two methods in the SMS Messaging API: -Send an SMS. Optionally use the SMS for a mobile verification, also known as sending an OTP code (One Time Password) to verify the access to the mobile phone. Theses added parameters for OTP are described here. -Check the delivery status of a sent SMS. Optionally validate the OTP code simultaneously if that was the use case. Note that this API has two use cases – for sending SMS and for OTP verification, ie sending and verifying one-time passwords, aka Two Factor Authentication (2FA). In the 2FA use case, we auto-generate in the message an OTP code for the end user to validate (OTP=One Time Password). If the SMS text contains the text **{0}** it means you want to run the OTP Login use case. The {0} text will be replaced with an auto-generated four-digit OTP code, and the delivery status end-point will be both be a validator of the correct OTP code, and reporter of the current SMS delivery status. ### Common Response JSON for Send and Status This Response is returned both after a Send and after a Status Check. ### Step 1. Send an SMS To send a SMS message, optionally for Otp verification. #### API POST to https://(env).zignsec.com/v2/mmessaging where `(env)` is api or test. ### Request Header In order to send a message you need to authenticate yourself using the credentials given by ZignSec. | | | | |---|---|---| |Authorization|Specifies the ZignSec authorization that you get from ZignSec Example:`Authorization: 00000000-e2a2-4968-b651-5352305c9fb0`|Required| |Content-Type|Specifies the media type of the request body data. Set to application/x-www-form-urlencoded for post data and application/json for JSON object. Example:`Content-Type: application/x-www-form-urlencoded`|Required| |Host|Use test.zignsec.com for test environment and api.zignsec.com for production environment. Example:`api.zignsec.com`|Required| ### Request Body This request contains: |**Parameter**|**Desription**|**Required**| |---|---|---| |from|This is the Sender. Numerical is max length of 16. Alphanumeric sender is limited to GSM default alphabet with max length of 11. This is also called the SenderID. Example:`This is the Sender. Numerical is max length of 16. Alphanumeric sender is limited to GSM default alphabet with max length of 11. This is also called the SenderID. Example:`|Yes| |to|The receiver´s phone number including country code, but not including a leading + or 00. Example:`to=46123456789`|Yes| |text|The SMS body. Messages where type is text (the default) are in UTF-8 with URL encoding. Contents of the message, URL encoded is necessary. Note: If the text contains the string The SMS body. Messages where type is text (the default) are in UTF-8 with URL encoding . Contents of the message, URL encoded is necessary._Note: If the text contains the string {0} the use case 2FA-login is activated and the {0} is replaced with an auto-generated four digit OTP code_. Message longer than 160 characters will automatically concatenate to up to 13 SMS with 153 characters each for a total length of 2000 characters. Each part in a concatenated message is credited as one SMS. You can see the full UTF-8 character set here: [http://www.fileformat.info/info/charset/UTF-8/list.htm]. To test if your message can be URL encoded, use: http://www.url-encode-decode.com/. Example: text=This+is+the+URL-encoded+message the use case 2FA-login is activated and the 0 is replaced with an auto-generated four digit OTP code. Message longer than 160 characters will automatically concatenate to up to 13 SMS with 153 characters each for a total length of 2000 characters. Each part in a concatenated message is credited as one SMS. You can see the full UTF-8 character set here: http://www.fileformat.info/info/charset/UTF-8/list.htm. To test if your message can be URL encoded, use: [http://www.url-encode-decode.com/]. Example:`text=This+is+the+URL-encoded+message`|Yes| ### Example: ```json Authorization: 00000000-e2a2-4968-b651-5352305c9fb0 Content-Type: application/json Host: test.zignsec.com Content-Length: 71 { "to":"46123456789", "from":"ZignSec", "text":"This+is+the+URL-encoded+message {0}", "RelayState":"123456" } ``` ### OTP OTP stands for One Time PIN and is used to carry out 2FA (Two Factor Authentication) with help of a phone number. ZignSec makes it easy to generate, implement and verify a OTP-code. If you want to use an OTP, insert “{0}” in the text of the SMS and ZignSec generates the code and replace it automatically. To validate that the user enters the correct code see section “Receiving SMS status” in this document. Example with OTP generation: text=Enter+the+following+code+to+log+in%3A+%7B0%7D SMS in plain text: “Enter the following code to log in: 0” SMS to the phone: “Enter the following code to log in: 422423” The code has a time validity of 5 minutes and allows for up to three failed login attempts before blocking it. Use the below value to add a OTP-code in your message request. `verify_code` [Optional] By default ZignSec generates this 6 digit numeric value. If you prefer to use your own code can you override the default value by including a numeric value between 100 and 9999999. Example: `to=547933` Upload the code entered on your website or in your app by using the Status SMS request and use the code value described below. code You can provide an user entered code to the API to validate it. This is preferable because we can do a better risk assessment. In example the correct OTP-code in the SMS is “12345” Example:`https://test.zignsec.com/v2/mmessaging/fa15b9c4-5156-4ba9-9516-eef03a15e16c/12345` Check if the code has been successfully validated with the status given in the SMS Status response. `sms.state` Possible values are `PENDING, FINISHED, VALID, INVALID`. VALID and INVALID is used when OTP-code is generated, if not the final state is FINISHED. ### Response Each Send SMS request returns a response with status and details. Both the Send SMS and the Status request follow the same repsonse structure described below. ### Keys and values | | | |---|---| |id|A GUID value used to identify the web service request. The value is unique to each web service request, is randomly-generated by ZignSec, and is returned in the response message immediately following the web service request.| |errors|A JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair of parameters is returned for each error. `code` Code for the error. List of codes is in table below. `description` A string that describes the type of error that occurred. If no errors occur, then this object is empty.`errors : []`| |result|An object that describes the result; it contains the following parameters: `sms.state` Possible values are `PENDING, FINISHED, VALID, INVALID`. VALID and INVALID is used when OTP-code is generated, if not the final state is FINISHED.| |sms|An object that describes the status of the SMS. The following parameters can be found in this object. `smsid` The unique ID of the message that was sent. `status.code` Code for the error. List of codes is found below.`status.description` A string that describes the type of error that occurred.`status.updated` Time and date then last updated.| ### Table of response errors |**Code**|**Description**| |---|---| |INVALID_TO|Invalid “To”| |INVALID_FROM|Invalid “From”| |INVALID_TEXT|Invalid ”Text” length. The maximum length of text message that you can send is 2000 characters| |INVALID_APPID|Invalid ”AppID”| |MISSING_CONFIG|Your account has a missing config, contact ZignSec for help| |INVALID_REQUEST|Something unexpected has gone wrong, contact ZignSec for help| ### Table of status |**Code**|**Description**| |---|---| |100|Delivered to phone| |101|Delivered to SMSC| |102|Queued on SMSC| |103|Non-Delivered to SMSC| |104|Non-Delivered to Phone| |105|The message is pending| #### Example ```json { "id" : "89772638-c373-4cde-8742-946b24c8e0a6", "errors" : [], "result": { "sms": { "state": "PENDING" } }, "sms": { "SmsId": "5cc5484a-9903-49dd-817f-74003ce5f7a2", "status": { "code": 105, "description": "The message is pending", "updated": "2016-10-05T15:25:22.2144377+02:00” } } } ``` ### Step 2. Check the delivery status ### API GET from https://(env).zignsec.com/v2/mmessaging/(id)/(code) where `(env)` is API or test and `(code)` is optional when OTP validation is performed. The `(id)` parameter in the URL is our SMS identification code, and should be the id in the response from the initiating send message API call. ### Notification As for all ZignSec APIs, you can either pick up the status of the message you with a GET request, or register a webhook to have ZignSec push a notification to you. ### Response Body The response body contains a JSON object with same parameters as in the response section. `id` The reference identifier that ZignSec generated and returned in its response to your POST to this web service request. This value uniquely identifies each ZignSec web service request. Example:`https://test.zignsec.com/v2/mmessaging/fa15b9c4-5156-4ba9-9516-eef03a15e16c>` `code` You can provide an user entered code to the API to validate it. This is preferable because we can do a better risk assessment.. In example the correct OTP-code in the SMS is “12345” Example:`https://test.zignsec.com/v2/mmessaging/fa15b9c4-5156-4ba9-9516-eef03a15e16c/12345` ### GET Session results by Session Id ```json GET https://test.zignsec.com/v2/mmessaging/89772638-c373-4cde-8742-946b24c8e0a6/ HTTP/1.1 Authorization: 00000000-e2a2-4968-b651-5352305c9fb0 Content-Type: application/json Host: test.zignsec.com ``` ```json { "id": "89772638-c373-4cde-8742-946b24c8e0a6", "errors": [], "result": { "sms": { "state": "FINISHED" } }, "sms": { "SmsId": "de3b3b09-1dc5-498c-adfc-8cef7b94c6b2", "status": { "code": 100, "description": "Delivered to phone", "updated": "2022-04-28T08:33:02.0429653Z" } }, "relayState": "ZignSec" } ``` ### GET Session validation results by Session Id and 4 digits code ```json GET https://test.zignsec.com/v2/mmessaging/89772638-c373-4cde-8742-946b24c8e0a6/12345 HTTP/1.1 Authorization: 00000000-e2a2-4968-b651-5352305c9fb0 Content-Type: application/json Host: test.zignsec.com ``` ```json { "id": "89772638-c373-4cde-8742-946b24c8e0a6", "errors": [], "result": { "sms": { "state": "VALID" } }, "sms": { "SmsId": "de3b3b09-1dc5-498c-adfc-8cef7b94c6b2", "status": { "code": 100, "description": "Delivered to phone", "updated": "2022-04-28T08:33:36.764019Z" } }, "relayState": "ZignSec" } ```