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.
Your app → Your backend → https://api.gleap.io/v3/s2s/…
api.gleap.io is the API host of the EU data region. Projects in the US region use https://api.us.gleap.ai instead — see Data regions.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
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.
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 sameuserId.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
Authentication — create your token (2 minutes, self-serve).
Quickstart — the full conversation loop in six requests.
Realtime stream — the recommended event channel; Webhooks & events covers the catalog, envelope and signatures.