Acties: antwoorden uit je eigen systeem

Met een actie kan je bot midden in een chat iets opzoeken in je eigen systeem — waar een bestelling is, wanneer die wordt geleverd, of een boeking bevestigd is. De klant vraagt, de bot verzamelt wat hij nodig heeft, roept je API aan en antwoordt op basis van wat terugkomt, in de taal van de klant.

Het werkt overal waar je bot werkt: de website-widget, je bot-link en QR-code, en de Android-, iOS-, React Native-, Flutter- en Ionic-apps. Er wordt niets geïnstalleerd of bijgewerkt — de aanroep gebeurt vanaf onze servers, dus je API-gegevens bereiken nooit een browser of telefoon.

Voordat je begint: iedereen kan met je bot chatten

Je bot is een openbare chat. Als een bestelnummer alleen genoeg is om een bestelling te zien, kan iedereen nummers typen tot er een werkt.

De bot helpt op drie manieren, maar geen daarvan vervangt die controle: hij stuurt alleen waarden die de klant echt heeft getypt, hij beperkt hoeveel opvragingen één chat of één adres kan doen, en je kunt kiezen welke velden van het antwoord hij mag zien.

Een actie instellen

Open Acties in het dashboard en kies Nieuwe actie. Eigenaren en beheerders kunnen dit scherm zien.

• Naam — voor jezelf, zoals "Bestelstatus".
• Wanneer moet de bot dit gebruiken? — één zin, zoals je het aan een nieuwe collega zou vertellen: "De klant vraagt waar zijn bestelling is of wanneer die aankomt."
• Je API-adres — GET of POST, en een https://-adres. Schrijf {{order_id}} op de plek van een waarde.
• Waar de bot de klant om vraagt — maximaal zes waarden. Elke waarde heeft een label in je eigen woorden ("Bestelnummer"), de naam die je API gebruikt (order_id) en een type: vrije tekst, een getal, een e-mailadres of een telefoonnummer.
• Headers — je API-sleutel of token. Versleuteld opgeslagen en nooit meer getoond.
• Deel alleen deze velden met de bot — optioneel. Noem de delen van het antwoord die de bot mag gebruiken, zoals status, eta, items[].name. Al het andere wordt weggelaten voordat de AI het ziet.

Druk op Testen, typ voorbeeldwaarden, en je ziet het verstuurde verzoek en precies wat de bot zou krijgen. Probeer het daarna echt op het scherm Test: "Waar is mijn bestelling 48213? Mijn e-mailadres is asha@example.com".

Wat je API ontvangt

Bij GET worden de waarden die je in het adres hebt gezet ingevuld en de rest wordt aan de query string toegevoegd:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

Bij POST vormen de waarden de JSON-body:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

Elk verzoek bevat ook je eigen headers en deze:

Wat je terugstuurt

Antwoord binnen 8 seconden met JSON, of een korte regel platte tekst.

• 200 met de gegevens — de bot antwoordt daaruit. Houd het klein en gebruik duidelijke veldnamen: {"status":"shipped","eta":"2 October"} werkt beter dan interne codes.
• 404 als er niets overeenkomt — de bot vertelt het de klant en vraagt om te controleren wat er is getypt.
• Iets anders, of geen antwoord op tijd — de bot biedt zijn excuses aan, geeft je contactgegevens en de chat wordt voor je gemarkeerd. De reden zie je op het scherm Acties.

Redirects worden niet gevolgd, en een antwoord groter dan 256 KB wordt niet gelezen.

De handtekening controleren

Verzoeken worden ondertekend volgens Standard Webhooks, dus je kunt een bestaande library gebruiken. Je ondertekeningssleutel staat op het scherm Acties.

Handmatig: plak de id, de timestamp en de exacte body met punten aan elkaar, onderteken dat met HMAC-SHA256 met de sleutel (het deel na whsec_, base64-gedecodeerd), en vergelijk.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

Bij een GET-verzoek is de body leeg, dus de ondertekende tekst eindigt met een punt. Gebruik POST als je wilt dat de waarden zelf ook onder de handtekening vallen.

Hoe de bot het gebruikt

• Hij vraagt om alles wat ontbreekt, één korte vraag tegelijk, en onthoudt wat de klant eerder in de chat heeft gezegd.
• Hij gokt nooit een waarde. Als de klant het niet heeft getypt, vraagt de bot ernaar.
• Eén opvraging per bericht. Je opgeslagen antwoorden gaan nog steeds voor, dus een vraag die je zelf hebt beantwoord roept je API nooit aan.
• Antwoorden uit een opvraging worden nooit hergebruikt voor een andere klant.
• Een opvraging telt als één antwoord, net als elk ander antwoord dat de AI schrijft.

In Chats staat onder een antwoord dat uit een opvraging kwam welke actie is uitgevoerd en hoe die afliep. De waarden die de klant heeft getypt blijven in het transcript en nergens anders.

Limieten

Acties lezen informatie. Richt er geen op een adres dat iets verandert — een bestelling annuleren of een terugbetaling doen vereist een bevestigingsstap die de bot nog niet heeft.