How may we help?

Introduction

A keyword represents the first word of a text message sent to your shortcode, and a subkeyword represents an optional second word. They are used for similar purposes with primary difference being that subscriptions can only be created on keywords. Both keywords and subkeywords are tied to your shortcode. The default shortcode is “1217”, however it is possible to use existing shortcodes or book specific ones for your organization through OnlineFundraising.

A subkeyword cannot be created within the keyword of that subkeyword already existing. An unlimited amount of subkeywords can be tied to a keyword, however, each subkeyword has to be unique. Each keyword or subkeyword can be related to a Campaign, which define how text messages received on the chosen keyword/subkeyword should be handled.

Examples

• Keywords
  • “hjælp“
  • “støt”
  • “mad”
• Subkeywords
  • “hjælp 100”
  • “hjælp 25”
  • “støt nu”
  • “støt sult“
  • “mad syrien”

Properties

Name	Type	Mandatory	Example	Description
keywordGuid	STRING	-	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID
active	BOOLEAN	-
campaignGuid	STRING	NO	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID of Campaign
channel	STRING	YES	1217	Channel (“shortcode”) receiving the inbound text messages
keyword	STRING	YES	"TIFO"	The keyword used to distinguish inbound text messages
subKeyword	STRING	NO	"100" allowing "TIFO 100"	The subkeyword used to distinguish additional content text messages
keywordStartDate	DATETIME	NO	2019-10-17 14:37:26 +0200	Defines beginning of donation approval
keywordEndDate	DATETIME	NO	2019-10-17 14:37:26 +0200	Defines end of donation approval
keywordIdleText	STRING	NO	"Thanks, but the Campaign is not active."	Reply text for messages received on the keyword before and after approved donation dates, and if no active campaign is related to the keyword
createdTs	DATETIME	-	2019-10-17 14:37:26 +0200	Date of creation
deletedTs	DATETIME	-	2019-10-17 14:37:26 +0200	Date from which the keyword is no longer effectively active
webhookEndpointUrl	STRING	NO	https://yourEndpoint.dk/ReceiveWebhook	Endpoint to send webhooks of received messages to. Max 255 characters in length.

Endpoints

GET /keywords

Get a list of keywords and subkeywords.

Response

HTTP	Description
200	OK

HTTP 200 Example

[
  {
    "keywordGuid": "b9e23j99-55f7-4e80-a144-xxxxxxxxxxxx",
    "createdTs": "2019-10-17 14:37:26 +0200",
    "channel": "1217",
    "keyword": "tifo",
    "subKeyword": "100",
    "active": true,
    "webhookEndpointUrl": "https://enb64ilxmkaj8wr.org"
  }
]

GET /keyword/{keywordGuid}

Get a single keyword or subkeyword.

Response

HTTP	Description
200	OK
404	Not found

HTTP 200 Example

{
    "keywordGuid": "b8a26c17-55f7-4e80-a144-xxxxxxxxxxxx",
    "createdTs": "2019-10-17 14:37:26 +0200",
    "merchantId": "onlinefundraising",
    "channel": "1217",
    "keyword": "tifo",
    "active": true,
    "campaignGuid": "c669d751-a82c-476f-9fbe-xxxxxxxxxxxx",
    "keywordIdleText": "Not understood",
    "keywordStartDate": "2019-10-01 14:37:26 +0200",
    "keywordEndDate": "2019-10-31 14:37:26 +0200",
    "webhookEndpointUrl": "https://enb64ilxmkaj8wr.org"
}

GET /keyword/{keywordGuid}/subkeywords

Get a single keyword’s subkeywords.

Response

HTTP	Description
200	OK
404	Not found

HTTP 200 Example

[
  {
    "keywordGuid": "b9e23j99-55f7-4e80-a144-xxxxxxxxxxxx",
    "createdTs": "2019-10-17 14:37:26 +0200",
    "merchantId": "OnlineFundraising",
    "channel": "1217",
    "keyword": "tifo",
    "subKeyword": "100",
    "active": true,
    "campaignGuid": "c669d751-a82c-476f-9fbe-xxxxxxxxxxxx",
    "keywordIdleText": "Not understood",
    "keywordStartDate": "2019-10-01 14:37:26 +0200",
    "keywordEndDate": "2019-10-31 14:37:26 +0200"
  }
]

GET /keyword/Check?channel={channel}&keyword={keyword}

Check whether a keyword (such as “tifo”) is available on the channel (such as 1217).

Response

HTTP	Description
200	OK

HTTP 200 Example of an available keyword

{
    "keywordStatus": "free"
}

 

HTTP 200 Example of an unavailable keyword

{
    "keywordStatus": "unavailable"
}

POST /keyword/Reserve

Reserve a single keyword.

Request

The following must be provided as the request body:

{
  "keyword": "tifo",
  "channel": "1217"
}

Response

HTTP	Description
201	Created
400	Something's wrong with request body
405	Not allowed

HTTP 201 Example

{
  "keywordGuid": "b8a26c17-55f7-4e80-a144-xxxxxxxxxxxx",
  "createdTs": "2019-10-17 14:37:26 +0200",
  "channel": "1217",
  "keyword": "tifo"
}

POST /keyword/Reserve

Reserve a single subkeyword to an existing keyword.

Request

The following must be provided as the request body:

{
  "keyword": "tifo",
  "subKeyword": "100",
  "channel":"1217"
}

Response

HTTP	Description
201	Created
400	Something's wrong with request body.
405	Not allowed

HTTP 201 Example

{
  "keywordGuid": "b9e23j99-55f7-4e80-a144-xxxxxxxxxxxx",
  "createdTs": "2019-09-30 14:48:13 +0200",
  "channel": "1217",
  "keyword": "tifo",
  "subKeyword": "100"
}

POST /keyword/{keywordGuid}/Deactivate

Deactive a single keyword or subkeyword.

Response

HTTP	Description
200	OK
404	Not found

POST /keyword/{keywordGuid}/Reactivate

Reactive a single inactive keyword before the keyword’s deletedTs.

Response

HTTP	Description
200	OK
404	Not found