Public API – POST Custom Action

The actions endpoint allows a new Custom Action to be created and added to an existing Zone. A call back is generated within the application, enabling the implementation of customized behaviour.

Custom Actions can be added regardless of whether the Zone was created using the public API or via the web interface for the Bluedot back-end system, Point Access. One or more conditions can be attached to an action as shown in the example below. Conditions can be added at a later stage through the update action.

URL to call

https://api.bluedotinnovation.com/1/actions

Content Type

The content type should be specified in the Content-Type HTTP header as “application/json”.

image

Content-Type: application/json

Parameters

No URL Parameters required. See example JSON below.

Key JSON fields

Name
Required
Data Type
Description
Format
customerApiKey String API key for customer (rather than the app).
apiKey String API key for the app.
zoneId String The identifier of the zone being updated.
actions Object The actions object is used to add the different action types (Message, URL and Custom).
customActions Array The customActions array is used to add one or more custom actions to the zone.
name String An identifying name for the Custom action.

Example: JSON request to create a custom action

{
    "security": {
        "customerApiKey": "bc199c80-5441-11e4-b7bb-a0481cdc3311",
        "apiKey": "d3161e80-38d1-11e4-b039-bc305bf60831"
    },
    "content": {
        "zone": {
            "zoneId": "24d9a245-2087-421b-9972-2af2ee0970f1",
            "actions": {
                "customActions": [
                    {
                        "name": "A Custom action"
                    }
                ]
            }
        }
    }
}

 

Example: JSON request to create a custom action with conditions

 

{
    "security": {
        "customerApiKey": "bc199c80-5441-11e4-b7bb-a0481cdc3311",
        "apiKey": "d3161e80-38d1-11e4-b039-bc305bf60831"
    },
    "content": {
        "zone": {
            "zoneId": "24d9a245-2087-421b-9972-2af2ee0970f1",
            "actions": {
                "customActions": [
                    {
                        "name": "My Custom action",
                        "conditions": {
                            "percentageCrossed": [
                                {
                                    "percentage": 50,
                                    "timeoutPeriod": "00:01",
                                    "sequential": false
                                }
                            ],
                            "dateRange": [
                                {
                                    "start": "12/12/2014",
                                    "end": "14/12/2015"
                                }
                            ],
                            "timeActive": [
                                {
                                    "from": {
                                        "time": "10:00",
                                        "period": "am"
                                    },
                                    "to": {
                                        "time": "2:00",
                                        "period": "pm"
                                    }
                                }
                            ],
                            "bearing": [
                                {
                                    "fromAngle": 80,
                                    "toAngle": 200
                                }
                            ],
                            "speed": [
                                {
                                    "minimumSpeed": 10,
                                    "maximumSpeed": 30
                                }
                            ]
                        }
                    }
                ]
            }
        }
    }
}

Example: JSON request to create a custom action with custom data fields

To receive custom metadata as part of the Custom Action callback when a device moves into a Fence or comes in the range of a Beacon, add the custom fields envelope as part of the custom action POST request.

image

As of version 1.8 only 5 custom data fields can be added for a single custom action.

Name
Required
Data Type
Description
Format
key String The name of the metadata field to be returned as part of the custom action callback on the device.
value String The value of the metadata field to be returned as part of the custom action callback on the device.
{
    "security": {
        "customerApiKey": "bc199c80-5441-11e4-b7bb-a0481cdc3311",
        "apiKey": "d3161e80-38d1-11e4-b039-bc305bf60831"
    },
    "content": {
        "zone": {
            "zoneId": "24d9a245-2087-421b-9972-2af2ee0970f1",
            "actions": {
                "customActions": [
                    {
                        "name": "Blue Bottle Coffee custom action",
                        "customFields":[
                            {
                                "key":"Store Type",
                                "value":"Coffee Shop"
                            },
                            {
                                "key":"Name",
                                "value":"Blue Bottle Coffee"
                            },
                            {
                                "key":"ID",
                                "value":"48707775-4991-434b-ba3a-f41ac1236c44"
                            }
                        ]
                    }
                ]
            }
        }
    }
}

Example: JSON response to request

 

{
    "objectsUpdated": [
        {
            "actionId": "5e8556a5-5025-4a71-baff-3050fbd9dff1",
            "actionName": "A Custom action"
        }
    ],
    "message": "Your request has been successfully processed.",
    "messageCode": 200
}

Source code examples

Created by Bluedot DevOps on March 3, 2018

Start the discussion