# SMS - Get started

## API Documentation <a href="#howtos-apidocumentation" id="howtos-apidocumentation"></a>

API Swagger Documentation is available here :

{% embed url="<https://messages.cloud.cegedim.com/swagger-ui/index.html>" %}

## URL & Base URI <a href="#howtos-url-and-baseuri" id="howtos-url-and-baseuri"></a>

Vortext API base path is located at :

* `https://vortext.cloud.cegedim.com` for services hosted in cegedim.cloud datacenters.
* `https://messages.cloud.cegedim.com` for 3rd party applications reaching Vortext on the internet.

All methods are relative to this URL.

For example if you want to get status of vortext, you have to use:

```http
GET https://messages.cloud.cegedim.com/status
```

## Security <a href="#howtos-security" id="howtos-security"></a>

### HTTPS Protocol <a href="#howtos-httpsprotocol" id="howtos-httpsprotocol"></a>

All requests to Vortext API is made by HTTP protocol, using TLSv1 transport encryption.

### Authentication <a href="#howtos-authentication" id="howtos-authentication"></a>

As for now, basic authentication is used for **every** request made to Vortext service. Each request is completely stateless, so you can use Vortext service with a simple line of `curl`. If you don’t know about basic authentication, it only needs a http request header 'Authorization' :

```
Authorization Basic YWRtaW5pc3RyYXRvc5cnF2NjBTenh3djRuaU5meEV5VFgwaUN4VmNTaHF1djBYU0RIbjY2
```

The credential used if `username:password` encoded in base 64. Most of libraries will simply let you provide username and password.

## HTTP Request and Responses format : json <a href="#howtos-httprequestandresponsesformat-json" id="howtos-httprequestandresponsesformat-json"></a>

This API is aimed primarily to handle `json` messages in http request and response bodies.

### HTTP Request format <a href="#howtos-httprequestformat" id="howtos-httprequestformat"></a>

Use `Content-Type: application/json` header to let Vortext service know your request body format.

### HTTP Response format <a href="#howtos-httpresponseformat" id="howtos-httpresponseformat"></a>

Use `Accept: application/json` header to let Vortext service which format do you want for body response.

## Date/Time format <a href="#howtos-date-timeformat" id="howtos-date-timeformat"></a>

As json doesn’t support natively Date/Time, all parameters tagged as Date in this API are string with ISO8601 format :

```
`YYYY-MM-DDTHH:MM:SS.sssZ`
```

where Z is timezone (like `+0200`).

Examples : `2016-06-01T12:27:19.000+0200.`

For query parameters, don’t forget to url encode these parameters.

## Sender Name <a href="#howtos-sendername" id="howtos-sendername"></a>

You can customize sender name of SMS, instead of a classic number such as "30180".

To do so, please make a request in ITCare to our team by requesting this feature to be setup.

**Requirements:**

* Maximum length: 11 characters
* Allowed characters: alphanumeric (a-zA-Z, 0-9) and dashes (-)

Once your account configured, all SMS sent will be with this sender name. As per now, it is not possible to have multiple sender name per account.

## Custom data <a href="#howtos-metadata" id="howtos-metadata"></a>

Optionnaly, you can add a metadata object to sms send request, to tag custom data for this message. The added tag will be retrieved when getting the detail of the SMS.

Exemple of SMS sending with a metadata tag :

`{ "phoneNumber": "+3361127272727", "message": "Please call me", "metadata": { "myCustomerId": "123de32", "caller": "MyApp 2.2" } }`

## PUSH responses <a href="#howtos-pushresponses" id="howtos-pushresponses"></a>

It is possible to receive PUSH responses (https REST call) as soon as a customer makes a response to a previously sent SMS. To activate this features, please make a request in ITCare to our team .

Here is the specifications of outbound request you will receive once activated :

<table data-header-hidden><thead><tr><th width="233"></th><th></th></tr></thead><tbody><tr><td>Protocol</td><td>https</td></tr><tr><td>URL</td><td>&#x3C;yours></td></tr><tr><td>HTTP method</td><td>POST</td></tr><tr><td>Authentication</td><td>None</td></tr><tr><td>Content-Type</td><td>application/json</td></tr><tr><td>Message Body</td><td>{ "response": { "content": "Response of your customer", "answeredAt" : "2020-02-12T13:00:00.000+0000" }, "message": { }}</td></tr></tbody></table>

## Limits <a href="#howtos-limits" id="howtos-limits"></a>

You can set limits to avoid multiple calls / bad loops and prevent some flooding :

* total SMS sent by minute
* total SMS sent by hour

To activate this features, please make a request in ITCare to our team.