Receive incoming SMS

Prerequisites

In order to receive incoming calls to our system and then forward them to your callback URL, you need a virtual number. You can easily get a virtual number by ordering one of our subscription, or order the additional service 11-digit virtual number in our webshop.

Description

If an incoming SMS callback URL is specified in the account settings, incoming SMS messages will be sent to that URL when available. The content of these SMS messages is described below.

Our system sends incoming SMS with POST and expects a 200 OK if the SMS is delivered correctly. If any other status (ie an error status) is received, the incoming SMS will be re-sent at a later time.

You manage your callback url in the user portal https://portal.ip1.net/ → SMS → Settings for incoming SMS

Callback Payload

{ "id": "5c613848879973045cf39ac4", "batchId": "5c613848879973045cf39ac3", "owner": "ip1-XXXXX", "sender": "46712345678", "recipient": "456189040623", "body": "Hi my name is earl", "direction": "mo", "segments": 1, "type":"SMS", "datacoding": "GSM", "priority": 1, "statuses": [ { "created" : "2018-10-23T17:43:21Z", "code": 201, "duration": 1 } ], "modified": "2018-10-23T17:43:19Z", "mcc": "431" , "mnc": "20" }

Fields for payload

Field name Type Description and Conditions Example
id String The ID of the incoming message. 

"id": "5bcf4324ee47dee41a9dbb13"
batchId String ID of the parent batch of the incoming message (Messages cannot exist without a parent batch). 

"batchId": "5c613848879973045cf39ac3"
batchId String The account ID of the SMS account that owns the message (e.g. you). 

"owner": "ip1-XXXXX"
sender String The sender ID of the message's originator. 

"sender": "46712345678"
sender String The recipient of the message (your virtual number). 

"recipient": "467612345678"
body String The message contents. 

"body": "Hi my name is earl"
direction String Indicates whether the message was sent or received by our system.
  • MT An acronym for Mobile Terminated, a message that was sent to a mobile device.
  • MO An acronym for Mobile Originated, a message that was sent from a mobile device.
 

"direction": "mt"
segments Integer In cases where the message consists of more characters than the character limit for one SMS, the message will be split into several SMS, also called concatenated SMS. This property indicates how many SMS are needed to send the message 

    "segments": 1,
type String There are two types: sms and flash.
  • sms is a standard SMS.
  • flash is a message that is displayed once on the device and then deleted.
The standard type is sms. 

  "type":"SMS"
datacoding String There are two types available:.
  • gsm: 7-bit character set (160 characters/SMS), limited number of characters.
  • flash: 2-byte character set (70 characters/SMS), allows all characters (e.g. emoji).
If gsm is set, messages that require ucs (extended characters) to be denied. The default is ucs. 

"datacoding": "GSM",
priority Integer

Used for messages that need to be delivered quickly. Allowed values are 1 (standard, minimum) and 2 (highest).

Setting priorities 2 increases the price per SMS (10 öre for Swedish account, €0.01 for international account).

 

"priority": 1
statuses Array

An array of status updates.

  • statuses[].created
    • when the status was added
  • statuses[].code
    • The specific status code. More may be added in the future
  • statuses[].duration
    • Tells whether this is the last status update or if there may be more status updates to come 

  "statuses": [
      {
          "created": "2018-10-23T17:43:21Z",
          "code": 201,
          "duration": 1
      }
  ],
modified String When the SMS was last updated. 

"modified": "2018-10-23T17:43:19Z",
mcc String The country part of the leaf operator may be specified here if it's provided by the upstream carrier. MCC is an acronym for Mobile Country Code 

    "mcc": "431",
mnc String The network part of the leaf operator may be specified here if it's provided by the upstream carrier. MNC is an acronym for Mobile Network Code 

    "mcc": "431",

Code example

Below you will find a code example for a callback for incoming SMS traffic.

Callback for incoming SMS C#

[Route("callback")] [ApiController] public class CallbackController : ControllerBase { private readonly SqlConnection Connection; public CallbackController() { Connection = new SqlConnection("Connection String"); Connection.Open(); } [HttpPost("")] public ActionResult HandleCallback(IncomingSms request) { using (SqlCommand cmd = new SqlCommand("INSERT INTO [Messaging].[SmsMessage] ([Sender],[Body]) VALUES (@sender, @body )", Connection)) { cmd.Parameters.AddWithValue("@sender", request.Sender); cmd.Parameters.AddWithValue("@body", request.Body); int result = cmd.ExecuteNonQuery(); } return Ok(); } } public class IncomingSms { public string Id { get; set; } public string BatchId { get; set; } public string Owner { get; set; } public string Sender { get; set; } public string Recipient { get; set; } public string Body { get; set; } public string Direction { get; set; } public int Segments { get; set; } public string Type { get; set; } public string DataEncoding { get; set; } public int Priority { get; set; } public List Statuses { get; set; } public DateTimeModified { get; set; } public string Mcc { get; set; } public string Mnc { get; set; } } public class Status { public DateTime Created { get; set; } public int Code { get; set; } public int Duration { get; set; } }