This tutorial explains how to set up remotes using the REST API. In order to do so, we will need to understand how to configure the callback and send a remote command.

Post Channel #

The first step is to configure a reusable configuration settings named channel.

1
2
3
4
5
6
7
$ curl \
  --POST \
  --url /accounts/channels \
  --data 'client_id=<client_id>' \
  --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
  --cert 'path/to/client_cert.pem[:<cert_password>]' \
  --key 'path/to/key.pem' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "label": "Channel Remote 755",
    "channel": {
        "webhook": {
            "target": "https://webhook.site/a1fd8eac-a1a7-452c-9169-441ef8fdd098",
            "name": "webhook",
            "attributes": [
                {
                    "type": "Header",
                    "key": "x-vehicle-id",
                    "value": "$vin"
                }
            ]
        }
    }
}

Below is a description of the JSON body to configure the channel.

• label is the name of the callback. 
• callback.webhook: to set up the reception server and the notification attributes (headers, query params, body, usually use for routing).
• retryPolicy to configure how to deal with a server not receiving notifications. Retry Policy is described in this dedicated page.
• batchNotify if notifications needs to be received in batches instead of one by one.
• remoteTypes allows to set up which type of remotes can work with this callback.

Be careful: it’s only possible to send one remote action at once. However, callbacks are re-usable for multiple those remote action.

Example of Remote Operation

This example creates a remote operation with the following parameters:

• If the callback notification is not received, the request will be sent again every 120s until it’s properly delivered.
• The callback will be sent once 10 callback notifications are ready to be sent or 300s after triggering.
• The callback will be sent to https://my.post.callback webhook, with the VIN of the vehicle as a query path parameter and the Basic authentication in HTTP headers.
• This callback can be used in order to send remote action: ChargingSchedule.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "label": "charging",
    "action": {
        "charging": {
            "charge": {
                "immediate": false,
                "programs": [
                    {
                        "enabled": true,
                        "start": "PT12H30M",
                        "end": "PT14H30M",
                        "chargeToFull": false,
                        "occurrence": {
                            "day": [
                                "Mon",
                                "Tue",
                                "Wed",
                                "Thu"
                            ]
                        },
                        "minChargingLevel": 20,
                        "maxChargingLevel": 80,
                        "slot": 1,
                        "actionsType":"Set"
                    }
                ]
            }
        }
    }
}

If the remote operation is properly created the HTTP response body will look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "_links": {
        "channel": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
        },
        "remote": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
        }
    },
    "remoteActionId": "string",
    "type": "Locking"
}

This message indicates that the callback has been sucessfully created with a unique identifier. This identifier, called {chid} is required to create a remote.

Post Remote Request #

The following example is the structure of the HTTP request intended to send a remote command.

The following path parameters are required, they need to be replaced by the appropriate value:

• {id} is the id.
• {vid} is the id of the vehicle to send a remote to.
• {cbid} is the id of a callback, this id is received when a callback is created.

1
2
3
4
5
6
7
$ curl \
  --POST \
  --url /accounts/vehicles/{id}/channels/{chId}/remotes \
  --data 'client_id=<client_id>' \
  --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
  --cert 'path/to/client_cert.pem[:<cert_password>]' \
  --key 'path/to/key.pem' \

1
2
3
4
5
6
7
8
{
    "label": "doors",
    "action": {
        "locking": {
        "state": "Unlocked"
        }
    }
}

Below is a description of the JSON body to configure the remote, refers to API Reference for the specification of this endpoint.

• label is the name of the remote.

• <remote-type> objects allow configuring the remote action to send, checkout remote actions. Only one remote can be sent at once.

Post Remote Response #

This is an example of HTTP response when sending a remote action:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "_links": {
        "channel": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
        },
        "remote": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
        }
    },
    "remoteActionId": "string",
    "type": "Locking"
}

This message indicates that the remote has been successfully created with a unique identifier. This identifier is sent with every notification; therefore, it allows tracking this remote.

Remote Actions #