PubNub · AsyncAPI Specification

PubNub Realtime Streaming API

Version 3.0.0

AsyncAPI description of PubNub's realtime subscribe surface — the event stream that delivers messages, signals, presence updates, file events, message-action events, and App Context (object) events to subscribed clients. Transport note (important honesty disclaimer): PubNub's official public wire protocol is NOT WebSocket. The Subscribe API is delivered over HTTPS as a long-lived long-poll request against ps.pndsn.com. The SDK issues a GET subscribe request; the network either returns immediately with a batch of events (HTTP 200 with a JSON envelope) or holds the request until a long-poll expiration (~280 seconds) and returns an empty batch, after which the SDK reissues the request using the most recent timetoken. AsyncAPI is used here to model the EVENT-LEVEL contract (channels, message schemas, presence/object/message-action events) that the SDK exposes to application code via listeners. The underlying transport binding is HTTP long-poll, not WebSocket. PubNub's own documentation describes only the SDK-level listener event objects publicly; the lower-level wire envelope (t/m/e/a/f/i/p/k/c/d/b/u fields) is not formally published and is therefore not modeled in this spec to avoid fabrication. Source documentation: - https://www.pubnub.com/docs/general/setup/connection-management - https://www.pubnub.com/docs/general/presence/presence-events - https://www.pubnub.com/docs/general/metadata/basics - https://www.pubnub.com/docs/sdks/javascript/api-reference/publish-and-subscribe - https://www.pubnub.com/docs/sdks/javascript/api-reference/message-actions Authentication: publish/subscribe key pair (per keyset). Optional Access Manager auth token via the auth query parameter.

View Spec View on GitHub RealtimeWebSocketsPub/SubIoTMessagingChatPresenceFunctionsAsyncAPIWebhooksEvents

Channels

message
subscribe receiveMessage
Receive published messages on a channel.
Standard published messages delivered to all subscribers of a channel. Received by SDK listeners as a "message" event.
signal
subscribe receiveSignal
Receive signals on a channel.
Lightweight signals delivered to subscribers of a channel. Signals are capped at 64 bytes of payload and are intended for high-volume, low-latency use cases. Received by SDK listeners as a "signal" event.
presence
subscribe receivePresence
Receive presence events for a channel.
Presence events for a channel, delivered on the {channel}-pnpres companion channel. Event types include join, leave, timeout, state-change, and interval.
file
subscribe receiveFile
Receive file events on a channel.
File events delivered when a file is uploaded to a channel. Subscribers receive a file event containing the file ID, filename, and an optional description.
message-action
subscribe receiveMessageAction
Receive message action events on a channel.
Message action events delivered when a reaction or action (e.g. emoji reaction, read receipt) is added to or removed from a previously published message on a channel.
app-context-events
subscribe receiveAppContextEvent
Receive App Context (object) events.
App Context (object metadata) events delivered when user, channel, or membership metadata is created, updated, or deleted. Event types are "set" or "delete"; entity types are "uuid", "channel", or "membership".

Messages

✉
Message
Published Message
A user-published message delivered to channel subscribers.
✉
Signal
Signal Event
A signal event delivered to channel subscribers (payload ≤ 64 bytes).
✉
PresenceJoin
Presence Join Event
✉
PresenceLeave
Presence Leave Event
✉
PresenceTimeout
Presence Timeout Event
✉
PresenceStateChange
Presence State-Change Event
✉
PresenceInterval
Presence Interval Event
✉
FileEvent
File Upload Event
✉
MessageActionEvent
Message Action Event
✉
UuidMetadataEvent
User (UUID) Metadata Event
✉
ChannelMetadataEvent
Channel Metadata Event
✉
MembershipEvent
Membership Event

Servers

https
production ps.pndsn.com
PubNub production edge endpoint. The Subscribe API is a long-poll HTTPS GET under the path /v2/subscribe/{sub-key}/{channels}/0. Despite the realtime semantics modeled by this AsyncAPI document, the underlying binding is HTTPS, NOT WebSocket.

AsyncAPI Specification

Raw ↑ 
asyncapi: '2.6.0'
id: 'urn:com:pubnub:realtime'
info:
  title: PubNub Realtime Streaming API
  version: '3.0.0'
  description: |
    AsyncAPI description of PubNub's realtime subscribe surface — the event stream
    that delivers messages, signals, presence updates, file events, message-action
    events, and App Context (object) events to subscribed clients.

    Transport note (important honesty disclaimer):
    PubNub's official public wire protocol is NOT WebSocket. The Subscribe API is
    delivered over HTTPS as a long-lived long-poll request against ps.pndsn.com.
    The SDK issues a GET subscribe request; the network either returns immediately
    with a batch of events (HTTP 200 with a JSON envelope) or holds the request
    until a long-poll expiration (~280 seconds) and returns an empty batch, after
    which the SDK reissues the request using the most recent timetoken.

    AsyncAPI is used here to model the EVENT-LEVEL contract (channels, message
    schemas, presence/object/message-action events) that the SDK exposes to
    application code via listeners. The underlying transport binding is HTTP
    long-poll, not WebSocket. PubNub's own documentation describes only the
    SDK-level listener event objects publicly; the lower-level wire envelope
    (t/m/e/a/f/i/p/k/c/d/b/u fields) is not formally published and is therefore
    not modeled in this spec to avoid fabrication.

    Source documentation:
    - https://www.pubnub.com/docs/general/setup/connection-management
    - https://www.pubnub.com/docs/general/presence/presence-events
    - https://www.pubnub.com/docs/general/metadata/basics
    - https://www.pubnub.com/docs/sdks/javascript/api-reference/publish-and-subscribe
    - https://www.pubnub.com/docs/sdks/javascript/api-reference/message-actions

    Authentication: publish/subscribe key pair (per keyset). Optional Access
    Manager auth token via the auth query parameter.
  contact:
    name: PubNub Support
    url: https://support.pubnub.com/
  license:
    name: PubNub Terms of Service
    url: https://www.pubnub.com/legal/terms-of-service/
  termsOfService: https://www.pubnub.com/legal/terms-of-service/

defaultContentType: application/json

servers:
  production:
    url: ps.pndsn.com
    protocol: https
    description: |
      PubNub production edge endpoint. The Subscribe API is a long-poll HTTPS GET
      under the path /v2/subscribe/{sub-key}/{channels}/0. Despite the realtime
      semantics modeled by this AsyncAPI document, the underlying binding is
      HTTPS, NOT WebSocket.

channels:
  message:
    description: |
      Standard published messages delivered to all subscribers of a channel.
      Received by SDK listeners as a "message" event.
    subscribe:
      summary: Receive published messages on a channel.
      operationId: receiveMessage
      message:
        $ref: '#/components/messages/Message'

  signal:
    description: |
      Lightweight signals delivered to subscribers of a channel. Signals are
      capped at 64 bytes of payload and are intended for high-volume, low-latency
      use cases. Received by SDK listeners as a "signal" event.
    subscribe:
      summary: Receive signals on a channel.
      operationId: receiveSignal
      message:
        $ref: '#/components/messages/Signal'

  presence:
    description: |
      Presence events for a channel, delivered on the {channel}-pnpres
      companion channel. Event types include join, leave, timeout, state-change,
      and interval.
    subscribe:
      summary: Receive presence events for a channel.
      operationId: receivePresence
      message:
        oneOf:
          - $ref: '#/components/messages/PresenceJoin'
          - $ref: '#/components/messages/PresenceLeave'
          - $ref: '#/components/messages/PresenceTimeout'
          - $ref: '#/components/messages/PresenceStateChange'
          - $ref: '#/components/messages/PresenceInterval'

  file:
    description: |
      File events delivered when a file is uploaded to a channel. Subscribers
      receive a file event containing the file ID, filename, and an optional
      description.
    subscribe:
      summary: Receive file events on a channel.
      operationId: receiveFile
      message:
        $ref: '#/components/messages/FileEvent'

  message-action:
    description: |
      Message action events delivered when a reaction or action (e.g. emoji
      reaction, read receipt) is added to or removed from a previously published
      message on a channel.
    subscribe:
      summary: Receive message action events on a channel.
      operationId: receiveMessageAction
      message:
        $ref: '#/components/messages/MessageActionEvent'

  app-context-events:
    description: |
      App Context (object metadata) events delivered when user, channel, or
      membership metadata is created, updated, or deleted. Event types are
      "set" or "delete"; entity types are "uuid", "channel", or "membership".
    subscribe:
      summary: Receive App Context (object) events.
      operationId: receiveAppContextEvent
      message:
        oneOf:
          - $ref: '#/components/messages/UuidMetadataEvent'
          - $ref: '#/components/messages/ChannelMetadataEvent'
          - $ref: '#/components/messages/MembershipEvent'

components:
  messages:
    Message:
      name: Message
      title: Published Message
      summary: A user-published message delivered to channel subscribers.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ListenerMessage'

    Signal:
      name: Signal
      title: Signal Event
      summary: A signal event delivered to channel subscribers (payload ≤ 64 bytes).
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ListenerMessage'

    PresenceJoin:
      name: PresenceJoin
      title: Presence Join Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PresenceJoinPayload'

    PresenceLeave:
      name: PresenceLeave
      title: Presence Leave Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PresenceLeavePayload'

    PresenceTimeout:
      name: PresenceTimeout
      title: Presence Timeout Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PresenceTimeoutPayload'

    PresenceStateChange:
      name: PresenceStateChange
      title: Presence State-Change Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PresenceStateChangePayload'

    PresenceInterval:
      name: PresenceInterval
      title: Presence Interval Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PresenceIntervalPayload'

    FileEvent:
      name: FileEvent
      title: File Upload Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/FileEventPayload'

    MessageActionEvent:
      name: MessageActionEvent
      title: Message Action Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/MessageActionEventPayload'

    UuidMetadataEvent:
      name: UuidMetadataEvent
      title: User (UUID) Metadata Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AppContextEventPayload'

    ChannelMetadataEvent:
      name: ChannelMetadataEvent
      title: Channel Metadata Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AppContextEventPayload'

    MembershipEvent:
      name: MembershipEvent
      title: Membership Event
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AppContextEventPayload'

  schemas:
    Timetoken:
      type: string
      description: |
        17-digit PubNub timetoken — number of 100-nanosecond intervals since
        Unix epoch. Encoded as a string to preserve precision.
      pattern: '^[0-9]{17}$'
      example: '15610547826969050'

    ListenerMessage:
      type: object
      description: |
        SDK listener event object delivered for "message" and "signal" events.
        Fields as documented in the JavaScript SDK publish-and-subscribe API
        reference.
      properties:
        channel:
          type: string
          description: The channel ID for which the message belongs.
        subscription:
          type: [string, 'null']
          description: Channel group or wildcard subscription match, if any.
        timetoken:
          $ref: '#/components/schemas/Timetoken'
          description: Publish timetoken.
        message:
          description: The message payload (arbitrary JSON).
        publisher:
          type: string
          description: User ID of the message publisher.
        userMetadata:
          type: object
          description: Optional sender user metadata.
        meta:
          type: object
          description: Optional extra metadata published with the request.
      required:
        - channel
        - timetoken
        - message

    PresenceJoinPayload:
      type: object
      required:
        - action
        - channel
        - subscribedChannel
        - timetoken
        - occupancy
        - uuid
        - timestamp
      properties:
        action:
          type: string
          enum: [join]
        channel:
          type: string
        subscribedChannel:
          type: string
          description: Companion presence channel (suffix -pnpres).
        timetoken:
          $ref: '#/components/schemas/Timetoken'
        occupancy:
          type: integer
        uuid:
          type: string
        timestamp:
          type: integer
          description: Unix timestamp (seconds).
      example:
        action: join
        channel: chats.room1
        subscribedChannel: chats.room1-pnpres
        timetoken: '15119466699655811'
        occupancy: 2
        uuid: user123
        timestamp: 1511946669

    PresenceLeavePayload:
      type: object
      required:
        - action
        - channel
        - subscribedChannel
        - timetoken
        - occupancy
        - uuid
        - timestamp
      properties:
        action:
          type: string
          enum: [leave]
        channel:
          type: string
        subscribedChannel:
          type: string
        timetoken:
          $ref: '#/components/schemas/Timetoken'
        occupancy:
          type: integer
        uuid:
          type: string
        timestamp:
          type: integer
      example:
        action: leave
        channel: chats.room1
        subscribedChannel: chats.room1-pnpres
        timetoken: '15119466699655811'
        occupancy: 2
        uuid: user123
        timestamp: 1511946669

    PresenceTimeoutPayload:
      type: object
      required:
        - action
        - channel
        - subscribedChannel
        - timetoken
        - occupancy
        - uuid
        - timestamp
      properties:
        action:
          type: string
          enum: [timeout]
        channel:
          type: string
        subscribedChannel:
          type: string
        timetoken:
          $ref: '#/components/schemas/Timetoken'
        occupancy:
          type: integer
        uuid:
          type: string
        timestamp:
          type: integer
      example:
        action: timeout
        channel: chats.room1
        subscribedChannel: chats.room1-pnpres
        timetoken: '15119466699655811'
        occupancy: 2
        uuid: user123
        timestamp: 1511946669

    PresenceStateChangePayload:
      type: object
      required:
        - action
        - channel
        - subscribedChannel
        - state
        - timetoken
        - occupancy
        - uuid
        - timestamp
      properties:
        action:
          type: string
          enum: [state-change]
        channel:
          type: string
        subscription:
          type: [string, 'null']
        actualChannel:
          type: [string, 'null']
        subscribedChannel:
          type: string
        state:
          type: object
          description: Arbitrary JSON state object set by the user.
        timetoken:
          $ref: '#/components/schemas/Timetoken'
        occupancy:
          type: integer
        uuid:
          type: string
        timestamp:
          type: integer
      example:
        action: state-change
        channel: room-1
        subscription: null
        actualChannel: null
        subscribedChannel: room-1-pnpres
        state:
          mood: grumpy
        timetoken: '15119477895378127'
        occupancy: 5
        uuid: user1
        timestamp: 1511947789

    PresenceIntervalPayload:
      type: object
      description: |
        Interval event — replaces individual join/leave/timeout events when channel
        occupancy exceeds the "Announce Max" threshold. With Presence Deltas
        enabled the event also includes join/leave/timeout arrays of UUIDs that
        changed since the last interval.
      required:
        - action
        - channel
        - occupancy
        - subscribedChannel
        - timestamp
        - timetoken
      properties:
        action:
          type: string
          enum: [interval]
        channel:
          type: string
        occupancy:
          type: integer
        join:
          type: array
          items:
            type: string
          description: UUIDs that joined since the last interval (Presence Deltas).
        leave:
          type: array
          items:
            type: string
          description: UUIDs that left since the last interval (Presence Deltas).
        timeout:
          type: array
          items:
            type: string
          description: UUIDs that timed out since the last interval (Presence Deltas).
        subscribedChannel:
          type: string
        timestamp:
          type: integer
        timetoken:
          $ref: '#/components/schemas/Timetoken'
        hereNowRefresh:
          type: boolean
          description: |
            Flag indicating payload size exceeded limits; clients should use the
            Here Now API to retrieve active User IDs.
      example:
        action: interval
        channel: chats.megachat
        occupancy: 27
        join: [user123, user88]
        leave: [user20, user11, user14]
        timeout: [user42]
        subscribedChannel: chats.megachat-pnpres
        timestamp: 1511947739
        timetoken: '15119477396210903'
        hereNowRefresh: false

    FileEventPayload:
      type: object
      description: |
        File event delivered to subscribers when a file is uploaded to a channel.
        Contains the publishing channel, an optional message description, and
        the file descriptor (id, name). A download URL can be constructed using
        the SDK's getFileUrl() method.
      properties:
        channel:
          type: string
        subscription:
          type: [string, 'null']
        timetoken:
          $ref: '#/components/schemas/Timetoken'
        publisher:
          type: string
        message:
          description: Optional description published with the file.
        file:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
              description: Unique file identifier.
            name:
              type: string
              description: Filename.
      required:
        - channel
        - file

    MessageActionEventPayload:
      type: object
      description: |
        Message action event payload as documented in the addMessageAction /
        removeMessageAction API reference. Delivered via subscribe listeners to
        clients subscribed to the channel.
      properties:
        channel:
          type: string
        subscription:
          type: [string, 'null']
        timetoken:
          $ref: '#/components/schemas/Timetoken'
        publisher:
          type: string
        data:
          type: object
          properties:
            type:
              type: string
              description: Action type (e.g. "reaction", "receipt").
            value:
              type: string
              description: Action value (e.g. an emoji name).
            uuid:
              type: string
              description: User ID that added the action.
            actionTimetoken:
              $ref: '#/components/schemas/Timetoken'
            messageTimetoken:
              $ref: '#/components/schemas/Timetoken'
      example:
        data:
          type: reaction
          value: smiley_face
          uuid: user-456
          actionTimetoken: '15610547826970050'
          messageTimetoken: '15610547826969050'

    AppContextEventPayload:
      type: object
      description: |
        App Context (object metadata) event envelope. Delivered via subscribe
        when user, channel, or membership metadata is created, updated, or
        deleted. Structure as documented at
        https://www.pubnub.com/docs/general/metadata/basics.
      required:
        - channel
        - message
        - timetoken
      properties:
        channel:
          type: string
        subscription:
          type: [string, 'null']
        timetoken:
          $ref: '#/components/schemas/Timetoken'
        message:
          type: object
          required:
            - source
            - version
            - event
            - type
          properties:
            source:
              type: string
              enum: [objects]
            version:
              type: string
              example: '2.0'
            event:
              type: string
              enum: [set, delete]
              description: Operation that occurred.
            type:
              type: string
              enum: [uuid, channel, membership]
              description: Entity type the event refers to.
            data:
              type: object
              description: Event-specific entity payload.
      example:
        channel: sample-channel
        message:
          source: objects
          version: '2.0'
          event: set
          type: uuid
          data: {}
        subscription: sample-subscription
        timetoken: '15610547826969050'