Skip to main content
The Server-to-Server (S2S) Conversations API gives your backend headless access to Gleap conversations: create and read conversations, send messages as your end customer, drive bot workflows, upload files, and receive every change as an event — without the Gleap SDK or widget in your app.
It is an access layer, not a separate product: a conversation your backend opens is indistinguishable from one opened through the widget. The same inbox, the same agents, the same workflows, AI agents, routing rules and reporting apply — your support team changes nothing.

​
The two planes

REST

Contacts, conversations, messages, workflows and uploads. Everything you write here is authored as the end customer — the key difference from the admin REST API, which always acts as a teammate.

Events

A single Pusher-protocol realtime stream per backend instance (recommended) and/or HMAC-signed webhooks. Same event types, same envelope on both.

​
Core concepts

  • Contacts are addressed by your user identifier — /v3/s2s/contacts/{userId} — with no session handshake and no identity-verification hashing. Contacts deduplicate against SDK-created contacts on the same userId.
  • Conversation and message ids are opaque (cnv_…, msg_…). Treat them as strings.
  • Event payloads are authoritative for the conversation they carry; order and dedupe events by (conversation id, sequence).
  • Recovery is per-conversation catch-up, the same model the Gleap widget uses: re-pull a contact’s conversation list and each conversation’s messages (?after=<last id you have>) whenever your app opens the support screen or your consumer suspects a gap.

​
Start here

  1. Authentication — create your token (2 minutes, self-serve).
  2. Quickstart — the full conversation loop in six requests.
  3. Realtime stream — the recommended event channel; Webhooks & events covers the catalog, envelope and signatures.