websms – Receive Message

Use websms to handle incoming SMS messages automatically by using SMTP or HTTP.

Receive SMS and DeliveryReports

You have two options to handle incoming messages at websms.

Request body

Element: notification

Property Type Description Example
messageType String "text", "binary", "deliveryReport" – defines the contenttype of your notification text
notificationId String 20 digit long identification of your notification. Eg: "050f9005180a2a212469"
messageTypes: text, binary, deliveryReport
transferId String Unique transfer-id to connect the deliveryReport to the initial message.
messageTypes: deliveryReport
messageFlashSms Boolean true|false – indicates whether you received message is a SMS or a flash-SMS
messageTypes: text, binary
senderAddress String Originator of the sender, eg:4366012345678
messageTypes: text, binary, deliveryReport
senderAddressType String international – defines the number format of the mobile originated senderAddress. International numbers always includes the country prefix.
messageTypes: text, binary
recipientAddress String Senders address, can either be
international (4366012345678),
national (066012345678)
or a shortcode (1234)
messageTypes: text, binary, deliveryReport
recipientAddressType String "international"|"national"|"shortcode" – defines the number format of the mobile originated message
messageTypes: text, binary
textMessageContent String Text body of the message encoded in UTF-8. In the case of concatenated SMS it will contain the complete content of all segments.
messageTypes: text
Hello World!
userDataHeaderPresent Boolean true|false – indicates whether a user-data-header is included within a Base64 encoded byte segment.
messageTypes: binary
binaryMessageContent Array of Strings Content of a binary SMS in an Array of Byte64 Strings (URL safe).
messageTypes: binary
deliveryReportMessageStatus String "delivered", "undelivered", "expired", "deleted", "accepted", "rejected"
messageTypes: deliveryReport
sentOn String ISO 8601 timestamp, eg: "2013-05-27T13:36:00.000+02:00". Point of time sending the message to recipients address.
messageTypes: deliveryReport
deliveredOn String ISO 8601 timestamp, eg: "2013-05-27T13:36:00.000+02:00". Point of time of submitting the message to the mobile operators network.
messageTypes: deliveryReport
deliveredAs String "sms", "push", "failover-sms", "voice"
messageTypes: deliveryReport
clientMessageId String In the case of a delivery report, the clientMessageId contains the optional submitted message id.
messageTypes: deliveryReport

Response body

You have to confirm the notification with statusCode 2000 within your response body. Otherwise, websms will retry the delivery of your notification for the duration of the lifetime of your message. Element

Attribute Description
statusCode status code after processed request
statusMessage Description of the response status


Receive SMS JSON


  "messageType": "text",
  "notificationId": "02c1d0051949fe70cbfa",
  "senderAddress": "4367612345678",
  "senderAddressType": "international",
  "recipientAddress": "08282709900001",
  "recipientAddressType": "national",
  "textMessageContent": "Das ist eine Antwort SMS mit Sonderzeichen, Umlauten \u003c\"Ümläuten\"\u003e und €urozeichen."

Response body JSON


	"statusCode" : "...",
	"statusMessage" : "...",

Receive SMS XML


    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
        <textMessageContent>Das ist eine Antwort SMS mit Sonderzeichen, Umlauten &lt;&quot;Ümläuten&quot;&gt; und €urozeichen</textMessageContent>

Response body XML



PHP implementation

< ?php

  # 1) get the sms from the received notification
  $sms = json_decode($HTTP_RAW_POST_DATA);

  # 2) do something with $sms
  # 3) respond to the notification
  header('Content-Type: application/json; charset=UTF-8');
  echo '{"statusCode" : 2000, "statusMessage" : "ok"}';