SMS Pack

SMS Pack

Bundle of pre-paid SMS

Buy product

Technical Overview

SendSMS Service

The service provides operations for sending an SMS to a terminal, for example from a Web page or desktop application and a polling mechanism for monitoring the delivery status of a sent SMS.

Notification Service

The service provides operations to notified of delivery status of a SMS.

API Reference

Service Operation Description
Notification notifySmsDeliveryReceipt

Called to inform the delivery status of previously sent SMS message (using the sendSms operation of the OneAPI/SMS/SendSMS service).

SendSMS getSmsDeliveryStatus

Obtains the delivery state of a SMS message sent using operation sendSms.

This is an alternative to the notification interface.

sendSms

Sends a SMS message to one or more recipients. Optionally, it can notify an endpoint when there is a delivery state change.

Notification Service

Operations

notifySmsDeliveryReceipt

Called to inform the delivery status of previously sent SMS message (using the sendSms operation of the OneAPI/SMS/SendSMS service).

Request Parameters
correlator : string (required)

The opaque value sent by the client application (e.g. on the sendSms operation) is sent here as a callback context.

deliveryStatus : DeliveryInformation (required)

The delivery status for a destination address.

Go to top

SendSMS Service

Operations

getSmsDeliveryStatus

Obtains the delivery state of a SMS message sent using operation sendSms.

This is an alternative to the notification interface.

Request Parameters
requestIdentifier : string (required)

The request identifier of a sent SMS message.

This is the result value returned by the sendSms operation.

Response Parameters
result : DeliveryInformation (optional)
Examples

Get the delivery state of a message

The following example shows how to get the delivery state of a sent SMS message.

And the corresponding, successful, response:

Go to top

sendSms

Sends a SMS message to one or more recipients. Optionally, it can notify an endpoint when there is a delivery state change.

Request Parameters
addresses : anyURI (required)

A list of one or more destination telephone addresses

This must have the format tel:+[COUNTRY_CODE][NUMBER], e.g. tel:+351960000001

senderName : string (optional)

The sender name that will appear on the telephone.

This must have the format: [ONE LETTER][ONE OR MORE: LETTER or DIGIT], eg. Neo.

OneAPI defines this parameter as optional, but on our implementation this is really required.

charging : ChargingInformation (optional)

Do not pass this parameter, or set it to null. Its not used by our implementation.

message : string (required)

The SMS content.

If this message is comprised entirely by ASCII characters, you can use a maximum of 140 characters. Otherwise, you can use a maximum of 70 characters

receiptRequest : SimpleReference (optional)

Defines the endpoint that should be notified when the delivery state changes; e.g. when the message has been delivered to the terminal.

Response Parameters
result : string (required)

The request identifier of the sent SMS message.

You can use this identifier to retrieve the delivery state (by calling the getSmsDeliveryStatus operation).

Examples

Send SMS with receipt notification

The following example shows how to send a SMS and receive a notification when its delivery status changes (eg. when its delivered to the user terminal).

And the corresponding, successful, response:

When the SMS is delivered to the terminal, the application (i.e. the indicated endpoint in sendSMS request) will receive the following notification message:

Go to top

Notification Entities

DeliveryInformation

The delivery status of a SMS message sent to a specific destination address.

Attribute Name Description
address : anyURI The destination address. e.g. tel:+351213456789.
deliveryStatus : DeliveryStatus The delivery status.
description : string (optional) The delivery status description.
Go to top

DeliveryStatus

Message's delivery status.

Value Name Description
DeliveredToNetwork Successful delivery to the network enabler responsible for routing the SMS.
DeliveryUncertain Delivery status unknown. e.g. because it was handed off to another network.
DeliveryImpossible Unsuccessful delivery. The message could not be delivered before expired.
MessageWaiting The message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states.
DeliveredToTerminal Successful delivery to Terminal.
DeliveryNotificationNotSupported Unable to provide delivery receipt notification.
Go to top

SendSMS Entities

ChargingInformation

This entity is not supported by our implementation. Do not use.

Attribute Name Description
List of description : string
currency : string (optional)
amount : decimal (optional)
code : string (optional)
Go to top

DeliveryInformation

The delivery status of a SMS message sent to a specific destination address.

Attribute Name Description
address : anyURI The destination address. e.g. tel:+351213456789.
deliveryStatus : DeliveryStatus The delivery status.
description : string (optional) The delivery status description.
Go to top

DeliveryStatus

Message's delivery status.

Value Name Description
DeliveredToNetwork Successful delivery to the network enabler responsible for routing the SMS.
DeliveryUncertain Delivery status unknown. e.g. because it was handed off to another network.
DeliveryImpossible Unsuccessful delivery. The message could not be delivered before expired.
MessageWaiting The message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states.
DeliveredToTerminal Successful delivery to Terminal.
DeliveryNotificationNotSupported Unable to provide delivery receipt notification.
Go to top

SimpleReference

Attribute Name Description
endpoint : anyURI

The URI for the application HTTP endpoint that will receive the delivery notifications.

The exact type of the endpoint interface is choosen with the interfaceName member.

interfaceName : string

The endpoint interface name. Currently set this to soap (your application must implement the Notification interface).

correlator : string

An opaque value defined by your application. It was defined when you called the sendSms operation. It will be sent for the application notification endpoint as a callback context.

Go to top

SOAP API Authentication

Authenticating SOAP Request

Every request must contain authentication information to establish the identity of whom making the request and a autorization token called ESB Access Key.

ESB Access Key

Correct with the path to the access key

The ESB Access Key is what will authorize the usage of the API and is available when the buying process ends. In the costumer area you can find the product details where you can generate an ESB Access Key for you usage, another user registered on SAPO Services or even for everyone.

The element ESBAccessKey must appear on the message SOAP Header after the complex type ESBCredentials

Example:

ESBCredentials

ESBCredentials is a complex type that is used to pass the credentials in order to authenticate a SOAP request.

Request with username and password
Elements Description
ESBUsername The e-mail of the account that is used to access the API
ESBPassword The password that in combination with the ESBUsername is used to access the corresponding account

Example:

Request with ESBToken

Using a token instead of your username and password can be useful if you don't want to give your credentials to whom is using the API.

In order to generate a ESB Token you must use SAPO Security Token Service (STS). The ESBtoken is valid for 12 hours.

Requesting with an ESBtoken
Go to top