Skip to content

smart messaging.html

Jump to bottom
hwaarl edited this page Apr 15, 2016 · 6 revisions

title: SmartMessaging API owner: API

<%= modified_date %>

Overview

The SmartMessaging API provides different resources around the topic of mobile messaging.

SMS

Resource to send an SMS. It is also possible to receive a status notification.

Token Validation

Simple resource to validate a phone number by token. To validate a number, a well specified SMS message with an included textual token will be sent to your customer's mobile. Now the customer is able to forward this token to your service (HTML from, Mail, Callcenter). After a quick validation by this resource, you can be sure that phone number belongs to your customer.

API Resources

/messaging/v1/sms

POST

Send an SMS

Request
Headers
  • client_id (Id to authenticate client)
  • Content-Type (application/json)
  • Accept (application/json)
Body (application/json)
{
  "from": "Swisscom",
  "to": "+4171234567",
  "text": "Greetings from Swisscom!"
  "callbackUrl": "http://notification.com/service"
}
{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "required": [
    "to", "text"
  ],
  "properties": {
    "from": {
      "description": "Sender name or number. Valid MSISDN number or alpha numeric text with max. 11 Characters",
      "type": "string"
    },
    "to": {
      "description": "Recipient number. A valid number starts with 0, 00 or + and must contain 7 to 15 digits. Local numbers (prefix 0) are handled with international code +41 by default.",
      "type": "string"
    },
    "text": {
      "description": "Appears as text in SMS.",
      "type": "string"
    },
    "callbackUrl": {
      "description": "A valid callback URL (HTTP) for delivery notification. The notification call will be send (PUT method with the header.location which contains messageID) for each SMS status change",
      "type": "string"
    }
  }
}
Success Responses
201 Response
no content
Error Responses

400, 401, 403, 404, 405, 406, 429, 500, 503

/messaging/v1/sms/{messageId}

GET

Get Status information for an SMS

Request
Headers
  • client_id (Id to authenticate client)
  • Accept (application/json)
URI Parameters
  • messageId (MessageId of the SMS. You will receive this on notification request.)
Success Responses
200 Response (application/json)
{
  "messageId": "0001",
  "status": "201",
  "description": "Delivered with delivery confirmation"
}
{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "required": [
    "messageId",
    "status"
  ],
  "properties": {
    "messageId": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "description": {
      "type": "string"
    }
  }
}
Error Responses

401, 403, 404, 405, 500, 503

/messaging/v1/tokenvalidation

POST

This call will start the SMS Token validation process by sending a validation token to an MSISDN. The validation token is a random string of characters that is sent to the user's mobile phone. After making this call, your application can then verify the user recieved the validation token by calling Validate SMS Token.

Request
Headers
  • client_id (Id to authenticate client)
  • Content-Type (application/json)
  • Accept (application/json)
Body (application/json)
{
  "to": "+41791544781",
  "text": "Verification code: %TOKEN% \r\n Expires in 60 seconds.",
  "tokenType": "SHORT_ALPHANUMERIC",
  "expireTime": 60,
  "tokenLength": 6
}
{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object" ,
  "required": [
    "to"
  ],
  "properties": {
    "to": {
      "description": "Mobile number which should be verified. A valid number starts with 0, 00 or + and must contain 7 to 15 digits. Local numbers (prefix 0) are handled with international code +41 by default. ",
      "type": "string"
    },
    "text": {
      "description": "Appears as text in SMS. %TOKEN% is the placeholder for the generated token.",
      "type": "string"
    },
    "tokenType": {
      "description": "Describes what kind of token should be generated.",
      "enum": [
        "SHORT_NUMERIC",
        "SHORT_ALPHANUMERIC",
        "SHORT_SMALL_AND_CAPITAL",
        "LONG_CRYPTIC"
      ]
    },
    "expireTime": {
      "description": "Expire time of the token in seconds.",
      "type": "integer",
      "minimum": 0,
      "maximum": 86400
    },
    "tokenLength": {
      "description": "The size of the token. It is mandatory for all SHORT_* tokenTypes.",
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    }
  }
}
Success Responses
201 Response
no content
Error Responses

400, 401, 403, 404, 405, 406, 429, 500, 503

/messaging/v1/tokenvalidation/{msisdn}/{token}

GET

Validate the token sent to the MSISDN number by the Send SMS Token call. This call is made after the Send SMS Token call to validate the token sent to the end user via SMS.

Request
Headers
  • client_id (Id to authenticate client)
  • Accept (application/json)
URI Parameters
  • msisdn (The token depending phone number. A valid number starts with 0, 00 or + and must contain 7 to 15 digits. Local numbers (prefix 0) are handled with international code +41 by default.)
  • token (Token to verify.)
Success Responses
200 Response
{
  "validation": "SUCCESS"
}
{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object" ,
  "required": [
    "validation"
  ],
  "properties": {
    "validation": {
      "description": "Whether token validation was successful",
      "enum": [
        "SUCCESS",
        "FAILED"
      ]
    }
  }
}
Error Responses

400, 401, 403, 404, 405, 406, 500, 503

Examples

About cUrl

You can quickly make calls to the Swisscom APIs using cURL in the command line. If you have not already installed cURL, use the cURL Download Wizard to get the correct binary.

About client id

The SmartSms API requires client Id authentication only. See our tutorial for details and in particular the description of where to find the client id in Swisscom application cloud's developer console

Sending SMS

This first call shows how to send a SMS without optional parameter:

curl -ik -H "Content-Type: application/json" -H "client_id:%YOUR_CLIENT_ID%" -X POST "https://api.swisscom.com/messaging/v1/sms" -d "{\"to\": \"+417xxxxxxxx\", \"text\": \"hello world\"}"

By default your registered mobile number is used as sender number. To display a different sender number you can set the "from" parameter. Notice: you need special permissions to use this parameter. Please contact our support team, to book this feature.

If you need updates about the SMS state (e.g. SMS was received). You can set the callBackUrl parameter. You will receive a HTTP PUT request on this URL, on any SMS state change.

curl -ik -H "Content-Type: application/json" -H "client_id:%YOUR_CLIENT_ID%" -X POST "https://api.swisscom.com/messaging/v1/sms" -d "{\"to\": \"+417xxxxxxxx\", \"from\": \"Swisscom\", \"text\": \"hello world\", \"callbackUrl\": \"http://mydomain.net/notification\"}"

Token Validation

If you want to verify the mobile number of a customer, you can simple send a SMS token with this request:

curl -ik -H "Content-Type: application/json" -H "client_id:%YOUR_CLIENT_ID%" -X POST " https://api.swisscom.com/messaging/v1/sms/tokenvalidation" -d "{\"to\":\"+417xxxxxxxx\",\"text\":\"Take this token: %TOKEN%\", \"tokenType\":\"SHORT_NUMERIC\",\"expireTime\":120,\"tokenLength\":6}"

The customer receives the token on his mobile. After he types the token into your web form, you can do a verification with the following request:

curl -ik -H "Accept: application/json" -H "client_id:%YOUR_CLIENT_ID%" -X GET " https://api.swisscom.com/messaging/v1/sms/tokenvalidation/00417xxxxxxxx/%RECEIVED_TOKEN_GOES_HERE%"

RESTful API Services

Clone this wiki locally