Smart Messaging

Page last updated:

Overview

The Smart Messaging API provides different resources around the topic of mobile messaging like sending SMS or validating phone numbers via SMS:

SMS

Send SMS and check their status.

Token Validation

Validate a phone number via SMS token. To validate a number, a predefined SMS message with an included textual token will be sent to your customer’s mobile phone. The customer then enters this token somewhere in your application (e.g. HTML from, Mail, Callcenter) and you can validate it using this API.

Creation

To create a Smart Messaging service, simply click “Create Service” in the web console or run cf create-service smartmsg usage my-sms (replace “my-sms” with the actual name of your service instance).

Important: Note that you’ll have to activate the service after you have triggered its creation. To do so, click the “Manage” button on the service instance’s detail screen in the web console.

API Resources

Sending SMS

POST /messaging/sms
curl -X POST https://api.swisscom.com/messaging/sms -H 'SCS-Version: 2' -H 'client_id: {YourClientID}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'SCS-Request-ID: {YourRequestID}' -d '{"to": "{YourPhoneNumber}", "text": "YourMessageText."}'

Request

Headers
  • client_id required (See authentication)
  • SCS-Version required (Must be 2)
  • Content-Type required (E.g. application/json)
  • Accept required (Must be application/json)
  • SCS-Request-ID optional (Can be used to trace your request to our API. Only relevant if you need support from our team so they know which request to look into.)
Body Example (application/json)
{
  "from": "Swisscom",
  "to": "+41791234567",
  "text": "Greetings from Swisscom!",
  "callbackUrl": "https://notification.com/service"
}

By default, the mobile number you used to create your service instance is used as the sender’s number. To display a different sender, you can set the from parameter. Notice: you need special permissions to use this parameter. Please contact our support team at developer-support@swisscom.com to get access to this feature.

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

Body Schema (application/json)
{
  "$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. Defaults to the number used to create the service. Special permissions required to set this.",
      "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 sent (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

Get status information for an SMS

GET /messaging/sms/{messageId}
curl https://api.swisscom.com//messaging/sms/{messageId} -H 'SCS-Version: 2' -H 'client_id: {YourClientID}' -H 'Accept: application/json' -H 'SCS-Request-ID: {YourRequestID}'

Request

Headers
  • SCS-Version required (Must be 2)
  • client_id required (See authentication)
  • Accept required (Defaults to application/json)
  • SCS-Request-ID optional (Can be used to trace your request to our API. Only relevant if you need support from our team so they know which request to look into.)
URI Parameters
  • messageId (MessageId of the SMS. You will receive this on notification request.)

Success Responses

201 Response Example (application/json)
{
  "messageId": "0001",
  "status": "201",
  "description": "Delivered with delivery confirmation"
}
201 Response Schema (application/json)
{
  "$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

Initiate SMS Token Validation process

POST /messaging/tokenvalidation
curl -X POST https://api.swisscom.com/messaging/tokenvalidation -H 'SCS-Version: 2' -H 'client_id: MyClientID' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'SCS-Request-ID: {YourRequestID}' -d '{"to":"+41791234567", "text":"Take this token: %TOKEN%", "tokenType":"SHORT_NUMERIC", "expireTime":120,"tokenLength":6}'

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 that the user recieved the validation token by calling the Validate SMS Token endpoint.

Request

Headers
  • SCS-Version required (Must be 2)
  • client_id required (See authentication)
  • Content-Type required (E.g. application/json)
  • Accept optional (Defaults to application/json)
  • SCS-Request-ID optional (Can be used to trace your request to our API. Only relevant if you need support from our team so they know which request to look into.)
Body Example (application/json)
{
  "to": "+41791544781",
  "text": "Verification code: %TOKEN% \r\n Expires in 60 seconds.",
  "tokenType": "SHORT_ALPHANUMERIC",
  "expireTime": 60,
  "tokenLength": 6
}

Use %TOKEN% as a placeholder for where the actual token should go.

Body Schema (application/json)
{
  "$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": "Expiration time of the token in seconds.",
      "type": "integer",
      "minimum": 0,
      "maximum": 86400
    },
    "tokenLength": {
      "description": "The size of the token. 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

Validate SMS token

GET /messaging/tokenvalidation/{msisdn}/{token}
curl https://api.swisscom.com/messaging/tokenvalidation/{YourMsisdn}/{YourReceivedToken} -H 'SCS-Version: 2' -H 'client_id: {YourClientID}' -H 'Accept: application/json' -H 'SCS-Request-ID: {YourRequestID}'

Validate a token sent to the MSISDN number using the Send SMS Token endpoint. 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 required (See authentication)
  • SCS-Version required (Must be 2)
  • Accept required (Must be application/json)
  • SCS-Request-ID optional (Can be used to trace your request to our API. Only relevant if you need support from our team so they know which request to look into.)
URI Parameters
  • msisdn required (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 required (The token to verify.)

Success Responses

200 Response Example (application/json)
{
  "validation": "SUCCESS"
}
200 Response Schema (application/json)
{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object" ,
  "required": [
    "validation"
  ],
  "properties": {
    "validation": {
      "description": "More details on the error",
      "enum": [
        "SUCCESS",
        "FAILED"
      ]
    }
  }
}

Error Responses

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

Error Handling

Error Response Schema

{
  "$schema": "http://json-schema.org/draft-03/schema",
  "type": "object" ,
  "properties": {
    "uuid": {
      "description": "The UUID of the client software",
      "type": "string",
      "required": false
    },
    "status": {
      "description": "The http status code, e.g. 400",
      "type": "string",
      "required": true
    },
    "code": {
      "description": "The error code, e.g. INVALID_PARAMETER",
      "type": "string",
      "required": true
    },
    "message": {
      "description": "The error message",
      "type": "string",
      "required": true
    },
    "detail": {
      "description": "A detailed error description",
      "type": "string",
      "required": false
    }
  }
}

Error Response Examples

400 (Bad Request. Invalid request.)

{
  "status": "400",
  "code": "INVALID_REQUEST",
  "message": "The request could not be understood due to malformed syntax. Correct the request syntax and try again.",
  "detail": ""
}

401 (Unauthorized. No permission to access resource or invalid API key.)

{
  "status": "401",
  "code": "INVALID_AUTHENTICATION_CREDENTIALS",
  "message": "Authentication credentials missing or incorrect. Check that you are using the correct authentication method and that you have permission to the given resource and your app key is approved.",
  "detail": ""
}

403 (Forbidden. No permission to access requested resource.)

{
  "status": "403",
  "code": "FORBIDDEN_RESOURCE",
  "message": "The server understood the request, but is refusing to fulfill it. Check that you have permission to the given resource.",
  "detail": ""
}

404 (Not Found. The server has not found a resource matching the Request-URI.)

{
  "status": "404",
  "code": "INVALID_REQUEST_RESOURCE",
  "message": "The requested resource does not exist. Verify that the resource URI is correctly spelled.",
  "detail": ""
}

405 (Method Not Allowed. The resource is not accessible via the given HTTP method. For example, the client sent a POST request to a resource that only supports GET.)

{
  "status": "405",
  "code": "INVALID_REQUEST_METHOD",
  "message": "The resource is not accessible via the given method. Check the documentation or the Allow header for allowed methods.",
  "detail": ""
}

406 (Invalid Header Accept. The provided Accept-type is not supported by the resource.)

{
  "status": "406",
  "code": "INVALID_HEADER_ACCEPT",
  "message": "The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request. Make sure the request has an Accept header with a media type supported by the API. Check the developer portal for supported media types.",
  "detail": ""
}

429 (Too Many Requests. Quota for this service has been exhausted. Message must contain further details.)

{
  "status": "429",
  "code": "EXPIRED_QUOTA",
  "message": "Your quota for this service has been exhausted. Try again later or contact support at developer-support@swisscom.com.",
  "detail": ""
}

500 (Internal Server Error. The server has run into an unexpected condition.)

{
  "status": "500",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "The server encountered an unexpected condition which prevented it from fulfilling the request. Try again later or contact support at developer-support@swisscom.com.",
  "detail": ""
}

503 (Service Unavailable. The server is currently unable to handle the request due to temporary overloading or maintenance. Typically, back end is unavailable.)

{
  "status": "503",
  "code": "UNAVAILABLE_SERVICE",
  "message": "The server is currently unable to handle the request due to temporary overloading or maintenance. Try again later or contact support at developer-support@swisscom.com.",
  "detail": ""
}

ClientId Authentication

The SMS API requires ClientId authentication. The ClientId is part of the credentials, which are available in the VCAP_SERVICES environment variable after you bind the SMS API service to your app or through service keys. For a valid authentication of your requests, you must set the ClientId as HTTP header client_id in your requests. See also examples for details.

SmartSmsServiceKey

View the source for this page in GitHub