x.com/ Docs

REST API

Base URL: https://x-com.lovable.app/api/public

Every request must include a bearer token:

Authorization: Bearer sk_live_XXXXXXXXXXXX

POST /widget/session

Mint a short-lived session for a visitor. Called by the embedded widget.

{
  "token": "pk_widget_XXX",
  "visitor": { "externalId": "u_1029", "name": "Alex", "email": "alex@acme.com" }
}

Response:

{
  "sessionSecret": "wss_...",
  "channelId": "c_...",
  "expiresAt": "2026-07-14T22:14:00.000Z"
}

POST /widget/messages

Send a message on behalf of the visitor. Requires the sessionSecret above.

{
  "sessionSecret": "wss_...",
  "body": "Hi — I never received my order",
  "attachments": []
}

POST /messages

Server-to-server: post a message into any channel your token has access to.

POST /api/public/messages
{
  "channelId": "c_...",
  "body": "Refund processed — you'll see it in 3-5 days.",
  "kind": "agent"    // "agent" | "client" | "ai" | "system"
}

Rate limits

  • Widget token: 60 requests / min / IP
  • Server token: 600 requests / min / token

Errors

All error responses use the shape:

{ "error": "Origin not allowed", "code": 403 }

Webhooks

Configure a webhook URL under Integrations → Webhooks to receive:

  • message.created
  • channel.resolved
  • task.updated
  • invoice.finalized

Every webhook is signed with HMAC-SHA256 in the X-X-com-Signature header.