Receive incoming SMS

If an incoming delivery URL is specified in account settings, incoming SMS messages will be sent to that URL whenever they are available. The contents of these SMS messages are described below.

Our system sends the report using POST and expects a 200 OK response if the report is delivered correctly. If any other status (ie an error status) is received, the report will be sent again at a later time.

You manage your callback url in the user portal → Settings for incoming SMS (See image below)

Report Payload

{ "id": "5c613848879973045cf39ac4", "batchId": "5c613848879973045cf39ac3", "owner": "ip1-XXXXX", "sender": "TestNOS", "recipient": "456189040623", "body": "Hi my name is earl", "direction": "mt", "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" }


A unique ID for the specific message.


An ID for all the messages received in the same request as this message. This is usually just the one.


The account ID of the SMS account that owns the message (e.g. you).


The sender ID of the message's originator.


The recipient of the message (e.g. your virtual number).


The message contents.


Determines whether the message was sent or received by our systems. Should always be mo here.

mt  an acronym for mobile terminated.
mo an acronym for mobile originated.


In case the message contains more characters than one sms can hold the message will be split into multiple sms also known as concatenated sms. This property indicates how many sms the message needs to be sent.


Specifies the datacoding scheme used to send the message in question.


The priority in which the message was sent. Priority 1 is the default and is the lowest priority that is available. Priority 2 is the higher priority.


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

Incoming messages only have one provided status as it entered our systems from outside. For more information regarding our status codes for messages please see our section about Status codes.


When the SMS was last updated.


The country part of the leaf operator may be specified here if it's provided by the upstream carrier.

MCC an acronym for Mobile Country Code


The network part of the leaf operator may be specified here if it's provided by the upstream carrier.

MNC an acronym for Mobile Network Code

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; } }