Create a conversation stream token

Request

Realtime streaming of conversation events uses Server-Sent Events (SSE). It is an opt-in feature, enabled per workspace. Contact Intercom to turn it on.

Issue a token that a contact's client uses to subscribe to a realtime stream of that contact's conversation events.

Tokens are short-lived, so call this endpoint again before expires_at to get a fresh one. Use the revoke link in the response to end every active token for the contact.

Requires the read_conversations permission.

Security

bearerAuth

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:2.17

Bodyapplication/json

external_idstringrequired

The external ID of the contact to issue a token for.

Example:"contact-1234"

curl -i -X POST \
  https://api.intercom.io/conversations/stream/token \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "external_id": "contact-1234"
  }'

Responses

Token issued

Bodyapplication/json

typestring

String representing the object's type. Always has the value conversation_stream_token.

Value:"conversation_stream_token"

Example:"conversation_stream_token"

expires_atinteger, (date-time)

The time the token expires, as a UNIX timestamp.

Example:1731241200

streamobject

What the client needs to connect to the stream.

linksobject

The requests you can make with this token.

Response

{
  "type": "conversation_stream_token",
  "expires_at": 1731241200,
  "stream": {
    "provider": "ably",
    "url": "main.realtime.ably.net",
    "channel": "conversation_stream:abc123:6710a1b2c3d4e5f6a7b8c9d0",
    "token": "<stream token>"
  },
  "links": {
    "self": { … },
    "revoke": { … }
  }
}