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”, |
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. |