This page is for the developer of a business that runs its own booking system. Once connected, bookings taken by the Blinkerbot assistant (WhatsApp, Instagram, web chat, phone) are created in your system as real appointments in the customer's name.
How it works
- Blinkerbot sends signed
POSTrequests to one address on your system. The operation is named in the body. - Your system is the source of truth. The record in Blinkerbot is only a mirror.
- You never call us. Nobody copies a secret by hand: the business owner pastes the pairing code from the panel into your setup screen, and the signing secret is set up between the two systems automatically.
- If your system can't answer, no customer is lost: the request waits, is processed when the system is back, and the customer is told the result.
Step by step
The business owner works in the panel, the developer on their own server. There are two ways in; both pass the same automatic test.
Before you start (business owner):
- In the panel open Settings > Bookings > My own system. If it says the feature isn't available for your workspace, write to us and we switch it on for your account.
- Every important step on this screen (creating a code, saving the address, turning the connection on) asks for a two-factor (2FA) code. If 2FA isn't on yet, enable it under Account > Security first. For safety, the screen stays locked for 24 hours after 2FA or the password was changed.
Path A: pairing code (when you use the package or the examples — recommended):
- The owner clicks Create pairing code and enters the 2FA code. The code starts with
blk_pair_, is valid for 2 hours and works once. The owner passes it to the developer. - The developer runs the package's pair command with it (e.g.
php blinkerbot-endpoint.php pair blk_pair_XXXX --url https://www.yoursite.com/blinkerbot-endpoint.php). The package tells us your endpoint address, receives the signing secret and writes it to the secret file outside the web root. The secret never appears on any screen. - If the code expired or was mistyped, just create a new one; for security the error message is the same in every case.
Path B: manual setup (when you implemented the contract yourself):
- In Manual setup the owner enters the endpoint address (
https://, port 443). The signing secret field comes pre-filled with a randomwhsec_…value; Generate new replaces it. If your system already has a secret, you can type that instead (whsec_+ at least 24 bytes of base64). - The owner clicks Save address and secret and enters the 2FA code. The secret is shown once: copy it straight into your system's settings; never send it by e-mail or chat.
- The developer uses that same secret to verify signatures (see Signing below).
Final steps (both paths):
- The Automatic test runs by itself (or Test again). Each step shows pass/fail and why; the steps are listed under Automatic test.
- Once it passes your services appear. Match your services: match each one to a Blinkerbot service or add it to Blinkerbot. The assistant doesn't book services that aren't matched. If your
list_servicesanswer includes a staff list, the assistant lets the customer pick a staff member and sendsstaff_id. - Write bookings to my own system > Turn on (2FA). It needs a passed test and at least one matched service. While on, Google and Microsoft calendars are no longer the booking source.
- If your system can't answer for a moment, requests wait under Requests awaiting confirmation; they are processed when the system is back and the customer is told the result. The owner can switch the connection off, change the address or rotate the secret from the same screen.
Fastest path: the ready-made PHP package
One file, no dependencies (no Composer), PHP 7.4–8.3, PDO (MySQL/MariaDB InnoDB or SQLite). The package ships signature verification, pairing-code setup, ping, duplicate protection, error codes, test requests and rescheduling. You only write 4 small functions that read and write your own tables:
listServices(): services (id, name, duration; optional price and staff list)findSlots($q): free times for a service (and optional staff member)createBooking($pdo, $b): writes the booking inside the given$pdotransactioncancelBooking($pdo, $id): cancels (already cancelled is still a success)- optional
getBooking($id)
Expected effort: 6–20 hours. Download: blinkerbot-booking.php · example config · package README
Setup steps:
- Put
blinkerbot-booking.phpon your server, copy the example config and enter your database details. Keep the secret file outside the web root. - Create the endpoint file (e.g.
blinkerbot-endpoint.php) and write the 4 functions. - The business owner clicks Settings > Bookings > My own system > Create pairing code in the panel (valid 2 hours, single use). Enter it on the server (as the web server user):
php blinkerbot-endpoint.php pair blk_pair_XXXX --url https://www.yoursite.com/blinkerbot-endpoint.php - The panel runs the automatic test. Once it's green, the owner matches services and turns the connection on.
Examples with the same 4-function layout: Node example · Python example
With your AI assistant
Paste the ready-made prompt into ChatGPT or Claude and describe your tables; it writes the 4 functions for you. Broken code never reaches customers: the connection can't be turned on until the panel test passes. For AI tools: llms.txt.
Contract
Every request is POST {your address} with a JSON body: operation, request_id, idempotency_key, account, test, data.
ping: connection and signature check (answered by the package). If you can reschedule in one request, announcecapabilities: ["replaces_booking_id"].list_services: services. Required.find_slots:service_id, optionalstaff_id,from,to,timezone,limit(1–500; earliest free times). Required.create_booking:service_id, optionalstaff_id,start,end,timezone,customer(name, phone, optional email),channel, optionalnoteandreplaces_booking_id.idempotency_keyis mandatory. Required.get_booking,cancel_booking: recommended. If you don't implement one, answer HTTP 200 with{"ok":false,"error":{"code":"not_implemented"}}— never a 5xx.
Response rules:
- Success: HTTP 200,
{"ok": true, "data": …} - Business error: HTTP 200,
{"ok": false, "error": {"code": "…"}}. Codes:slot_unavailable,invalid_service,invalid_staff,outside_hours,invalid_customer,booking_not_found,cancellation_not_allowed,idempotency_mismatch,request_in_progress. - Signature error: HTTP 401.
- Timeouts, 5xx, 429, non-JSON answers and HTML pages count as "unreachable"; the request is held and retried.
Times are ISO 8601 with offset: 2026-11-20T14:00:00+03:00. Your error message never reaches the assistant; it is only stored, clipped, in the owner's call log. For health businesses (clinics, dental, health centres) the customer note is never sent.
Full details: OpenAPI definition · Postman collection
Duplicate protection
- If the same
idempotency_keyarrives again, don't create a new booking; return the first answer. - If the same key arrives with different content, return
idempotency_mismatch. - Write the key in the same database transaction as the booking and keep it for at least 7 days.
- We resend a create request whose answer never reached us with the same key; it must not create a duplicate.
Signature (Standard Webhooks)
Every request is signed per Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature (v1,<base64>). The signed content is webhook-id.webhook-timestamp.raw_body; the key is the base64-decoded bytes after the whsec_ prefix. Check the timestamp with a 5-minute tolerance, compare in constant time, and don't modify the body before verifying. During a secret renewal two space-separated signatures arrive; either one matching is valid.
$id = $_SERVER['HTTP_WEBHOOK_ID']; $ts = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body = file_get_contents('php://input');
$key = base64_decode(substr($secret, strlen('whsec_')));
$expected = 'v1,' . base64_encode(hash_hmac('sha256', "$id.$ts.$body", $key, true));
$valid = abs(time() - (int) $ts) <= 300 && in_array(true, array_map(fn($s) => hash_equals($expected, $s), explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])), true);Libraries: Node npm install standardwebhooks, Python pip install standardwebhooks, PHP 8 composer require standard-webhooks/standard-webhooks.
Time limits
- Phone: free times 2.5 s; create, cancel and lookup 3.5 s.
- Chat: free times 5 s; create, cancel and lookup 8 s.
- Service list and ping: 5 s.
- Answers can be at most 64 KB. Redirects are not followed.
Automatic test
After connecting, the panel tries: ping; signature checking (a wrong signature, a 10-minute-old timestamp and a request signed with another secret must all get 401); service list; 7 days of free times; a test booking with test: true (must not be saved); the same booking for the same key; idempotency_mismatch for different content; lookup and cancel if present; speed for phone.
Troubleshooting
- Firewall blocks (403): Cloudflare Bot Fight Mode, Wordfence or ModSecurity may block the requests. Add an exception for this address. We don't publish our egress IP; contact us if you need it.
- HTML with a 200: a cache plugin, maintenance mode or a login redirect is in the way. Exclude the address from caching.
- Signature fails (401): the body is re-encoded before verification or the server clock drifted. Use the raw body and enable NTP.
- Times are off: make sure you include the offset (
+03:00);+0300is accepted, a local time without offset is not. - Too slow: cheap hosting can cold-start PHP. While connected we send a ping every 5 minutes.
- Redirects: if there is an
http→httpsorwwwredirect, enter the final address.
Local development
To receive our requests on your own machine, use a tunnel: Cloudflare Tunnel or ngrok. Use the tunnel's https:// address when pairing; pair again with the real address when you're done.
Security
- Never put the secret in code, version control or chat; keep it in a file outside the web root with
0600permissions. - Verify the signature on every request; answer 401 when it fails.
- Only
httpson port 443 is accepted. Internal network addresses are rejected. - If you suspect a leak, the business owner can turn the connection off in one click and renew the secret.
For CRM automations, see the public API and signed webhooks. All developer guides.