Guestly Partner API

GET /partner/me
x-api-key: gst_live_…

{
  "business": { "id": "66e42ceeb622697a6f788bb3", "name": "Hotel Alpenrose" },
  "whatsapp": { "connected": true, "phone_number": "+39 0471 123456", "display_name": "Hotel Alpenrose" },
  "key": { "id": "6ab98b77754244405c647b2e", "label": "Booking system" },
  "rate_limit_per_minute": 120
}

{
  "error": {
    "code": "OUTSIDE_24H_WINDOW",
    "message": "The guest has not written in the last 24 hours, so WhatsApp only allows an approved template.",
    "details": { "last_inbound_at": "2026-09-23T09:21:02.586Z" }
  }
}

GET /partner/templates?language=it

{
  "data": [
    {
      "name": "cloud_offer_invite",
      "language": "it",
      "category": "MARKETING",
      "header": { "format": "IMAGE", "text": null, "media_url": "https://…/hero.jpg", "media_overridable": true },
      "body": "Ciao {{1}}, la Sua offerta per il soggiorno dal {{2}} è pronta.",
      "footer": null,
      "variables": [
        { "position": 1, "name": "FIRSTNAME", "auto_filled": true, "example": "Mario" },
        { "position": 2, "name": "arrival", "auto_filled": false, "example": "12 maggio" }
      ],
      "buttons": [
        { "index": 0, "type": "URL", "text": "Apri l'offerta", "url": "https://www.cloudoffer.it/{{1}}", "dynamic": true }
      ]
    }
  ]
}

POST /partner/messages

"to": { "contact_id": "65f1c0b8a2e3f4c5d6e7f8a9" }

"to": { "phone": "+393331234567", "name": "Mario", "surname": "Rossi", "email": "[email protected]", "language": "it" }

{
  "to": { "phone": "+393331234567", "name": "Mario" },
  "type": "template",
  "template": {
    "name": "cloud_offer_invite",
    "language": "it",
    "variables": {
      "body": ["Mario", "12 maggio"],
      "header_media_url": "https://cdn.example.com/offers/abc123.jpg",
      "buttons": ["abc123"]
    }
  }
}

{
  "to": { "contact_id": "65f1c0b8a2e3f4c5d6e7f8a9" },
  "type": "text",
  "text": "Hi Mario, your offer is ready — let me know if you have any questions!"
}

{
  "to": { "contact_id": "65f1c0b8a2e3f4c5d6e7f8a9" },
  "type": "document",
  "media": { "url": "https://cdn.example.com/invoices/2026-0142.pdf", "filename": "Invoice 2026-0142.pdf", "caption": "Your invoice" }
}

curl -X POST https://api.guestly.ai/api/v1/partner/messages \
  -H "x-api-key: $GUESTLY_KEY" \
  -F "to[contact_id]=65f1c0b8a2e3f4c5d6e7f8a9" \
  -F "type=image" \
  -F "media[caption]=Your room is ready" \
  -F "[email protected]"

{
  "data": {
    "id": "6ab98bb73f66ba571c7380fa",
    "message_id": "wamid.HBgMMzkz…",
    "room_id": "69134ad2f633ce7c42606a54",
    "contact": { "id": "65f1c0b8a2e3f4c5d6e7f8a9", "phone": "+393331234567", "name": "Mario Rossi" },
    "direction": "outbound",
    "sent_by": "api",
    "sender_name": "Booking system",
    "type": "template",
    "text": "Ciao Mario, la Sua offerta per il soggiorno dal 12 maggio è pronta.",
    "status": "sent",
    "created_at": "2026-09-28T10:14:03.000Z"
  }
}

GET /partner/rooms?status=open&updated_since=2026-09-27T00:00:00Z&page=1&limit=20

{
  "data": [
    {
      "id": "69134ad2f633ce7c42606a54",
      "status": "open",
      "contact": { "id": "65f1…", "phone": "+393331234567", "name": "Mario", "surname": "Rossi", "email": null, "language": "it" },
      "last_message_at": "2026-09-23T09:21:53.948Z",
      "last_message_by": "guest",
      "last_message_preview": "Do you have a room for two next weekend?",
      "unread_count": 1,
      "window": { "open": true, "expires_at": "2026-09-24T09:21:02.586Z" }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "has_more": false }
}

GET /partner/rooms/{room_id}/messages?limit=50
GET /partner/rooms/{room_id}/messages?before={message id}   older page
GET /partner/rooms/{room_id}/messages?after={message id}    newer messages, oldest first

{ "data": [ { …message… } ], "has_more": true, "order": "newest_first" }

POST https://your-server.example.com/guestly
Content-Type: application/json
X-Guestly-Event: message.created
X-Guestly-Delivery: evt_qGlH_spKIgkHAapr
X-Guestly-Signature: t=1790545000,v1=5f2b…

{
  "id": "evt_qGlH_spKIgkHAapr",
  "event": "message.created",
  "created_at": "2026-09-28T10:14:03.512Z",
  "business_id": "66e42ceeb622697a6f788bb3",
  "data": { …message object (section 9)… }
}

const crypto = require('crypto');

function verifyGuestly(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const given = Buffer.from(String(parts.v1 || ''));
  return fresh && given.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), given);
}

import hashlib, hmac, time

def verify_guestly(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < 300
    return fresh and hmac.compare_digest(expected, parts["v1"])