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.

HTTP request headers used in this tutorial require to use realms.

Post Callback #

The first step is to configure a reusable configuration settings named callback. The same callback can be used for monitors and/or remote features of this API.

Registering a callback can be done using the following API. They are 3 types of callback notifications: WebHook, Push Notification, WebSocket.

1
2
3
4
5
6
7
8
9
10
$ curl \
  --request POST \
  --url 'https://api-cert.groupe-psa.com/connectedcar/v4/user/callbacks' \
  --data-urlencode 'client_id=<client_id>' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-introspect-realm: <realm>' \
  --key 'path/to/key.pem' \
  --cert 'path/to/client_cert.pem[:<cert_password>]' \
  --cacert 'path/to/ca_cert.pem' \
  --data '<check out HTTP body>' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "label": "<callback-name>",
  "type": ["Monitor", "Remote"],
  "callback": {
    "webhook": {
      "target": "https://my.post.callback",
      "name": "<webhook-name>",
      "batch": { "enabled": true, "size": 100 },
      "attributes": [ { "type": "Header", "key": "X-Vehicle_Id", "value": "$vin"} ]
    },
    "pushnotif": {
      "devices": ["<device_name>"],
      "attributes": [ { "type": "Header", "key": "X-Vehicle_Id", "value": "$vin"} ]
    },
    "websocket": {
      "target": "scheme://host[:port][/Path]",
      "batch": { "enabled": true, "size": 100 },
      "attributes": [ { "type": "Header", "key": "X-Vehicle_Id", "value": "$vin" } ]
    }
  }
}

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

• label is the name of the callback. 
• type to declare a callback for Monitor, Remote or both.
• callback allows to configure notifications, they can be of 3 different types:
  • webhook: for HTTP notification.
  • websocket: for websocket callbacks.
  • pushnotif: using Firebase Cloud Messaging in order to trigger push notification on iOS (APNs) or Android (GCM).
• callback.<notification_type> allow to configure:
  • attributes: to setup additional attributes of the notification (headers, query params, body). These attributes are usually used for routing.
  • batch: webhook & websocket notifications can be send in batch, it’s recommended to use batch over single time notification.

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

1
2
3
4
5
{
  "_links": {  },
  "callbackId": "<id>",
  "status": "Running"
}

This message indicates that the callback has been sucessfully created with a unique identifier. This identifier, called {cbid} 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 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
8
9
10
$ curl \
  --request POST \
  --url 'https://api-cert.groupe-psa.com/connectedcar/v4/user/vehicles/{id}/callbacks/{cbid}/remotes' \
  --data-urlencode 'client_id=<client_id>' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-introspect-realm: <realm>' \
  --key 'path/to/key.pem' \
  --cert 'path/to/client_cert.pem[:<cert_password>]' \
  --cacert 'path/to/ca_cert.pem' \
  --data '<check out HTTP body>' \

1
2
3
4
5
6
7
8
{
  "label": "remote_name",
  "attributes": {  }
  "callbackAttributes": {  },
  "door": {
    "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.

• attributes & callbackAttributes: allows adding or to overwrite key/value attributes declared in the callback creation, it will be available in the notification as query parameters, headers or body. Attributes (vin, CallbackID & CallbackLabel) are useful to perform the routing of the notification.

• <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
{
  "_links": {  },
  "remoteActionId": "909bkqacjb3bfhdhjanahbc244jj2lixfbe2e52u5y",
  "type": ["ThermalPreconditioning"]
}

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 #