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). | |
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. | |
| batchId | String | The overall batch identifier | |
| owner | String | The account ID of the SMS account that owns the message (e.g. you). | |
| sender | String | The sender of the message | |
| recipient | String | Recipient's mobile number | |
| body | String | The message itself | |
| direction | String |
Tells you if the message sent or received by our system
| |
| 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 | |
| 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. | |
| 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. | |
| 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. | |
| currency | String | Which currency the given price uses. | |
| statuses | Array | A list of status updates containing the latest status of each message. | |
| modified | String | When the SMS was last updated. | |
| 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. | |
| 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 | |
| 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 | |
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. | |
| totalMessageCount | Integer | The total number of messages with the participant. | |
| totalSmsCount | String | The total number of SMS segments with the participant. | |
| 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. | |
| 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. | |