Conversations

Read messages to and/or from a given participant.

Quick start

Using the example below, replace “API_NYCKEL” with a bearer token that you create in the user portal and replace {participant} with a number in the format MSISDN (46712345678)

curl -X POST "https://api.ip1sms.com/v2/conversations/{participant}" \
-H "Authorization: Bearer API_NYCKEL" \
-H "Content-Type: application/json" \

call

Get all messages

This endpoint allows you to retrieve all messages in a conversation, regardless of direction, based on the recipient or sender's number.

Endpoint: /v2/conversations/{participant}

Methodology: GET

Examples of calls

https://api.ip1sms.com/v2/conversations/46712345678

Retrieve all outgoing messages

This endpoint allows you to retrieve outgoing messages in a conversation based on a specified participant. mt is an acronym for mobile terminated.

Endpoint: /v2/conversations/{participant}/mt

Methodology: GET

Examples of calls

https://api.ip1sms.com/v2/conversations/46712345678/mt

Get all incoming messages

This endpoint allows you to retrieve incoming messages in a conversation based on the specified participant. mo is an acronym for mobile originated.

Endpoint: /v2/conversations/{participant}/mo

Methodology: GET

Examples of calls

https://api.ip1sms.com/v2/conversations/46712345678/mo

Download a summary of messages

Apart from reading messages to and from specific MSISDNs we also provide an endpoint which gives you an aggregated summary with mt and mo

Endpoint /v2/conversations/{participant}/summary

Methodology: GET

Examples of calls

https://api.ip1sms.com/v2/conversations/46712345678/summary

Fields for call data

Field name Mandatory Type Description and Conditions Example
participant Yes String A participant's number in the format MSISDN (46712345678). 

46712345678

Response

Response data for a call to /v2/conversations/{participant}/mt, /v2/conversations/{participant}/mo and /v2/conversations/{participant} returns a paginated list similar to the response data for listing messages.

Example of response data (Messages)

{
    "id": "5bcf4324ee47dee41a9dbb13",
    "batchId": "5bc86b6e85c7209830f96936",
    "owner": "ip1-XXXXX",
    "sender": "iP1",
    "recipient": "456189040623",
    "body": "Hi my name is earl",
    "direction": "mt",
    "segments": 1,
    "type":"SMS",
    "datacoding": "ucs",
    "priority": 1,
    "price": 0.0416,
    "currency": "EUR",
    "statuses": [
        {
            "created": "2018-10-23T17:43:21Z",
            "code": 201,
            "duration": 0
        }
    ],
    "modified": "2018-10-23T17:43:19Z",
    "reference": "A client reference",
    "mcc": "431"
    "mnc": "20"
}

Fields for response data (Messages)

Field name Type Description and Conditions Example
id String A unique ID for the specific message. 

"id": "5bcf4324ee47dee41a9dbb13"
batchId String The overall batch identifier 

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

"owner": "ip1-XXXXX"
sender String The sender of the message 

"sender": "iP1"
recipient String Recipient's mobile number 

"recipient": "456189040623"
body String The message itself 

"body": "Hi my name is earl"
direction String Tells you if the message 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 String 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
datacoding String Specifies the minimum data encoding scheme needed to send the message in question. If the message body contains characters outside the specified data encoding, the message is not sent, as the latest status code should indicate. This may differ from the batch data encoding. 

"datacoding": "ucs"
priority String The priority of the message. Priority 1 is the default value and also the lowest priority provided. Priority 2 is the highest priority. 

 "priority": 1
price String The price of the whole message. If you want to know the price of an individual SMS in a message, you can divide the message price by the number of segments. 

 "price": 0.0416
currency String Which currency the given price uses. 

  "currency": "EUR",
statuses Array A list of status updates containing the latest status of each message. 

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

"modified": "2018-10-23T17:43:19Z",
reference String This is a property that allows the user to set a custom ID or reference if storing the default default generated IDs is disallowed. 

"reference": "A client reference",
mcc String The country part of the leaf operator can be specified here if provided by the upstream carrier. MCC is an acronym for Mobile Country Code 

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

"mnc": "20"

Example of response data (Summary)

{ "participant": "46734487112", "totalMessageCount": 387, "totalSmsCount": 774, "mobileTerminatedMessages": { "101": { "messages": 43, "sms": 86 }, "102": { " messages": 3, "sms": 6 }, "201": { "messages": 142, "sms": 284 } }, "mobileOriginatedMessages": { "201": { "messages": 199, "sms" : 398 } } }

Response data field (Summary)

Field name Type Description and Conditions Example
participant String A participant is either an MSISDN (Mobile Number) or an alphanumeric sender (Text Sender). This field indicates the type of participant. 

"participant": "46734487112"
totalMessageCount Integer The total number of messages with the participant. 

"totalMessageCount: 387
totalSmsCount String The total number of SMS segments with the participant. 

"totalSmsCount": 774,
mobileTerminatedMessages Nestat object Summary of messages sent to the participant. This is a dictionary where the key is a status code and the value is the count of how many messages (and their corresponding SMS segments) has that status code as it's most recently added status. 

  "mobileTerminatedMessages": {
      "101": {
          "messages": 43,
          "sms": 86
      },
      "102": {
          "messages": 3,
          "sms": 6
      },
      "201": {
          "messages": 142,
          "sms": 284
      }
  },
mobileOriginatedMessages Nestat object Summary of messages sent from the participant. This is a dictionary where the key is a status code and the value is the count of how many messages (and their corresponding SMS segments) has that status code as it's most recently added status. 

  "mobileOriginatedMessages": {
      "201": {
          "messages": 199,
          "sms": 398
      }
  }