RTM API Reference (V1)

Updated on September 21, 2021

Events are sent on the RTM Events API WebSocket channel that you can open alongside your REST API channel, which allows you to receive asynchronous replies and events for some of your actions via the REST API.

Endpoint

You may subscribe to events by opening a Socket.IO connection to the WebSocket endpoint.

The RTM API endpoint URL is: wss://app.relay.crisp.chat/

There is a limit on the maximum number of connections that can be simultaneously open with the RTM API (per-token, per-website and per-IP). This limit is quite high and can be revised at any time. Please make sure to teardown any unused connection before opening a new one. Most use cases require a single RTM API connection.

Namespaces

Available RTM event namespaces are listed below. Make sure to subscribe to the ones you need to receive in the RTM authentication request, otherwise you won't receive them. Read our guides on how to do that.

Note that if your API token is a plugin tier token, then you will only have access to the RTM events that your token scopes allow, based on the API routes that you have access to. Required scopes and tiers are listed for each event below.

Session Events

  • session:update_availability

    • Description: session availability changed (eg. online to offline)
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:update_verify

    • Description: session verification status changed
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:request:initiated

    • Description: session has been initiated (conversation started)
    • Tiers: user plugin
    • Scopes: website:conversation:initiate + write
  • session:set_email

    • Description: email has been set for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:set_phone

    • Description: phone has been set for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:set_address

    • Description: address has been set for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:set_avatar

    • Description: avatar has been set for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:set_nickname

    • Description: nickname has been set for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:set_data

    • Description: user data has been set for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:sync:pages

    • Description: a page was just browsed by user on session
    • Tiers: user plugin
    • Scopes: website:conversation:pages + read
  • session:sync:events

    • Description: a live event was just pushed from user on session
    • Tiers: user plugin
    • Scopes: website:conversation:events + read
  • session:sync:capabilities

    • Description: user device just advertised its capabilities on session (eg. browser support fo**r **calls)
    • Tiers: user plugin
    • Scopes: website:conversation:sessions
  • session:sync:geolocation

    • Description: current geolocation was just pushed for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:sync:system

    • Description: current device system was just pushed for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:sync:network

    • Description: current device network was just pushed for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:sync:timezone

    • Description: current device timezone was just pushed for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:sync:locales

    • Description: current device locales was just pushed for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:sync:rating

    • Description: user rating was just submitted for session
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:set_state

    • Description: session state changed (eg. to resolved)
    • Tiers: user plugin
    • Scopes: website:conversation:states + read
  • session:set_block

    • Description: session was just blocked or unblocked
    • Tiers: user plugin
    • Scopes: website:conversation:actions + read
  • session:set_segments

    • Description: session segments have been added
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:set_opened

    • Description: conversation has been opened by an operator (viewed by)
    • Tiers: user plugin
    • Scopes: website:conversation:actions + read
  • session:set_closed

    • Description: conversation has been closed by a viewing operator
    • Tiers: user plugin
    • Scopes: website:conversation:actions + read
  • session:set_participants

    • Description: the list of conversation participants has been updated
    • Tiers: user plugin
    • Scopes: website:conversation:participants + read
  • session:set_mentions

    • Description: an operator mentioned another operator
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read
  • session:set_routing

    • Description: a routing identifier was set on conversation
    • Tiers: user plugin
    • Scopes: website:conversation:routing + read
  • session:removed

    • Description: session has been removed
    • Tiers: user plugin
    • Scopes: website:conversation:sessions + read

Message Events

  • message:updated

    • Description: message has been updated
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read
  • message:send

    • Description: message has been sent (from visitor)
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read
  • message:received

    • Description: message has been received (from operator)
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read
  • message:compose:send

    • Description: a message is being composed (MagicType from visitor)
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read
  • message:compose:receive

    • Description: a message is being composed (MagicType from operator)
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read
  • message:acknowledge:read:send

    • Description: messages sent by visitor were read by an operator
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read
  • message:acknowledge:read:received

    • Description: messages sent by operators were read by visitor
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read
  • message:acknowledge:delivered

    • Description: visitor client acknowledged delivery of an operator message
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read
  • message:notify:unread:send

    • Description: messages sent by visitor were not read in due time by an operator
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read
  • message:notify:unread:received

    • Description: messages sent by operators were not read in due time by visitor
    • Tiers: user plugin
    • Scopes: website:conversation:messages + read

People Events

  • people:profile:created

    • Description: a people profile was created
    • Tiers: user plugin
    • Scopes: website:people:profiles + read
  • people:profile:updated

    • Description: a people profile was updated
    • Tiers: user plugin
    • Scopes: website:people:profiles + read
  • people:profile:removed

    • Description: a people profile was removed
    • Tiers: user plugin
    • Scopes: website:people:profiles + read
  • people:bind:session

    • Description: a people profile was bound to session
    • Tiers: user plugin
    • Scopes: website:people:profiles + read
  • people:sync:profile

    • Description: a people profile was updated for session
    • Tiers: user plugin
    • Scopes: website:people:profiles + read
  • people:import:progress

    • Description: people batch import is progressing
    • Tiers: user
  • people:import:done

    • Description: people batch import is done
    • Tiers: user

Campaign Events

  • campaign:progress

    • Description: campaign sending is progressing (eg. campaign is 10% sent)
    • Tiers: user
  • campaign:dispatched

    • Description: campaign was dispatched
    • Tiers: user
  • campaign:running

    • Description: campaign is running, sending is ongoing
    • Tiers: user

Browsing Events

  • browsing:request:initiated

    • Description: magicBrowse request initiated by visitor browser
    • Tiers: user plugin
    • Scopes: website:conversation:browsing + write
  • browsing:request:rejected

    • Description: magicBrowse request rejected by visitor browser (eg. browser has privacy settings)
    • Tiers: user plugin
    • Scopes: website:conversation:browsing + write

Call Events

  • call:request:initiated

    • Description: call was initiated (accepted by user)
    • Tiers: user plugin
    • Scopes: website:conversation:calls + write
  • call:request:rejected

    • Description: call was rejected (declined by user)
    • Tiers: user plugin
    • Scopes: website:conversation:calls + write

Widget Events

  • widget:action:processed
    • Description: widget action processed result (success or failure)
    • Tiers: user

Status Events

  • status:health:changed
    • Description: status page health has changed
    • Tiers: user

Website Events

  • website:update_visitors_count

    • Description: website visitor counter changed (eg. a visitor came online)
    • Tiers: user plugin
    • Scopes: website:visitors + read
  • website:update_operators_availability

    • Description: website operator availability changed (eg. operator went online)
    • Tiers: user plugin
    • Scopes: website:operators + read
  • website:users:available

    • Description: website availability changed (eg. support went offline)
    • Tiers: user plugin
    • Scopes: website:availability + read

Bucket Events

  • bucket:url:upload:generated

    • Description: an upload URL was generated for a file upload (signed URL, usable once)
    • Tiers: user plugin
    • Scopes: bucket:url + write
  • bucket:url:avatar:generated

    • Description: an upload URL was generated for an avatar upload (signed URL, usable once)
    • Tiers: user plugin
    • Scopes: bucket:url + write
  • bucket:url:website:generated

    • Description: an upload URL was generated for a website upload (signed URL, usable once)
    • Tiers: user plugin
    • Scopes: bucket:url + write
  • bucket:url:campaign:generated

    • Description: an upload URL was generated for a campaign file upload (signed URL, usable once)
    • Tiers: user plugin
    • Scopes: bucket:url + write
  • bucket:url:helpdesk:generated

    • Description: an upload URL was generated for a helpdesk file upload (signed URL, usable once)
    • Tiers: user plugin
    • Scopes: bucket:url + write
  • bucket:url:status:generated

    • Description: an upload URL was generated for a status file upload (signed URL, usable once)
    • Tiers: user plugin
    • Scopes: bucket:url + write
  • bucket:url:processing:generated

    • Description: an upload URL was generated for a processing/import upload (signed URL, usable once)
    • Tiers: user plugin
    • Scopes: bucket:url + write

Media Events

  • media:animation:listed
    • Description: requested animation/GIF list is being returned
    • Tiers: user

Email Events

  • email:subscribe

    • Description: an user subscribed or unsubscribed to emails
    • Tiers: user plugin
    • Scopes: website:people:subscriptions + read
  • email:track:view

    • Description: an user viewed an email
    • Tiers: user plugin
    • Scopes: website:people:subscriptions + read

Plugin Events

  • plugin:channel

    • Description: generic channel for plugins
    • Tiers: user plugin
  • plugin:event

    • Description: generic event for plugins
    • Tiers: user plugin
  • plugin:settings:saved

    • Description: plugin settings saved
    • Tiers: user plugin