Integrate Wave API

Overview

During API integration, there are 3 important stages that align with your customer’s experience.

  1. Set the Custom Event Metadata to be attached with each Wave Event – this is usually at least the customer’s name and orderID. (Learn more here)
  2. Define the DestinationId – this is where the customer is collecting their order. You can use anything, but we recommend using the normal Store Number or Restaurant ID.
  3. Define an Arrival callout (I’m here button) in the web page or app and set it up to submit a Wave API request when the callout

Endpoints

Wave API is hosted in multiple regions worldwide to ensure the better performance of our services. Each region is completely independent and in a separated geographic area.

REGION
URL
APAC
EUROPE
NORTH AMERICA

If you’re not sure which region your account is in, please contact us at help@bluedot.io.

API reference

The API specification for Wave API can be found here.

Wave Request Example

To send a Wave event you’ll need to make a POST request to the Wave endpoint. It only requires to sign the request with the projectId and include the destinationId that it’s effectively the Zone the user has arrived.

You can also add context to the Wave Event, such as the user’s location, the event’s time, and other properties that can help you better understand your user’s behaviour.

Request Signature

Wave API uses the projectId to sign requests. You’ll need to add the key x-bluedot-api-key with the projectId as the value in request’s headers as shown below:

"x-bluedot-api-key": "<YOUR_PROJECT_ID>"

You can find your projectId in the Canvas in the Account section.

Request Payload

Simple Example

// JSON
{
  "destinationId": "your_zone_destinationId"
}

Enriched Data Example

// JSON
{
  "destinationId": "melbourne_store_001",
  "customEventMetaData": {
    "userId": "your_user_id",
    "storeId": "your_store_id"
  },
  "location": {
    "longitude": 144.123123123,
    "latitude": -33.123123123,
    "horizontalAccuracy": 12.232323,
    "bearing": 123,
    "speed": 2
  },
  "eventTime": "2018-09-02T00:08:16.000Z"
}

Using Wave API with Hello Screens

The Wave Events can also inform Hello Screens of the arrival of a customer to a Zone. You just need to add the OrderId in the customEventMetaData as shown below:

// JSON
{
  "destinationId": "melbourne_store_001",
  "customEventMetaData": {
    "OrderId": "aslkfiowae"
  }
}

We also recommend using the other properties the Hello Screens provides, such as adding the customer’s name and any additional relevant information for your use case.

// JSON
{
  "destinationId": "melbourne_store_001",
  "customEventMetaData": {
    "OrderId": "aslkfiowae"
    "CustomerName": "James",
    "CarModel": "Honda Civic"
    "CarColor": "Red"
    "CarPlate": "ABC123",
    "MobileNumber": "3231234567"
  }
}

Integrate Wave in your Web page using the Web SDK

Created by Melwin Chiramel on March 1, 2021