Receive incoming SMS

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/accounts/ → Settings for incoming SMS (See image below)

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

id

A unique ID for the specific message.

batchId

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

owner

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

sender

The sender ID of the message's originator.

recipient

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

body

The message contents.

direction

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.

segments

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.

datacoding

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

priority

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.

statuses

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.

modified

When the SMS was last updated.

mcc

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

mnc

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