Ariadni – SMS and Email Interface Specifications

Version 2.01

1         Introduction

1.1        Scope

The present document specifies the protocols and interfaces in order submit SMS and Emails between Government departments and the Notification Gateway.

1.2        Target Audience

The intended audience for this document are:

  • Software Designers;
  • Software Developers;
  • API Developers.

1.3        Structure of this document

The document is organized as follows:

  • Chapter 1 – Introduction presents the scope and the terminology used in the document;
    • Chapter 2 – Describes the Message Specifications for the Notification Gateway;

2         Notification Gateway Message Specifications

2.1        Supported Message Patterns

The Notification Gateway supports only Synchronous exchange:

–     In the synchronous exchange, the consuming client/service waits for a business response message from the Provider service.

2.2        Supported Message Types

The Notification Gateway supports the following message type:

  • Simple Message: The e-Service should provide the submitted text
  • Template Message: The e-Service should provide tokens and values that will be replaced in a pre-defined template configured in the Notification Gateway.

2.3        Message Specifications

2.3.1     Base URL

All REST API’s are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

All URLs referenced in the API documentation have the following base:

  • https://{FQDN}/DITS.CeGG.DIS.Notifications/api/v1.0

The Production FQDN is: https://dis.gateway.local

The Test FQDN is: https://dis.dev.gateway.local

FQDN: A fully qualified domain name (FQDN) that identifies the connector host.

2.3.2     Swagger Specifications

Swagger specifications can be found in the following url:

2.3.3     Submit Simple Message

2.3.3.1    HTTP Request

To send a new simple message, make an HTTP POST to the following resource URL. Resource: https://{Base URL}/notification/simple-message

2.3.3.1.1  Authentication

HTTP request to REST API are protected with Basic authentication. In short, you will use your department notification account provided by the Gateway Team.

2.3.3.1.2  Payload

The payload must be a valid JSON object of type «Simple Message» as specified at section 2.4.1

2.3.3.2    HTTP Response
2.3.3.2.1  HTTP Headers
2.3.3.2.2  X-RequestID

The HTTP header is always returned. Contains the Message ID generated by the API. You may use this for troubleshooting.

2.3.3.2.3  Possible HTTP status Codes
HTTP StatusDescription
200 OKThe request was successful.
401 UNAUTHORIZEDThe supplied credentials, if any, are not sufficient to access the resource.
400 BAD REQUESTEmpty request body or not valid message or not valid JSON object.
404 NOT FOUNDThe server cannot find the requested resource.
500 INTERNAL SERVER ERRORIndicates that the server encountered an unexpected condition that prevented from fulfilling the request.
2.3.3.2.4  Successful Response Format

When the HTTP Status Code is 200 ?? then the response body is a JSON object of

«SendMessageResponse» (see section 2.4).

2.3.3.2.5  Error Response Format

The REST API will return an «ErrorResponse» JSON object in the HTTP response body when something goes wrong.

2.3.4     Submit Template Message

2.3.4.1    HTTP Request
2.3.4.1.1  Authentication

HTTP request to this endpoint is protected with Basic authentication. In short, you will use your department notification account provided by the Gateway Team.

2.3.4.1.2  Payload

The payload must be a valid JSON object of type «Template Message» as specified at section 2.4.2

2.3.4.2    HTTP Response
2.3.4.2.1  HTTP Headers
2.3.4.2.2  X-RequestID

The HTTP header is always returned. Contains the Message ID generated by the API. You may use this for troubleshooting.

2.3.4.2.3  Possible HTTP status Codes
HTTP StatusDescription
200 ??The request was successful.
401 UNAUTHORIZEDThe supplied credentials, if any, are not sufficient to access the resource.
400 BAD REQUESTEmpty request body or not valid message or not valid JSON.
404 NOT FOUNDThe server cannot find the requested resource.
500 INTERNAL SERVER ERRORIndicates that the server encountered an unexpected condition that prevented from fulfilling the request.
2.3.4.2.4  Successful Response Format

When the HTTP Status Code is 200 ?? then the response body is a JSON object of

«SendMessageResponse» (see section 2.4).

2.3.4.2.5  Error Response Format

The REST API will return an «ErrorResponse» JSON object in the HTTP response body when something goes wrong.

2.4        Message Data Structures

2.4.1     Simple Message

Element NameCardinalityDescriptionTypeValues
Subject0..1The subject of the messagean..500 
Body1..1The body of the messagean..4000 
Channel1..1Channel to use Possible values: eMailSMS
Recipients1..nList of recipients (email or phone numbersstring 
Origin0..1The [from] address to use in case more than one is configured for your account (email or SMS Sender Id)an..20 
Attachments0..nList of email attachmentsAttachment 

Note 1: The element «Subject» should not be set in case the message «channel» is

«SMS».

Note 2: The e-Service developer should consider the following for the body:

  • One SMS message is 160 Latin characters.
  • One SMS message is 70 Greek characters

Note 3: Attachments are only allowed in case the message channel» is «eMail».

2.4.2     Template Message

Element NameCardinalityDescriptionTypeValues
TemplateCode1..1Template code of the template to use  
TemplateLanguage1..1Language code of the template Possible Values: ENEL
Tokens0..nList of template parameters  
Channel1..1Channel to use Possible Values: eMailSMS
Recipients1..nList of recipients (emails or phone numbers)string 
Origin0..1The [from] address to use in case more than one is configured for your account (email or SMS Sender Id)an..20 
Attachments0..nList of email attachmentsAttachment 

2.4.3     Attachment

Element NameCardinalityDescriptionTypeValues
Name1..1Name of the Attachmentan..100 
Content1..1Base-64 encoded string of the content typesan 

2.4.4     Message Token

Element NameCardinalityDescriptionTypeValues
Name1..1The Name of the template parameteran..20 
Value1..1The Value of the template parameteran..250 

2.4.5     SendMessageResponse

Element NameCardinalityDescriptionTypeValues
MessageId0..1Response message idan..20 

2.4.6     ErrorResponse

Element NameCardinalityDescriptionTypeValues
Description1..1The Error Messagean..250 
Number1..1The Error Coden..10 
Print Friendly, PDF & Email