SMS Outbound API

Batch

API Documentation

Senest redigeret:

Introduction

A Batch represents a list of text messages to be sent from a given date and within given hours of the day.

Properties

Name

Type

Mandatory

Default

Example

Description

batchGuid

STRING

NO

 

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

Unique GUID of the entity.

batchName

STRING

YES

 

 

Name of the batch.

createdTs

TIMESTAMP

NO

 

2020-01-01 13:05:00 +0100

Time at which a batch was created.

channel

INTEGER

YES

 

1217

The shortcode.

serviceId

STRING

NO

 

 

 

merchantId

STRING

NO

 

“onlinefundraising”

The name of the Merchant who owns the batch.

state

STRING

NO

 

"New", "Pending", "Started", "Stopped", "Done"

The current state of the batch.

senderAlias

STRING

NO

 

“1217”

The displayed name of the sender of the messages in the batch.

scheduledStartTs

TIMESTAMP

NO

Current time value (now).

2020-01-01 13:00:00 +0100

Definition of when the first message of the batch will be scheduled to be send.

scheduledEndTs

TIMESTAMP

NO

 

2020-01-05 13:00:00 +0100

Definition of when the last message of the batch will be scheduled to be sent.

A longer interval between the start and end times will spread out messages, such that the systems they might link to are not put under unnecessary stress.

timeframeStartHour

INTEGER

NO

 

8

Definition of from which hour of the day text messages can be sent, including the given hour.

timeframeEndHour

INTEGER

NO

 

21

Definition of until which hour of the day text messages can be sent, not including the given hour.

callbackUrl

STRING

NO

 

 

The URL receiving callbacks.

callbackVerbosity

STRING

NO

 

“ALL”,
“Delivered”,
“DeliveryFailed”

The type of callbacks.

archivedTs

TIMESTAMP

NO

NULL

2020-01-05 13:00:00 +0100

Definition of when the batch was archived, meaning no longer used.

Endpoints

GET /batches?showArchived={true | false}

Get the list of batches. The showArchived query parameter defaults to “false”, and is optional.

Response

HTTP

Description

200

OK

400

Bad request

HTTP 200 Example

[
    {
        "batchId": 1,
        "createdTs": "2021-09-28 13:17:04 +0200",
        "batchGuid": "0424c6f9-4857-46f1-9051-65d7a732a30f",
        "merchantId": "merchant",
        "batchName": "my-batch",
        "state": "New",
        "channel": "1217",
        "senderAlias": "1217",
        "scheduledStartTs": "2021-09-24 13:00:00 +0200",
        "callbackUrl": "https://webhook.site/decfc453-393c-48e6-be58-66ca0fefe8bf"
    },
    {
        "batchId": 2,
        "createdTs": "2021-09-23 15:51:28 +0200",
        "batchGuid": "28f13dc0-b83a-4e60-bd29-f23fd40dbc28",
        "merchantId": "merchant",
        "batchName": "my-batch"
        "state": "New",
        "channel": "1217",
        "senderAlias": "1217",
        "scheduledStartTs": "2021-09-24 13:00:00 +0200",
        "callbackUrl": "https://webhook.site/decfc453-393c-48e6-be58-66ca0fefe8bf"
    }
]

 

GET /batch/{batchGuid}

Get a single batch.

Response

HTTP

Description

200

OK

404

Not found

HTTP 200 Example

{
  "batchGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "batchName": "my-batch",
  "channel": "1217",
  "serviceId": "my-batch-serviceid",
  "senderAlias": "1217",
  "scheduledStartTs": "2019-12-04 13:00:00 +0100",
  "scheduledEndTs": "2019-12-04 13:30:00 +0100",
  "timeframeStartHour": 8,
  "timeframeEndHour": 21,
  "callbackUrl": "https://mycallback.tld",
  "callbackVerbosity": "ALL"
}

 

GET /batch/{batchGuid}/messageCount

Get the message count attached to the specified batch.

Response

HTTP

Description

200

OK

404

Not found

HTTP 200 Example

{
    "messageCount": 116,
    "messagePartCount": 200
}

 

GET /batch/{batchGuid}/files

Get the files attached to the given batch

Response

HTTP

Description

200

OK

404

The batch was not found

HTTP 200 Example

[
    {
        "fileGuid": "1f042ebd-8bb5-40cb-b23e-e1ba693a8b4a",
        "batchId": 1,
        "fileLink": "1_file.csv",
        "merchantId": "test",
        "state": "Uploaded"
    }
]

 

GET /batch/{batchGuid}/file/{fileGuid}/errors

Gets the errors on the given file which will be present if it failed the validation.

Response

HTTP

Description

200

OK

404

The file was not found

HTTP 200 Example

[
    {
        "row": 0,
        "count": 0,
        "error": "Invalid csv format: Number of data fields does not match number of headers."
    }
]

 

POST /batch

Create a batch.

Request

The following must be provided as the request body:

{
  "batchName": "my-batch",
  "channel": "1217",
  "serviceId": "my-batch-serviceid",
  "senderAlias": "myNGO",
  "scheduledStartTs": "2019-12-04 13:00:00 +0100",
  "scheduledEndTs": "2019-12-04 13:30:00 +0100",
  "timeframeStartHour": 8,
  "timeframeEndHour": 21,
  "callbackUrl": "https://mycallback.tld",
  "callbackVerbosity": "ALL"
}

Scheduling the messages

The fields scheduledStartTs, scheduledEndTs, timeframeStartHour and timeframeEndHour are used to configure how the messages are sent. Consider the cases where:

  • The messages attached to the batch need to be sent out today, as quickly as possibly after a batch has been started. Here you do not need to provide any of the fields, as scheduledStartTs defaults to the current time.

    {
      "batchName": "my-batch",
      "channel": "1217",
      "serviceId": "my-batch-serviceid",
      "senderAlias": "myNGO"
    }
  • Spread the messages out during the day, between the time interval 13-16 today (2019-12-04). The first message will be sent at 13:00:00 and the last one will be sent 15:59:59.

    {
      "batchName": "my-batch",
      "channel": "1217",
      "serviceId": "my-batch-serviceid",
      "senderAlias": "myNGO",
      "scheduledStartTs": "2019-12-04 13:00:00 +0100",
      "scheduledEndTs": "2019-12-04 16:00:00 +0100"
    }
  • Send a batch as quickly as possible after 10:00:00. If for some reason some messages are delayed. They will not sent after 22:00:00, but delayed until the following day after 08:00:00.

    {
      "batchName": "my-batch",
      "channel": "1217",
      "serviceId": "my-batch-serviceid",
      "senderAlias": "myNGO",
      "scheduledStartTs": "2019-12-04 10:00:00 +0100",
      "timeframeStartHour": 8,
      "timeframeEndHour": 22
    }

Response

HTTP

Description

201

Created

400

Bad request

HTTP 201 Example

{
  "batchGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  ...
}

 

POST /batch/{batchGuid}/messages

Add text messages to a given batch in increments of 5000 per request.

Request

It is required that the external Id is unique for each message per batch.

The following must be provided as the request body, note that the shortened link details are optional:

[
  {
    "msisdn": "4512345678",
    "text": "test-text1 {{abcd}} end",
    "externalId": "ext-id-1",
    "shortenLink": {
      "shortLinkDomain": "kortl.ink",
      "urls": [
        {
          "placeholder": "{{abcd}}",
          "url": "https://onlinefundraising.dk"
        }
      ]
    }
  }
]

Response

The response will be a 201 Created if the call went well. The response body will contain information of which messages were successfully added, along with those that failed the validation (which are marked with the error field).

HTTP

Description

201

Created

400

Bad request

HTTP 200 Example

[
    {
        "error": "text is required",
        "externalId": "ext-id-2"
    },
    {
        "messageGuid": "262c2245-f28a-4e93-bbd8-a41f83885535",
        "externalId": "ext-id-1"
    },
    {
        "messageGuid": "e7ddd7e6-deaa-48ef-a4d3-2793335cffda",
        "externalId": "ext-id-3"
    }
]

 

POST /batch/{batchGuid}/Start

Start sending the given batch.

Response

HTTP

Description

200

OK

404

The batch was not found

 

POST /batch/{batchGuid}/Stop

Stop the given batch during processing.

Response

HTTP

Description

200

OK

404

The batch was not found

 

POST /batch/{batchGuid}/Archive

Archive the batch, marking it as “finished”.
The batch cannot be archived when it’s in state “Started” or “Pending”.

Response

HTTP

Description

200

OK

400

Bad Request (when the batch is in state “Started” or “Pending”)

404

The batch was not found

 

POST /batch/{batchGuid}/Empty

Empty the batch, removing all messages and files related to it.
The batch can only be emptied when it’s in state “New”.

Response

HTTP

Description

200

OK

400

Bad Request (when the batch is not in state “New”)

404

The batch was not found

 

POST /batch/{batchGuid}/fileUpload

Adds a CSV, XLSX or XLS file to a given batch through form data. The file must contains these columns:

Requirement

Description

msisdn

Required.

text

Required.

externalId

Optional.

shortLinkDomain

Optional. Følgende tillades: kortl.ink, giiv.dk

url

Optional. Kun URL gyldige tegn (dvs. ingen æøå mv.).

placeholder

Optional. Formatet: {{placeholder}} kræves.

The file structure will not be validated on this call.

Request

{
  "messagesFile" : <the file as form data>
}

Response

HTTP

Description

200

Ok - The file was uploaded

400

Bad request - invalid file type

404

The batch was not found

 

POST /batch/{batchGuid}/file/{fileGuid}/Validate

Validates the given file, and provides error descriptions for which rows were unsuccessful.

The filed can only be validated when it’s in state “Uploaded”.

Response

HTTP

Description

200

The file will be validated

400

The file was not able to be validated, since it was not in state “Uploaded”

404

The file was not found

 

POST /batch/{batchGuid}/file/{fileGuid}/Import

Imports the messages from the file to the batch

The filed can only be imported when it’s in state “Validated”.

Response

HTTP

Description

200

The file will be imported

400

The file was not validated yet (its not in state “Validated”)

404

The file was not found

 

PATCH /batch/{batchGuid}

Update values of a created batch.

Patchable fields are: "batchName", "senderAlias", "scheduledStartTs", "scheduledEndTs", "timeframeStartHour", "timeframeEndHour"

Request

The following must be provided as the request body:

[
  {
    "op": "add|replace|remove",
    "path": "/batchName",
    "value": "My inventive batchname"
  }
]

Response

HTTP

Description

200

OK

400

Something is wrong with request body

404

Batch was not found

GET /BatchStatisticsServlet?guid={batchGuid}

Get current statistics on the batch - batchGuid must be specified as “guid”.

Response

HTTP

Description

200

OK

404

Not found

HTTP 200 Example

[
  {
    "state": "New",
    "count": 142
  },
  {
    "state": "Processed",
    "count": 2
  },
  {
    "state": "Delivered",
    "count": 3
  },
  {
    "state": "DeliveryFailed",
    "count": 1
  }
]

 

DELETE /batch/{batchGuid}/file/{fileGuid}

Deletes the given file

Response

HTTP

Description

200

The file was deleted

400

Bad request

404

The file was not found.