SMS Inbound API

Inbound SMS

API Documentation

Senest redigeret:

Introduction

An Inbound SMS represents a text message received matching your merchant’s active keywords or subkeywords.

Properties

Name

Type

Example

Description

messageGuid

STRING

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

Unique identifer of received incoming text message

channel

STRING

1217

The shortcode

keywordGuid

STRING

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

The guid of the located keyword or subkeyword

keyword

STRING

tifo

The keyword

subKeyword

STRING

100

The subkeyword

receivedText

STRING

TIFO 100 thank you

The received text message

state

STRING

 

Three states possible: Received | Processed | Error

msisdn

STRING

4512345678

Phone with Country Code (wiki on Country Code) with 1-3 digits reserved for country code without prefixes, such as 00 (wiki on MSISDN).

campaignGuid

STRING

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

The guid of the applied campaign

processedTs

DATE

2019-12-31 15:59:59 +0100

Timestamp at which the text message was received and processed

Endpoints

GET /SmsMO/{guid}

Get a specific inbound message.

Response

HTTP

Description

200

OK

HTTP 200 Example

{
        "messageGuid": "17934114-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "createdTs": "2021-02-10 13:33:23 +0100",
        "channel": "1217",
        "keyword": "STØT",
        "receivedText": "Støt",
        "keywordGuid": "3b03ac9a-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "state": "Processed",
        "msisdn": "4540xxxxxx",
        "merchantId": "min_organisation",
        "campaignGuid": "9b6ae17d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "processedTs": "2021-02-10 13:33:23 +0100"
    }

GET /SmsMO?pageNumber={x}&pageSize={y}

Get a list of received inbound text messages at a given size by a given offset.

Response

HTTP

Description

200

OK

HTTP 200 Example

{
    "pageNumber": 1,
    "pageSize": 100,
    "list": [
        {
            "messageGuid": "c6a2e42c-1592-4ed8-beb0-xxxxxxxxxxxx",
            "createdTs": "2019-11-04 16:21:48 +0100",
            "channel": "1217",
            "keyword": "subscription",
            "subKeyword": "stop",
            "receivedText": "Subscription STOP",
            "keywordGuid": "41b02f9c-17f4-4fec-b2d5-xxxxxxxxxxxx",
            "state": "Processed",
            "msisdn": "4510111213",
            "merchantId": "Fundraisingbureauet",
            "campaignGuid": "afa0327a-5c42-4e7e-981d-xxxxxxxxxxxx",
            "processedTs": "2019-11-04 16:21:48 +0100"
        },
        {
            "messageGuid": "a01db37d-39cb-4fee-a5b2-xxxxxxxxxxxx",
            "createdTs": "2019-11-04 16:20:46 +0100",
            "channel": "1217",
            "keyword": "subscription",
            "receivedText": "Subscription",
            "keywordGuid": "41b02f9c-17f4-4fec-b2d5-xxxxxxxxxxxx",
            "state": "Processed",
            "msisdn": "4510111213",
            "merchantId": "Fundraisingbureauet",
            "campaignGuid": "afa0327a-5c42-4e7e-981d-xxxxxxxxxxxx",
            "processedTs": "2019-11-04 16:20:46 +0100"
        }
    ]
}

Resulting DataSet from an Inbound SMS

Every Inbound SMS will insert a DataSet containing the received SMS ( smsMo = mobileOriginated ) and the response ( smsMt = mobileTerminated ) based on the matched Keyword and applied Campaign as they were configured at the time of processing.

{
  "dataSetGuid": "9f241ecb-3363-40c6-a9c2-xxxxxxxxxxxx",
  "merchantId": "merchant-name",
  "createdTs": "2019-10-07 08:14:05 +0200",
  "jsonElement": {
    "smsMo": {
      "messageGuid": "612999b2-c7e9-45bf-9763-xxxxxxxxxxxx",
      "createdTs": "2020-01-14 13:53:31 +0100",
      "channel": "1217",
      "keyword": "subscription",
      "subKeyword": "stop",
      "receivedText": "Subscription STOP",
      "keywordGuid": "4e1f7fb3-6acb-4adc-a8ec-xxxxxxxxxxxx",
      "state": "Processed",
      "msisdn": "4510111213",
      "merchantId": "merchant-name",
      "campaignGuid": "0f18d6d9-13dd-4719-b93e-xxxxxxxxxxxx",
      "processedTs": "2020-01-14 13:53:32 +0100"
    },
    "smsMt": {
      "messageGuid": "1358d458-66f7-4043-9468-xxxxxxxxxxxx",
      "createdTs": "2020-01-14 13:53:31 +0100",
      "msisdn": "4510111213",
      "text": "Hi! Thank you so much for contacting us, we really appreciate that. Your messages are the only thing keeping us afloat.",
      "channel": "1217",
      "keyword": "subscription",
      "subKeyword": "stop",
      "senderAlias": "1217",
      "callbackUrl": "https://domain.tld/outbound/callback",
      "serviceId": "1217-Subscription",
      "state": "Delivered",
      "externalId": "1579006411283",
      "moReferenceGuid": "612999b2-c7e9-45bf-9763-xxxxxxxxxxxx",
      "merchantId": "merchant-name",
      "deliveredTs": "2020-01-14 13:53:48 +0100",
      "handleCallback": true,
      "smscphMessageGuid": "cec025b3-b17e-4660-8a97-xxxxxxxxxxxx",
      "subscriptionMessage": false
    },
    "keyword": {
      "keywordGuid": "4e1f7fb3-6acb-4adc-a8ec-xxxxxxxxxxxx",
      "createdTs": "2019-10-24 15:33:48 +0200",
      "merchantId": "merchant-name",
      "channel": "1217",
      "keyword": "subscription",
      "subKeyword": "stop",
      "active": true,
      "campaignGuid": "0f18d6d9-13dd-4719-b93e-2bc7b560f28c",
      "keywordIdleText": "Not understood"
    },
    "campaign": {
      "campaignGuid": "0f18d6d9-13dd-4719-b93e-xxxxxxxxxxxx",
      "createdTs": "2019-10-24 15:37:02 +0200",
      "merchantId": "merchant-name",
      "active": true,
      "campaignName": "Test",
      "replyText": "Hi! Thank you so much for contacting us, we really appreciate that. Your messages are the only thing keeping us afloat.",
      "serviceType": "Message",
      "taxDeductable": false,
      "paymentRequired": false,
      "targetAudienceUnderAge": false,
      "urlShortener": "kortl.ink",
      "replyTextUrl": "https://www.test.tld",
      "metaData": {
        "Key1": "Value1",
        "Key2": "Value2"
      }
    },
    "paymentSessionResult": {
      "postProcessedTs": "2019-12-31 15:59:59 +0100",
      "postProcessingErrorTs": "2019-12-31 15:59:59 +0100",
      "postProcessingErrorDescription": "",
      "contactGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "paymentMethodGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "agreementGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "subscriptionGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "paymentGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
    }
  }
}