Guestly Partner API

Overview

1. Before you begin

On the hotel's side:

1. The hotel is onboarded on Guestly and has connected its WhatsApp Business number.
2. Guestly activates API access for the hotel and sends you your key. The key is shown once; keep it on your server, never in a browser or app. If a key leaks, ask Guestly to revoke it; it stops working within a minute.
3. To send templates, the hotel has at least one template approved by WhatsApp (you can list them with the API, see section 4).
4. For real-time sync, send Guestly your webhook URL. We set it up and send you the signing secret (section 10).

Check a key with:

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_limits": {
    "all_endpoints": { "per_minute": 120, "per_day": null },
    "send_message": { "per_second": 3, "per_day": null },
    "send_template": { "per_second": 1, "per_day": 250 },
    "list_templates": { "per_second": 5, "per_day": null }
  }
}

2. Errors and rate limits

Every error has the same shape:

{
  "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" }
  }
}

Rate limits. Limits are per hotel: all keys of one hotel share them. Defaults:

GET /partner/me returns the hotel's current limits (null = no limit). Ask Guestly if you need different ones.

• Windows are fixed: each second, minute or UTC day starts a new count. Days reset at 00:00 UTC.
• A request rejected with 429 doesn't count toward the limit that rejected it. A send that fails (any error response) doesn't count toward its daily limit.
• Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for the per-minute limit. Sends with a daily limit also carry X-RateLimit-Daily-Limit and X-RateLimit-Daily-Remaining.
• A 429 carries Retry-After (seconds) and error.details, for example { "limit": "send_template", "window": "day", "max": 250, "retry_after": 7201 }.

WhatsApp also limits how many new conversations a hotel can open per day (its messaging tier). A send over that limit returns 422 WHATSAPP_ERROR with meta_code: 131048.

3. Concepts

• Contact: a guest of the hotel, identified by id. You can always address a guest by phone number instead; Guestly finds the existing contact or creates one (you can pass name, surname, email, language). Existing data is never overwritten — only empty fields are filled.
• Room: the one WhatsApp conversation between the hotel and a contact.
• 24-hour window: WhatsApp allows free-form messages (text, media) only within 24 hours of the guest's last message. Outside it, only approved templates can be sent. Rooms report window.open and window.expires_at.
• Phone numbers: send +39 333 123 4567, 0039… or, for guests in the hotel's own country, the national number. Responses use E.164 (+393331234567).

4. List templates

GET /partner/templates?language=it

language (en, it, de) is optional. Only templates approved by WhatsApp are returned.

{
  "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, "auto_filled": false }
      ]
    }
  ]
}

• variables are the body placeholders {{1}}, {{2}}, … in order.
• auto_filled: true means Guestly can fill the value from its own contact or booking data (first name, last name, title, check-in/out dates, nights, guests, room, booking number, pre-check-in link). You can still pass your own value, and should if the hotel's bookings aren't in Guestly.
• example is the sample the hotel entered when creating the template. It is never sent in place of a missing value.
• dynamic: true buttons need a value for the {{1}} in their URL (for example an offer id), unless auto_filled is true (Guestly fills it, for example with the guest's GuestNet login link). A missing value returns 400 MISSING_TEMPLATE_VARIABLE; the template's sample URL is never sent.

5. Send a message

POST /partner/messages

Every message has a recipient to and a type: text, image, video, document or template.

Recipient

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

or

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

5.1 Template (works any time)

{
  "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"]
    }
  }
}

5.2 Text (within the 24-hour window)

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

5.3 Image, video or document (within the 24-hour window)

By URL:

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

Or upload the file with multipart/form-data:

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]"

Response (201)

The sent message, in the same shape as everywhere else (section 9):

{
  "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"
  }
}

status: "sent" means WhatsApp accepted the message. Delivery and read receipts follow as message.status webhooks (section 10). Store data.id and data.contact.id: you can address the guest by contact_id from then on, and the same id appears in webhooks.

6. Message format rules

• Formatting uses WhatsApp's own syntax, not Markdown or HTML: *bold*, _italic_, ~strikethrough~, ```monospace```, `inline code`, lists starting with - or 1. , and quotes starting with > .
• Links are sent as plain URLs; WhatsApp shows a preview.
• Media URLs must be publicly reachable (no login, no expiring signature shorter than a few minutes). WhatsApp downloads the file when the message is sent.
• Templates: the text is fixed by the approved template; only variables, header media and dynamic button values change per send. New templates are created and submitted for approval in Guestly (Template Studio).

7. List conversations (rooms)

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 }
}

8. List messages in a room

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" }

Use before with the oldest id you have to page back through history, and after with the newest id to catch up after downtime.

9. The message object

10. Webhooks

Send Guestly your HTTPS endpoint. We set it up, send it a test ping and share the signing secret (whsec_…) with you. A webhook needs an active API key for the hotel; revoking the hotel's last key turns the webhook off.

Guestly then POSTs every event to that one URL:

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)… }
}

Verify the signature

v1 is the HMAC-SHA256 of "{t}.{raw request body}" with the signing secret. Reject requests whose signature doesn't match or whose t is more than 5 minutes old.

Node.js:

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);
}

Python:

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"])

Delivery

• Answer with any 2xx within 5 seconds, then process the event asynchronously.
• Anything else (or a timeout) is retried after 30 s, 2 min, 10 min, then every 15 min — for about 6 hours in total.
• Delivery is at least once: deduplicate on the event id (or the message id).
• Events can arrive out of order: sort by created_at, and treat message.status as "latest wins". If you ever miss events, catch up with GET /partner/rooms/{id}/messages?after=….

11. Quick reference

All paths are relative to https://api.guestly.ai/api/v1.

Support

For test keys on our test environment, template design or higher limits, contact the Guestly integrations team.