Developer guide
Highlight items in the menu and send events
Your server sends the menu context and Reach tells you which item to highlight. It then sends a VIEW when the item is seen and a CLICK when it is chosen. Base URL: https://adv.api.waithero.com/api/v1. Your secret API key goes in the x-api-key header, never in the browser.
The key field below is a visual simulation for the try-it panels on this page. In production everything is handled through the API, from your server.
It is only for the visual try-it panels below. In production the key never lives in the browser.
Overview
There are two ways to integrate, and Waithero decides which one applies to your account:
- Embed cards (recommended for websites): you place Waithero's card on your page, and Waithero records views and clicks itself. See Embed campaigns on your website.
- API: you show the campaign in your own interface, and your server reports each VIEW and CLICK. The three steps below are this flow.
If your approval email contains a publishable key (it starts with wh_pk_), your account uses embed cards.
Find what to highlight
Ask for campaigns matching the city, restaurant and dish.
Send a VIEW
When a campaign becomes visible.
Send a CLICK
When the user taps it.
Embed campaigns on your website
You search campaigns, add one <waithero-campaign> element for each campaign you want to show, and Waithero draws the card and counts its views and clicks. Any website that can add a script tag can use it, whatever its stack.
1. Your two keys
The email that approves your application contains two keys:
- Secret API key: for your server only. Never put it in a web page or in code that runs in the browser.
- Publishable key (starts with
wh_pk_): safe to put in your page code. It can only search campaigns, and only from your registered website domains.
Your registered domain is the one from the website address (https) you gave when you applied. Waithero registers it when it approves you. To show cards on another domain, ask Waithero to add it.
2. Add the loader script
Add this tag once on every page that shows cards. It defines the <waithero-campaign> element.
<script src="https://embed.waithero.com/v1/loader.js" async></script>
3. Search campaigns
Call POST /client/campaigns/search, the same request as in Fetch campaigns. From the browser, send the publishable key. From your server, send the secret key. Both go in the x-api-key header. For embed accounts the location and categoryName are optional, but without a location you only get campaigns that don't target a specific area.
For product cards, also send price, currency, imageUrl and url for each product. The card shows them, and its button opens url.
curl -X POST "https://adv.api.waithero.com/api/v1/client/campaigns/search" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_SECRET_API_KEY" \
-d '{"address":"Milano","products":[{"referenceId":"sku-42","productName":"Margherita","categoryName":"Pizza","price":8.5,"currency":"EUR","imageUrl":"https://yoursite.com/img/42.jpg","url":"https://yoursite.com/p/42"}]}'Each campaign in the response has an embed object with the token for its card: embed.token for a HOMEPAGE campaign, or embed.products[].token for SUGGESTION and HIGHLIGHT campaigns (one per matched product). Tokens expire after 7 days, so search on each page view and use them right away.
{
"campaigns": [
{
"id": 12,
"type": "HOMEPAGE",
"embed": { "token": "HOMEPAGE_TOKEN" }
},
{
"id": 42,
"type": "HIGHLIGHT",
"embed": {
"products": [{ "referenceId": "sku-42", "token": "PRODUCT_TOKEN" }]
}
}
]
}4. Show the cards
Create one <waithero-campaign> element per token, with the token in its token attribute. This complete page searches from the browser and shows up to two cards. If the search fails or finds nothing, the page shows no cards and nothing breaks.
<script src="https://embed.waithero.com/v1/loader.js" async></script>
<div id="waithero-campaigns"></div>
<script type="module">
async function searchCampaigns() {
try {
const res = await fetch("https://adv.api.waithero.com/api/v1/client/campaigns/search", {
method: "POST",
headers: { "Content-Type": "application/json", "x-api-key": "wh_pk_YOUR_KEY" },
body: JSON.stringify({
address: "Milano",
products: [{
referenceId: "sku-42", productName: "Margherita", categoryName: "Pizza",
price: 8.5, currency: "EUR",
imageUrl: "https://yoursite.com/img/42.jpg", url: "https://yoursite.com/p/42"
}]
})
});
if (!res.ok) return [];
const { campaigns = [] } = await res.json();
return campaigns;
} catch {
return [];
}
}
const campaigns = await searchCampaigns();
const tokens = campaigns.flatMap((campaign) =>
campaign.embed?.token
? [campaign.embed.token]
: (campaign.embed?.products ?? []).map((product) => product.token)
);
const container = document.getElementById("waithero-campaigns");
for (const token of tokens.slice(0, 2)) {
const card = document.createElement("waithero-campaign");
card.setAttribute("token", token);
container.append(card);
}
</script>If you search from your server, write the element straight into your HTML:
<waithero-campaign token="TOKEN_FROM_SEARCH"></waithero-campaign>
In React, Vue or Angular, render the same tag with a token attribute. Vue and Angular need to be told it is a custom element.
5. Match your site's style
All attributes are optional, and an invalid value falls back to the default. The card always keeps its text readable and its Sponsored label visible.
| Attribute | Values | Default |
|---|---|---|
layout | card, or compact: a 120 px strip (a banner for HOMEPAGE campaigns, a row for products). | card |
theme | light, dark or auto (follows the visitor's system setting when you set no colours). | light |
lang | it or en. | it |
nav | top: the product card's button opens url. event: the card fires a waithero-click event instead; call preventDefault() on it to navigate inside your app. | top |
fit | cover: the image is cropped to fill its space. contain: the whole image is shown, and the empty sides show a blurred copy of it. Useful for product photos on a plain background, such as a bottle or a jar. | cover |
bg, text, accent | Hex colours, for example #1f6f50. | From the theme |
muted, border, accent-text | Hex colours, optional. | Derived from the other colours |
radius | Corner radius, 0 to 24 (px). | 12 |
font | One of: system, serif, inter, roboto, open-sans, lato, montserrat, poppins, nunito, playfair-display | system |
font-size | 13 to 16 (px). | 14 |
padding | 8 to 16 (px). | 12 |
height | Height of the card in px. | 340 (card) or 120 (compact) |
<waithero-campaign token="TOKEN_FROM_SEARCH" layout="compact" lang="en" bg="#fff8ee" text="#3b2a1a" accent="#1f6f50" radius="16" font="inter"></waithero-campaign>
6. Test and troubleshoot
- Testing: on
http://localhostorhttp://127.0.0.1, cards show a TEST badge and nothing is counted or charged. Localhost doesn't need to be registered. - No card? Open the browser console. The loader explains why, for example the page's domain isn't registered, the token expired or the campaign ended.
- Keep the card visible: don't hide, cover or shrink it, and don't cover its Sponsored label. Don't put the card or any of its parents under an
opacitybelow 1, a CSSfilter, or atransformother than a translate. Otherwise views don't count. - No events to send: Waithero counts views and clicks from the card itself.
- Content Security Policy: if your site has one, allow
https://embed.waithero.cominframe-srcandscript-src, and the API host inconnect-srcif you search from the browser.
Restaurant categories
GET /restaurant-categories. Keep each category id: you need it for restaurantCategoryIds.
| Field | Type | Required | Description |
|---|---|---|---|
| search | string | No | Matches inside the name. |
| language | string | No | Language code, for example it or en. |
| page | integer | No | From 1. Default 1. |
| limit | integer | No | From 1 to 50. Default 20. |
curl "https://adv.api.waithero.com/api/v1/restaurant-categories?search=pizza&language=it"
Try GET /restaurant-categories
Fetch campaigns
POST /client/campaigns/search. Only location is required: an address, or areaLat and areaLon. Without products you only get HOMEPAGE campaigns.
| Field | Type | Required | Description |
|---|---|---|---|
| restaurantCategoryIds | integer[] | No | Category IDs, or send names instead. |
| restaurantCategoryNames | string[] | No | Category names, for example Pizza. |
| address | string | No | Address typed as text. |
| areaLat / areaLon | number | No | Coordinates: send both. |
| products | Product[] | No | productName and categoryName are required on the product. referenceId optional. |
Each campaign gives you id, type (HOMEPAGE, SUGGESTION, HIGHLIGHT), advisor, promotedProduct, homepage, and matchedProductReferenceIds.
curl -X POST "https://adv.api.waithero.com/api/v1/client/campaigns/search" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"address":"Milano","restaurantCategoryNames":["Pizza"],"products":[{"referenceId":"sku-123","productName":"Margherita","categoryName":"Pizza"}]}'Try POST /client/campaigns/search
Enter your API key at the top of the page to try this request.
VIEW and CLICK events
POST /events with idAdCampaign and an eventType of VIEW or CLICK. If you showed more than one, send them together with POST /events/batch.
| Field | Type | Required | Description |
|---|---|---|---|
| idAdCampaign | integer | Yes | The id search gave you. |
| eventType | VIEW | CLICK | Yes | The event you are recording. |
| idUser | integer | No | End-user id, if you want attribution. |
The response tells you how much was charged (amount) and what is left (remainingBudget). The batch returns a results[] with ok or error for each campaign.
Using embed cards? Don't send events. Waithero records them from the card, and the events endpoints answer 403 for embed accounts.
curl -X POST "https://adv.api.waithero.com/api/v1/events" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "idAdCampaign": 42, "eventType": "VIEW" }'Full example
const BASE = "https://adv.api.waithero.com/api/v1";
const headers = { "Content-Type": "application/json", "x-api-key": process.env.CAMPAIGNS_API_KEY };
const categories = await fetch(`${BASE}/restaurant-categories?search=pizza`, { headers }).then((r) => r.json());
const { campaigns } = await fetch(`${BASE}/client/campaigns/search`, {
method: "POST", headers,
body: JSON.stringify({
restaurantCategoryIds: categories.data.map((c) => c.id),
areaLat: 45.4642, areaLon: 9.19,
products: [{ referenceId: "sku-123", productName: "Margherita", categoryName: "Pizza" }]
})
}).then((r) => r.json());
for (const campaign of campaigns) {
await fetch(`${BASE}/events`, { method: "POST", headers, body: JSON.stringify({ idAdCampaign: campaign.id, eventType: "VIEW" }) });
}Errors and budget
Every event takes costPerView or costPerClick out of the budget. When the budget runs out, the campaign closes and drops out of searches.
| Status | Meaning |
|---|---|
| 400 | Campaign inactive, outside its dates, or invalid event. |
| 401 | Missing or invalid API key. |
| 402 | Budget is gone. |
| 403 | Not allowed: for example a publishable key used from an unregistered domain, or events sent by an account that uses embed cards. |
| 404 | Campaign not found. |