ENG – HTTP Protocol

HTTP PROTOCOL #

It is possible to send SMS via HTTP Rest Api through a call structured as follows:

• URL: https://secure.agiletelecom.com/services/sms/send
• METHOD: POST
• AUTHENTICATION: Basic / Api-Key / OAuth1.1 (all in the header)
• BODY: JSON as per the example below:

{
  "globalId" : "f9b865ef-5ce3-4e44-b65c-615fd71bbd09",
  "maxIdLen" : 64,
  "enableConcatenated": true,
  "enableUnicode": true,
  "enableDelivery": true,
  "simulation": false,
  "messages":[
    {
      "destinations": ["41793026727", "417930254674"],
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dd90e", "d0f2e3c1-a043-418d-ad5e-0248184b9833"],
      "sender": "InfoSMS",
      "body": "This is a message.",
      "hexBody": false,
      "udhData": "070645670000",
      "scheduling": "2022-05-09 09:00:00.002+0200"
    },
    ...
  ]
}

The variables to be sent are as follows:

FIELD	TYPE	MANDATORY	DEFAULT	NOTES
globalId	string	no		Unique submission identifier for the client
maxIdLen	integer	no	64	Maximum length (characters) of ids
enableConcatenated	boolean	no	true	Enable concatenates if necessary
enableUnicode	boolean	no	true	Enable unicode text
enableDelivery	boolean	no	true	Enable delivery to the customer
simulation	boolean	no	false	Allows simulation, without actual sending of the message
messages	array	yes		List of messages to be sent. Each message can have multiple recipients
destinations	array	yes		List of recipients of a message
ids	array	no		List of message related IDs
sender	string	yes		Sender of messages to be sent
body	string	yes		Message text
hexBody	boolean	no	false	Indicates whether the text is entered in HEX or in normal UTF8/16
udhData	string	no		If present, it indicates the UDH code to be included in the message
scheduling	string	no		Programming date, in the format “yyyyy-MM-dd HH:mm:ss.SSSZ”

The response will be in JSON format (with Jsend specification in case of errors):

• 2XX (message accepted by the server)

{
  "globalId": "f9b865ef-5ce3-4e44-b65c-615fd71bbd09",
  "processedMessages": 2,
  "processedSmsParts": 4,
  "credit": 10.324
}

FIELD	TYPE	NOTES
globalId	string	Value of globalid reported by the request
processedMessages	integer	Messages accepted as per the messages section on the request
processedSmsParts	integer	Parts that will be shipped (differs from previous in case of concatenates)
credit	double	Account credit remaining expressed in €

• 4XX (request rejected due to formal errors in parameters)

{
    "status": "fail",
    "data": { 
		"body": "Missing message body(ies)" 
		"number": "Wrong destination number(s)"
		
	},
	"code": 6
}

FIELD	TYPE	NOTES
status	string	It always applies “fail” for 4XX errors
data	object / string	It contains a key-value list, where the keys indicate the field to be passed in and the value indicates the problem found on that field. Or a string describing the problem.
body/number/…	string	These are two possible examples of fields passed to the API where problems were encountered
code	integer	Custom error code. Indicates the type of problem as specified in the error code table given next

• 5XX (request not processed due to server-side errors)

{
    "status": "error",
    "message": "Number check service unavailable",
	"code": 9
}

FIELD	TYPE	NOTES
status	string	“Error” always applies to 5XX errors
message	string	Describes the type of server-side problem encountered while processing the request
code	integer	Custom error code. Indicates the type of problem as specified in the error code table given next

Table of error codes:

CODE	DESCRIPTION
1	Wrong credentials
2	Insufficient credit
8	Server error
9	Server error (service timeout)
100	Source IP is not allowed

HTTP Delivery #

Used by AgileTelecom to send SMS delivery confirmation to customers who have requested it. Clients will receive an HTTP Rest API call to the URL they specified structured as follows:

• URL: customer-defined
• METHOD: Post
• AUTHENTICATION: none
• BODY: JSON (as per the example below)

{ 
  "messageId": "157d541b-e0cd-4340-ac77-bc5d530dd90e", 
  "destination": "41793026727",
  "statusCode": 3,
  "description": "Delivered",
  "doneDate": "2022-05-09 09:00:05.002+0200",
  "concatTotal": 2,
  "concatProgressive": 1,
  "lcrOperator": "22210",
  "realOperator": "22201",
  "price": 0.003
}

FIELD	TYPE	NOTES
messageId	string	ID that uniquely identifies for the client the messages sent
destination	string	Phone number of the recipient of the sent message
statusCode	integer	Code identifying the receiving status of the message1: Accepted2: Rejected3: Delivered4: Expired5: Deleted6: Undeliverable
description	string	Status description
doneDate	string	Date related to delivery
concatTotal	integer	Number of total parts in case of concatenated message
concatProgressive	integer	Message part number in case of concatenated message
lcrOperator	string	(Optional, can be activated with customer parameter) Operator identified by LCR service.
realOperator	string	(Optional, can be activated with customer parameter) Real destination number operator
price	double	(Optional, can be activated with customer parameter) Cost of sending