Skip to main content
Markdown

Chat

Conversations between two people and in groups: messages that arrive at once on every device, who is typing, read ticks and reactions. The pages send to each other straight through WordPlus Cloud, sealed, and your server keeps the conversation in its own database from the webhook, so it is yours to search, moderate and show again.

The chat window of Ben shows “Ann typing” while Ann, in her own browser, writes a reply

The rooms​

A room for each conversation, named after it: chat:34:42 for the two people 34 and 42, the smaller id first, and group:7 for a group. A page joins the room of a conversation to send and receive in it.

Your server decides who may join. A page that joins asks your server first, and a rule answers: a function your server registers once for every room whose name fits a pattern, such as chat:{a}:{b}. WordPlus Cloud then holds the page to the answer (permissions). These rules say:

  1. A conversation of two lets in only the two people its name holds.
  2. A group lets in its members, who also see who else is in it.
// What every conversation carries, explained below the code.
const chat = { history: 50, emit: [ 'message', 'typing', 'read', 'reaction' ], webhook: [ 'message', 'reaction' ] };

// 1. Two people, such as chat:34:42: only the two in the name.
realtime.room( 'chat:{a}:{b}', chat, ( user, { a, b } ) => [ a, b ].includes( String( user ) ) );

// 2. A group, such as group:7: its members, who see each other in it.
realtime.room( 'group:{id}', { ...chat, presence: true }, async ( user, { id } ) => isMemberOf( id, user ) );
  • emit lists what the pages may send to each other, and nothing else gets through.
  • webhook names what your server gets too, to keep.
  • history carries the last 50 for 5 minutes, for a page that reconnects. Your database keeps the rest.

Keeping the conversation​

Your server saves each message by its event_id, the id the pages saw, so a webhook delivered twice saves it once:

// A guest in a public room sends with no `from`: kept here from signed-in people alone.
realtime.on( 'message', ( { room, from, data, event_id, at } ) => from && db.messages.upsert( { id: event_id, room, from, text: data.text, at } ) );
realtime.on( 'reaction', ( { from, data } ) => from && db.reactions.set( data.id, from, data.key ) );   // an empty key takes it back

And a route of yours gives a conversation back, the newest 50 messages, or the 50 before ?before=<id>, as { messages: [ { id, from, text, at, reactions } ], more }, only to the people in it (events from the page).

The page, ready-made​

The chat of Better Messages, with the history from your route, typing, read ticks and reactions:

<wordplus-chat room="chat:34:42" messages="/api/chat/34/42/messages" style="height: 520px"></wordplus-chat>
<wordplus-typing room="chat:34:42"></wordplus-typing>

In React, <Chat rt={ rt } room="chat:34:42" messages="/api/chat/34/42/messages" /> of @wordplus/realtime-ui/react, with its chat.css (elements, React).

The page, your own​

const chat = rt.join( 'chat:34:42' );

form.onsubmit = async () => {
    const { id, at } = await chat.emitWithAck( 'message', { text: input.value } );   // checked, kept and sent on
    draw( { id, from: me, text: input.value, at } );
};
input.oninput = () => chat.volatile.emit( 'typing', { on: input.value !== '' } );   // never queued or kept

chat.on( 'message', ( data, meta ) => {
    draw( { id: meta.id, from: meta.from, text: data.text, at: meta.at } );
    chat.volatile.emit( 'read', { id: meta.id } );
} );
chat.on( 'typing', ( data, meta ) => showTyping( meta.from, data.on ) );
chat.on( 'read', ( data, meta ) => markRead( meta.from, data.id ) );
  • meta.from is the sender as your server vouched for them: a page cannot write as someone else.
  • A refused message rejects with its code: not_allowed, rate_limited, too_large (errors).
  • Pictures and files may ride in the data as binary, up to 1 MB an event, or as a link to your storage for anything larger.

Telling the other person​

A message shows at once only on a page that has its conversation open. Ben writes to Cara while she is on another page of your app, and she sees nothing there. So tell her yourself:

  1. Your server hears the message: from its webhook, as it keeps it.
  2. It sends Cara a notice of her own with toUser(), which reaches every page and app she has open.
  3. Her page shows it: a toast with the name, the text and a link, or a count beside the conversation.
// After keeping it (above): the other one of the two, told on every page they have open.
realtime.on( 'message', async ( { room, from, data, event_id } ) => {
    const [ kind, a, b ] = room.split( ':' );           // chat:34:42
    if ( kind !== 'chat' ) return;
    const to = String( from ) === a ? b : a;
    await realtime.toUser( to ).emit( 'new_message', { room, from, text: data.text.slice( 0, 140 ), id: event_id } );
} );

Every page of a signed-in user listens, and leaves out the conversation it has open:

// React, in the layout of your signed-in pages, beside the provider.
useUserEvent( 'new_message', ( m ) => {
    if ( m.room !== openRoom ) toast( nameOf( m.from ), m.text, `/messages/${ m.room }` );
} );

In plain JavaScript, rt.on( 'new_message', ( m ) => … ) does the same (sending).

  • A count of new messages: add one to the conversation in your list for each notice, and clear it as the user opens it.
  • Nothing open, nothing heard: toUser() reaches the pages and apps open now. For someone away, send an email from your server after a while.

Without a webhook, as on localhost​

A webhook needs an address on the internet, so your server on localhost never gets one. While you build, the page can tell your server itself: onSent hears each message the room took, with its id.

<Chat rt={ rt } room="chat:34:42" messages="/api/chat/34/42/messages"
      onSent={ ( m ) => fetch( '/api/chat/sent', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify( m ) } ) } />

<wordplus-chat> says the same with its sent event: chat.addEventListener( 'sent', ( e ) => send( e.detail ) ). Your route /api/chat/sent then does what the webhook does above: it checks the user of the session is one of the two in m.room, keeps the message by m.id, and tells the other one. The webhook stays the one to trust where it reaches you, as WordPlus Cloud signs it, and keeping by the id lets both run without keeping a message twice.

  • Both on at once? Keep the message from either, by its id, but send the notice from one alone: the route of onSent while you build, the webhook once it reaches you. Or let the page show one notice for each id.
  • In Next.js, <Chat> goes in a client component ('use client') of your own (Next.js).

Groups​

  • Who is in the group comes from the presence of its room: chat.members, then join and leave (presence).
  • Someone removed from the group goes at once: take them off the group in your data, so your rule says no for them, then realtime.in( 'group:7' ).kick( 34 ). Their token is refused from then on, a reload asks your rule again, and newer messages are sealed with a key they never get (encryption).
  • Someone added joins when their page next asks: your rule says yes from then on.
  • A reader who may not write, such as a supervisor: the rule answers { readOnly: true } for them (permissions).

Variations​

  • A support chat beside a call: a <wordplus-call> button in the header of the conversation (calls from a button).
  • The same conversations in iOS and Android apps, on the same rooms (iOS events, Android events).
  • In a WordPress plugin: the same rooms with wordplus_realtime()->room() (WordPress events).