arvato SMS Service

The arvato SMS service allows to programmatically send and receive short text messages (SMS). Messages can be sent to mobile phones and you can receive notifications about incoming messages.

Please also see our Use Cases and FAQ pages.

This page introduces the API based on examples. If you're looking for a complete reference documentation, take a look at our interactive API console.

Overview

The following web service functionality is provided:

  • SMS enabled Phones numbers
    • View a list of phone numbers available for purchase
    • Purchase a phone number to send/receive text messages
    • View a list of phone numbers that you own
    • Release a previously purchased phone number
    • Add your own URL to retrieve incoming messages.
  • SMS
    • Send a short text message to a phone number
    • Retrieve notifications about incoming messages.
    • View a list of outgoing and incoming messages

Concepts

Phone numbers: In order to send and/or receive text messages, you must purchase a phone number first (see API examples below). There is a default limit of 1 phone number per tenant. This can be increased. Please contact our customer support to request an increase.

Short Message Service (SMS): SMS is a text messaging service component of phone, Web, or mobile communication systems. It uses standardized communications protocols to allow fixed line or mobile phone devices to exchange short text messages.

Carrier: Company that provides voice or data services. Carriers can be companies that operate wirelessly or over traditional wired land lines.

Accessing the API

All API calls are secured by access tokens. Please refer to the Getting Started guide about how to retrieve access tokens.

Required subscriptions

A subscription to the arvato SMS package is required. The package does not depend on other services.

Scopes

In most cases no specific scope is required when requesting access tokens; a subscription to the service is enough. However, if you intend to use the PubSub integration, then you need to request additional scopes. (Please see the PubSub section below for more details).

Endpoints

Production

The following endpoint is the base for all live transactions:

Base URL for this endpoint is: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}

RAML specification: https://api.yaas.io/arvato/sms/v1/public/api/api.raml

Test

The TEST endpoint can be used to try out and verify your integration with our API. When using this endpoint no phone numbers will be actually purchased and no SMS will be sent out. However, this can be useful for example during development when you would like to exercise parts of our API without having to actually purchase a phone number.

Base URL for this endpoint is: https://api.yaas.io/arvato/sms/test/tenants/{tenant}

RAML specification: https://api.yaas.io/arvato/sms/test/public/api/api.raml

Please note: The TEST environment is also where we beta test new features. It has limited availability and is less stable than the production environment. Persistent data may be removed at any time. There is no uptime guarantee or any other SLA.

Content Type

Unless otherwise specified, all the content type of all request and responses will be application/json.

API Examples

Managing phone numbers (/phones)

In order to send and/or receive text messages, you must purchase a phone number first. The /phones sub-resource lets you manage phone numbers.

Listing phone numbers available for purchase

The following example shows how to retrieve a list of phone numbers for the United States.

Request
  • Method: GET
  • URL: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/available/
  • Query Parameters:
    • isoCountryCode: US
Example
curl -X GET -H "Authorization: Bearer {token}" -H "Accept: application/json" -H "Cache-Control: no-cache" https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/available?isoCountryCode=US
Response
  • Status Code: 200
Example
[
  {
    "phoneNumber": "+13109821234",
    "region": "CA"
  },
  {
    "phoneNumber": "+13189953568",
    "region": "LA",
    "postalCode": "71082",
  },
  {
    "phoneNumber": "+1806221234",
    "region": "TX"
  },
  {
    "phoneNumber": "+16018690234",
    "region": "MS",
    "postalCode": "39652"
  }
]

Purchasing a phone number

Now we're going to purchase a phone number by sending a POST request to the /phones sub-resource.

Optionally, we can specify a callback URL, which will be invoked each time a new message is received. (Please see the section about callbacks further below.) Another alternative to retrieve only new messages is to use the Hybris PubSub service. (Please see the PubSub section below). Both integration methods are optional. It's also possible to directly receive the text message history (also explained further below).

Note that there is a default limit of 1 for the number of owned phones per tenant per month. If you need more, please contact us.

Request
  • Method: POST
  • URL: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/
  • Body:
{
  "phoneNumber": "+15005550006"
}
Simple Example without integrations
curl -X POST -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
  "phoneNumber": "+15005550006"
}
' https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/
Extended example with callback and PubSub integration
curl -X POST -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
  "phoneNumber": "+15005550006",
  "smsCallbackUrl": "http://your.callback.url.com/",
  "publishToQueue": true
}
' https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/
Response
  • Status Code: 201
  • Headers:
    • Location: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/?phoneNumber=%2B15005550006

Listing your owned phone numbers

The following example shows how to retrieve a list of phone numbers that you've previously purchased. Optionally you can specify a phone number to filter the results.

Request
  • Method: GET
  • URL: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/
  • Query Parameters:
    • phoneNumber: +15005550006
Example
curl -X GET -H "Authorization: Bearer {token}" -H "Accept: application/json" -H "Cache-Control: no-cache" https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones?phoneNumber=+15005550006
Response
  • Status Code: 200
Example
[
  {
    "id": "75ee95e254a9495a8019dd6306",
    "phoneNumber": "+13109821234",
    "publishToQueue": false
  },
  {
    "id": "5ee938hdf83j3s34438019873",
    "phoneNumber": "+1806221234",
    "smsCallbackUrl" : "http://some.callback.url.com/callback",
    "publishToQueue": false
  },
  {
    "id": "ffAA938hdf83j3s3443801123",
    "phoneNumber": "+1806229876",
    "publishToQueue": true
  }
]

Updating a phone number

We can update the SMS callback URL or enable/disable PubSub integration on any owned phone by sending a PUT request to /phones/{phoneId} resource. The {phoneId} parameter can be obtained by listing your owned phones.

Request
  • Method: PUT
  • URL: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/{phoneId}
  • Body:
{
  "smsCallbackUrl": "http://some.callback.url.com/"
}
Example
curl -X PUT -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
  "smsCallbackUrl": "http://your.callback.url.com/",
  "publishToQueue": false
}' https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/{phoneId}
Response
  • Status Code: 200

Releasing a phone number

If you no longer use a previously purchased phone number, it can be released by sending a DELETE request. The {phoneId} parameter can be obtained by listing your owned phones.

Note that there is a default limit of 1 for the number of owned phones per tenant per month. Even if you release a phone, you won't be able to buy a new one within the same month when the phone was purchased. If you would like to request an increase of this limit, please contact us.

Request
  • Method: DELETE
  • URL: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/{phoneId}
Example
curl -X DELETE -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '' https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/phones/{phoneId}
Response
  • Status Code: 204

Sending and Receiving SMS

Sending a text message to a phone number

The following example adds a new text message to the outgoing queue. The URI of the message is returned in the location header.

Note: To send a text message, you need to purchase a phone number first. Please see the previous section about how to manage phone numbers.

Request
  • Method: POST
  • URL: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/sms/
  • Body:
{
  "fromNumber": "+15005550006",
  "toNumber": "+15005550007",
  "messageText":"Hello there!"
}
Example
curl -X POST -H "Authorization: Bearer {token}" -H "Content-Type: application/json"  -H "Cache-Control: no-cache" -d '{
  "fromNumber": "+15005550006",
  "toNumber": "+15005550007",
  "messageText":"Hello there!"
}' https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/sms/
Response
  • Status Code: 201
  • Headers:
    • location: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/sms/fceda80ef6c49f1237e8541463c672d

Retrieving the status of a message

When a new message is posted, it gets added to a queue and is sent out as soon as possible. To retrieve a status of when a message was sent, you can use the following web service.

Request
  • Method: GET
  • Query Parameters:
    • messageId: fe07c4db04da8dad4905884cd75c5831
  • URL: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/sms/{messageId}
Example
curl -X GET -H "Authorization: Bearer {token}" -H "Accept: application/json" -H "Cache-Control: no-cache" https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/sms/fe07c4db04da8dad4905884cd75c5831
Response
  • Status Code: 200
Example
{
    "id": "SMfe07c4db04da8dad4905884cd75c5831",
    "fromNumber": "+123456789",
    "toNumber": "+987654321",
    "messageText": "Some message",
    "sentDate": "2015-07-01T14:22:56.000Z",
    "status": "received"
}

Retrieving the text messages history

The following example lists all outgoing and incoming messages. This list is paginated and can be navigating by the nextPage and previousPage urls included in the response. Optionally you can specify filters like phone number, date or pageSize.

Request
  • Method: GET
  • URL: https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/sms/
  • Query Parameters:
    • fromNumber: +15005550005
    • toNumber: +15005550006
    • fromDate: YYYY-MM-DD
    • pageSize: 50
Example
curl -X GET -H "Authorization: Bearer {token}" -H "Accept: application/json" -H "Cache-Control: no-cache" https://api.yaas.io/arvato/sms/v1/tenants/{tenant}/sms
Response
  • Status Code: 200
Example
[
    {
      "id": "7654328912",
      "fromNumber": "+123456789",
      "toNumber": "+987654321",
      "messageText": "Some message",
      "status": "received",
      "sentDate": "2015-06-26T13:44:17.000Z"
    },
    {
      "id": "555434563",
      "fromNumber": "+123456789",
      "toNumber": "+987654321",
      "messageText": "Another message",
      "status": "received",
      "sentDate": "2015-06-25T15:32:21.000Z"
    }
]

Callbacks

When you buy or update a phone number, you can specify a callback URL. This URL will receive a POST request each time a SMS is received by the number. This is useful to trigger your own business logic, for example when a customer replies to an SMS you sent.

This application/json request will include the following information:

  • Body:
{
  "fromNumber": "+15005550006",
  "toNumber": "+15005550007",
  "messageText":"Hello there!"
}

Additionally the request will contain the following Header:

  • Headers:
    • x-signature: Signature used to verify authenticity

How to retrieve your account token

The callback request from the arvato SMS service to your endpoint is signed with a key that is specific to your account. The following web service call can be used to retrieve your account token. If you would like to cache this key, make sure to keep it in a secure place.

Request

  • Method: GET
  • URL: https://api.yaas.io/arvato/sms/test/tenants/{tenant}/account/token
Example
curl -X GET -H "Authorization: Bearer {token}" -H "Accept: application/json" -H "Cache-Control: no-cache" https://api.yaas.io/arvato/sms/test/tenants/{tenant}/account/token

Response

  • Status Code: 200
Example
{
  "token": "some-token"
}

How to verify the signature

The x-signature header value can be used to verify that the callback originated from the arvato SMS service and not from a malicious third party. Follow these steps to verify the signature:

  1. Take the full URL of the callback URL that you specified for your phone number, from the protocol (https...) through the end of the query string (everything after the ?).
  2. Sort all of the JSON attributes alphabetically (using Unix-style case-sensitive sorting order).
  3. Iterate through the sorted list of JSON attributes, and append the variable name and value (with no delimiters) to the end of the URL string.
  4. Sign the resulting string from step 3) using HMAC-SHA1 and specifying your account's token as the key.
  5. Apply Base64 encoding to the resulting hash value.
  6. Compare the hash you calculated to the value of the x-signature header. If they match, then you can be sure the request came from the arvato SMS Service.

Example

The following example implemented in Java shows how to calculate the signature value.

public String calculateSignature(final URI yourCallbackURI, final String yourAccountToken, final Map<String, String> postParameters)
{
    // build URL to sign by appending every POST key-value-pair in alphabetical order
    final StringBuilder url = new StringBuilder(yourCallbackURI.toString());
    final List<String> keys = new LinkedList<>(postParameters.keySet());
    Collections.sort(keys);
    for (final String sortedKey : keys)
    {
        url.append(sortedKey).append(postParameters.get(sortedKey));
    }

    try
    {
        // Hash using SHA1 + AuthToken as key and finally encode in Base64
        final SecretKeySpec signingKey = new SecretKeySpec(yourAccountToken.getBytes(), HMAC_SHA1_ALGORITHM);
        final Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);
        mac.init(signingKey);
        return Base64.encodeBase64String(mac.doFinal(url.toString().getBytes("UTF-8")));
    }
    catch (IllegalStateException | UnsupportedEncodingException | InvalidKeyException | NoSuchAlgorithmException e)
    {
        throw Throwables.propagate(e);
    }
}

The following is a simple REST endpoint that is able to process and verify call-backs. It's implemented using Jersey and Java:

@Named
@Consumes({ MediaType.APPLICATION_JSON })
@Produces({ MediaType.APPLICATION_JSON })
@Path("/callback")
public class TestCallbackEndpoint
{
    @Context
    private UriInfo uriInfo;

    @POST
    public Response handleCallback(final Map<String, String> payload, @HeaderParam("x-signature") final String signature)
    {
        // calculate signature of this request (see example above)
        String calculatedSignature = calculateSignature(uriInfo.getRequestUri(), getYourAccountToken(), payload);

        // verify signature
        if (signature == null || !signature.equals(calculatedSignature))
        {
            return Response.status(Status.FORBIDDEN).build();
        }

        // perform your business logic here

        return Response.ok().build();
    }
}

PubSub integration

When you buy or update a phone number, you can enable PubSub integration by setting the publishToQueue flag to true. When enabled, the SMS service will automatically push new incoming messages to the Hybris PubSub service. You can then retrieve them by periodically polling the service. This is a convenient way to get notified about new messages in situations where a direct callback to your service is not possible. (For example if your service is behind a firewall or if you want to retrieve SMS from within a client side app such as mobile.)

Prerequisites

In order to use this feature, you need to make sure your application or service in YaaS Builder is allowed to use the following scope: hybris.pubsub.topic=arvato.sms.sms_incoming. You must add this scope under "Required Scopes".

You then enable this feature by setting the publishToQueue flag to true when buying a new phone number or updating a number you own (see API examples above).

How to retrieve new messages from PubSub

After you have followed the instructions under "Prerequisites", you can use the standard PubSub API to retrieve new messages.

When generating an access token to access the PubSub service, you must request the hybris.pubsub.topic=arvato.sms.sms_incoming scope. Otherwise you will not be allowed to read events from this topic.

Messages will be published under the topic owner arvato.sms under the event type sms_incoming. The complete path therefore is: /topics/arvato.sms/sms_incoming/read

(If you are using the TEST version of the sms service, then messages will be published under the event type sms_incoming-test and you need to request the hybris.pubsub.topic=arvato.sms.sms_incoming-test scope instead.)

Example read request with autocommit
curl -X POST -H "Content-Type: application/json; charset=utf-8" -H "Accept: application/json" -H "Authorization: Bearer {token}" -H "Cache-Control: no-cache" -d '{ 
    "numEvents": 10, 
    "ttlMs": 10000, 
    "autoCommit":true 
}' "https://api.yaas.io/hybris/pubsub/v1/topics/arvato.sms/sms_incoming/read"
Response
  • Status Code: 200
Example
{
  "events": [
    {
      "eventType": "sms_incoming",
      "payload": "{\"fromNumber\":\"+15005550006\",\"messageText\":\"Hello World\",\"toNumber\":\"+15005550007\"}",
      "tenant": "{tenant}",
      "id": "a26be1c2-e897-4a80-997e-be7ea3fa017f",
      "sourceClient": "arvato.sms",
      "createdAt": 1454528210582
    }
  ]
}