Skip to content

API · Webhooks · identify()

Built to plug into your product

A JavaScript API for the widget, signed identity for logged-in users, a REST API for your data and signed webhooks for everything that happens.
Install the widget
<script src="https://widget.aliendesk.io/loader.js" data-brand="YOUR_BRAND_KEY" async></script>

Control the widget from your code

Open the chat from your own button, switch its language, add events to the contact's timeline and react when a reply arrives. Calls made before the widget has loaded are queued, so you never have to wait for it.
  • open() and close()
  • identify(user)
  • track(event, properties)
  • setLocale(locale)
  • on("message" | "open" | "close" | "unread", callback)
Widget JavaScript API
// Open the chat from your own button
document.querySelector("#help").addEventListener("click", () => AlienDesk.open());

AlienDesk.close();
AlienDesk.setLocale("hi");                         // show the widget in Hindi
AlienDesk.track("checkout_started", { items: 2 }); // add an event to the contact

const stop = AlienDesk.on("message", (message) => {
  console.log("New reply", message);
});                                                // also "open", "close", "unread"

// Calls made before the widget loads are queued and replayed:
window.AlienDesk = window.AlienDesk || { q: [] };
window.AlienDesk.q.push(["identify", { userId: "u_8f2k1" }]);

Know who's chatting, for sure

Pass the logged-in user with identify() and a hash only your server can make. A valid hash marks the contact verified. Without one, the contact is stored as unverified and never trusted for actions, and a tampered hash is rejected.
  • userHash is an HMAC-SHA256 of the user ID
  • Made on your server with the brand’s identity secret
  • Verified contacts show their attributes to your team and the AI
Identity verification (Node.js)
// On your server. Never send the identity secret to the browser.
import { createHmac } from "node:crypto";

export function userHash(userId) {
  return createHmac("sha256", process.env.ALIENDESK_IDENTITY_SECRET)
    .update(String(userId))
    .digest("hex");
}

// In the page your server renders:
AlienDesk.identify({
  userId: user.id,
  email: user.email,
  name: user.name,
  attributes: { plan: user.plan, orders: user.orderCount },
  userHash: userHash(user.id),
});

A REST API for your data

Every request uses an API key sent as a Bearer token. Lists take ?cursor= and ?limit=, and IDs carry a prefix so you can tell them apart: tkt_, ctc_ and msg_.
  • Contacts, including upsert by your own ID
  • Conversations: list, get, create, reply and update status
  • Messages and tags
  • Cursor pagination with { data, nextCursor }
REST API
# List conversations, 20 at a time
curl "https://app.aliendesk.io/api/v1/conversations?limit=20" \
  -H "Authorization: Bearer ad_live_..."

# => { "data": [{ "id": "tkt_...", "status": "open", ... }], "nextCursor": "..." }
# Pass ?cursor=<nextCursor> for the next page.

# Create or update a contact by your own user ID
curl -X PUT "https://app.aliendesk.io/api/v1/contacts/by-external-id/u_8f2k1" \
  -H "Authorization: Bearer ad_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"priya@example.com","name":"Priya Sharma","attributes":{"plan":"Pro"}}'

Webhooks you can trust

Each event is a signed POST with X-AlienDesk-Event, X-AlienDesk-Delivery, X-AlienDesk-Timestamp and X-AlienDesk-Signature headers. The signature is an HMAC-SHA256 of the timestamp and body. Failed deliveries are retried with exponential backoff for up to 24 hours.
  • conversation.created
  • conversation.status_changed
  • message.created
  • contact.created
  • csat.submitted
Verify a webhook (Node.js)
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();

// Verify against the raw body, before parsing JSON
app.post("/webhooks/aliendesk", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-AlienDesk-Timestamp");
  const signature = req.get("X-AlienDesk-Signature") ?? ""; // "sha256=<hex>"
  const expected =
    "sha256=" +
    createHmac("sha256", process.env.ALIENDESK_WEBHOOK_SECRET)
      .update(`${timestamp}.${req.body}`)
      .digest("hex");

  const valid =
    signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!valid) return res.status(401).end();

  const { event, data } = JSON.parse(req.body);
  // conversation.created, conversation.status_changed, message.created,
  // contact.created, csat.submitted
  res.status(200).end();
});

Rate limits

Every REST response carries X-RateLimit headers, so your code can slow down before it hits the limit.
  • REST API: 600 requests a minute per key
  • Widget: 60 requests a minute per visitor
  • Widget: 20 new conversations an hour per visitor
Rate limit headers
HTTP/1.1 200 OK
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1792320000

# Over the limit: HTTP 429
# { "error": { "code": "rate_limited", "message": "Rate limit exceeded (600 requests per minute)" } }

The details

  • OpenAPI specGenerated from the API’s own schemas and published with the reference.
  • Cursor paginationStable paging through large lists with nextCursor.
  • Prefixed IDstkt_, ctc_ and msg_ make IDs easy to tell apart.
  • Consistent errorsEvery error is { error: { code, message } } with an HTTP status.
  • Scoped API keysKeys carry scopes, so each integration gets only what it needs.
  • Allowed domainsThe widget only runs on the domains you list for each brand.

Questions people ask

Beam it up

Put an AI agent on your website today

Billed monthly. No lock-in.