websms – Receive Message

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

Receive SMS, Whatsapp 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", "whatsapp" – defines the contenttype of your notification text
notificationId String 20 digit long identification of your notification. Eg: "050f9005180a2a212469"
messageTypes: text, binary, deliveryReport, whatsapp
050f9005180a2a212469
transferId String Unique transfer-id to connect the deliveryReport to the initial message.
messageTypes: deliveryReport
0051949fe700053c4615
messageFlashSms Boolean true|false – indicates whether you received message is a SMS or a flash-SMS
messageTypes: text, binary
true
senderAddress String Originator of the sender, eg:4366012345678
messageTypes: text, binary, deliveryReport, whatsapp
4366012345678
senderAddressType String international – defines the number format of the mobile originated senderAddress. International numbers always includes the country prefix.
messageTypes: text, binary, whatsapp
international
recipientAddress String Senders address, can either be
international (4366012345678),
national (066012345678)
or a shortcode (1234)
messageTypes: text, binary, deliveryReport, whatsapp
national
recipientAddressType String "international"|"national"|"shortcode" – defines the number format of the mobile originated message
messageTypes: text, binary, whatsapp
international
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, whatsapp
Hello World!
userDataHeaderPresent Boolean true|false – indicates whether a user-data-header is included within a Base64 encoded byte segment.
messageTypes: binary
true
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",
"read"(whatsapp only)
messageTypes: deliveryReport
delivered
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
2013-05-27T13:36:00.000+02:00
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
2013-05-27T13:36:00.000+02:00
deliveredAs String "sms", "push", "failover-sms", "voice","whatsapp"
messageTypes: deliveryReport
sms
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

Examples

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"?>
    <notification>
        <messageType>text</messageType>
        <notificationId>02c1d0051949fe70cbfa</notificationId>
        <senderAddress>4367612345678</senderAddress>
        <senderAddressType>international</senderAddressType>
        <recipientAddress>08282709900001</recipientAddress>
        <recipientAddressType>national</recipientAddressType>
        <textMessageContent>Das ist eine Antwort SMS mit Sonderzeichen, Umlauten &lt;&quot;Ümläuten&quot;&gt; und €urozeichen</textMessageContent>
    </notification>

Response body XML

 

<notificationResponse>
<statusMessage>...</statusMessage>
<statusCode>...</statusCode>
</notificationResponse>
	

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"}';
?>