Skip to main content
Markdown

A support desk with agents

Customers write to support, and a team of agents answers them: each new conversation goes to an agent on duty, the others see it and may read along, an agent and the customer see each other type, the agent calls the customer from the conversation when writing is not enough, and agents leave notes on it that the customer never sees.

Every part is a room or a call with a rule of your server. Your server keeps the conversations from the webhook, decides who answers each one, and tells the pages.

The rooms​

A ticket is a conversation, named after it: ticket:9. Beside it, ticket:9:notes, the notes of the agents on that ticket. And desk, a room for the agents alone, where they see who is on duty and hear of each ticket as it opens and as someone takes it.

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

  1. A ticket lets in its customer, who writes in it.
  2. The agent of the ticket writes in it too.
  3. Every other agent reads along, and writes nothing.
  4. The notes of a ticket let in agents alone.
  5. The desk lets in agents alone, who see each other on duty.
  6. A call from the ticket may run between its customer and its agent, either one calling.
// What a ticket carries: what the ready-made chat sends, explained below the code.
const conversation = { history: 50, emit: [ 'message', 'typing', 'read', 'reaction' ], webhook: [ 'message', 'reaction' ] };

realtime.room( 'ticket:{id}', conversation, async ( user, { id } ) => {
    const ticket = await findTicket( id );
    if ( !ticket ) return false;

    // 1. Its customer.
    if ( ticket.customerId === String( user ) ) return true;

    // 2. Its agent.
    if ( ticket.agentId === String( user ) ) return true;

    // 3. Any other agent reads along.
    if ( await isAgent( user ) ) return { readOnly: true };

    return false;
} );

// 4. The notes of a ticket, such as ticket:9:notes: agents alone.
realtime.room( 'ticket:{id}:notes', { history: 50, emit: [ 'note' ], webhook: [ 'note' ] }, ( user ) => isAgent( user ) );

// 5. The desk: agents alone, who see each other on duty.
realtime.room( 'desk', { presence: true, history: 50 }, ( user ) => isAgent( user ) );

// 6. A call named as the ticket: its customer and its agent, either one calling.
realtime.calls( 'ticket:{id}', async ( user, withUser, { id } ) => {
    const ticket = await findTicket( id );
    if ( !ticket || !ticket.agentId ) return false;

    const two = [ ticket.customerId, ticket.agentId ];
    return two.includes( String( user ) ) && two.includes( String( withUser ) );
} );
  • emit of a ticket lists what the ready-made chat sends: messages, typing, read ticks and reactions. A reader the rule answered readOnly sends none of them.
  • webhook sends messages, reactions and notes to your server, to keep them.
  • The notes stay among agents: the customer is refused the notes room, and its notes are sealed with a key of that room, which no customer gets (encryption).
  • ticket:{id} never matches ticket:9:notes, since a part of a pattern stops at :, so each room keeps its own rule.
  • A call and a room may share a name: ticket:9 is the conversation as a room and its call as a call, each with its own rule.

Opening and assigning​

  1. The customer opens a ticket with a route of yours, which keeps it and tells the desk.
  2. Your server gives it to an agent on duty: of the members of desk, the one with the fewest open tickets. With nobody on duty, it stays open for the first agent who takes it.
  3. An agent takes an open ticket from the list. The first one gets it: your route sets the agent in one update, only while nobody has it, and answers the others 409.
  4. Either way, assigned goes to the desk and to the ticket, so the customer sees who answers.
// 1. The customer opens a ticket.
app.post( '/tickets', async ( req, res ) => {
    const ticket = await createTicket( req.user.id, req.body.subject );
    await realtime.to( 'desk' ).emit( 'opened', { ticket: ticket.id, subject: ticket.subject } );

    // 2. To the agent on duty with the fewest open tickets, if anyone is on duty.
    const { list } = await realtime.in( 'desk' ).members();
    const agent = await leastBusy( list.map( ( member ) => member.id ) );
    if ( agent ) await assign( ticket.id, agent );
    res.status( 201 ).json( { id: ticket.id } );
} );

// 3. An agent takes an open ticket: the first one gets it.
app.post( '/tickets/:id/take', async ( req, res ) => {
    if ( !( await isAgent( req.user.id ) ) ) return res.sendStatus( 403 );
    if ( !( await assign( req.params.id, String( req.user.id ) ) ) ) return res.sendStatus( 409 );   // another agent was first
    res.sendStatus( 204 );
} );

// 4. Kept in one update while nobody has it, then told to the desk and to the ticket.
async function assign( ticket, agent ) {
    if ( !( await setAgentIfNone( ticket, agent ) ) ) return false;
    const event = { ticket, agent: { id: agent, name: await nameOf( agent ) } };
    await realtime.to( [ 'desk', 'ticket:' + ticket ] ).emit( 'assigned', event );
    return true;
}

Each route is the body of a route in your framework, given the signed-in user. A WordPress REST route knows the user from the REST nonce of the page, which wp.apiFetch sends. A ticket given to someone else, as a lead moves it, is the same update with no "while nobody has it", then the same assigned.

Keeping the conversation and the notes​

Your server keeps each message and note by its event_id, so a webhook delivered twice keeps it once, and tells the other side when they are on another page:

realtime.on( 'message', async ( { room, from, data, event_id, at } ) => {
    if ( !room.startsWith( 'ticket:' ) ) return;
    const ticket = await findTicket( room.slice( 7 ) );
    await saveMessage( { id: event_id, ticket: ticket.id, from, text: data.text, at } );

    // The customer wrote: their agent hears it on any page. The agent wrote: the customer does.
    const to = from === ticket.customerId ? ticket.agentId : ticket.customerId;
    if ( to ) await realtime.toUser( to ).emit( 'ticket_message', { ticket: ticket.id, text: data.text.slice( 0, 140 ) } );
} );

realtime.on( 'note', ( { room, from, data, event_id, at } ) => saveNote( { id: event_id, ticket: room.split( ':' )[ 1 ], from, text: data.text, at } ) );

Your app also answers the conversation of a ticket from a route, as { messages: [ { id, from, text, at, reactions } ], more }, to its customer and to agents, for the chat to show as it opens (chat), and the notes of a ticket to agents alone.

The page of the customer​

The ready-made chat, with the call of the ticket shown in it while it is on:

<chat-room room="ticket:9" call messages="/tickets/9/messages" style="height: 560px"></chat-room>
<p id="agent"></p>

<script type="module">
    import { connect } from '@wordplus/realtime';
    const rt = await connect( window.wordplusRealtimeConfig );
    await rt.callScreen();                  // the ring, and the chat with its call
    const ticket = rt.join( 'ticket:9' );
    ticket.on( 'assigned', ( { agent } ) => ( document.getElementById( 'agent' ).textContent = agent.name + ' answers you' ) );
    ticket.on( 'closed', () => showClosed() );
</script>
  • call alone shows the call named as the room, ticket:9, in the chat, beside the messages, once it starts (the chat).
  • Who is typing comes with the chat, both ways.
  • On WordPress, a REST route knows the user only with the REST nonce, which messages does not send: give the chat load in its place, with wp.apiFetch (WordPress events).

The page of an agent​

The list of tickets from the desk, the conversation with the customer on its top bar and their call buttons, and the notes beside it:

<chat-room room="ticket:9" to="42" name="Ben" call messages="/tickets/9/messages" style="height: 560px"></chat-room>
<online-list room="desk" title="On duty"></online-list>
<form id="note"><input name="text" placeholder="A note for the team"></form>

<script type="module">
    import { connect } from '@wordplus/realtime';
    const rt = await connect( window.wordplusRealtimeConfig );
    await rt.callScreen();

    // The tickets: opened, then assigned.
    const desk = rt.join( 'desk' );
    desk.on( 'opened', ( { ticket, subject } ) => list.add( ticket, subject ) );
    desk.on( 'assigned', ( { ticket, agent } ) => list.assign( ticket, agent ) );

    // The notes of this ticket, which its customer never sees.
    const notes = rt.join( 'ticket:9:notes' );
    notes.on( 'note', ( data, meta ) => drawNote( meta.from, data.text ) );
    document.getElementById( 'note' ).onsubmit = async ( e ) => {
        e.preventDefault();
        const { id } = await notes.emitWithAck( 'note', { text: e.target.text.value } );
        drawNote( me, e.target.text.value, id );
    };
</script>
  • to puts the customer on the top bar of the chat, online or not, with a video and an audio call button.
  • The desk lists the agents on duty, with the names your profile gives.
  • An agent reading along, whom the rule answered readOnly, sees the conversation and cannot write in it: their chat refuses to send.
  • Taking a ticket they were reading: the page joins the room again once the route says it is theirs, rt.leave( 'ticket:9' ) then rt.join( 'ticket:9' ) (or draws the chat anew). The rule answered read only when they joined, and answers again as they join.

A call from the conversation​

The agent presses the video button on the top bar of the chat, and it rings the customer in every tab they have open, and shows in the chat on both sides. Your call rule runs for the agent as they call, and again for the customer as they answer (how a page asks your server).

  • It connects on any network: directly between the two devices, through our relays on the ports of the web, 443 and 80, when a firewall blocks that, or through our media servers when even the relays cannot reach (how it connects).
  • Encrypted end to end on every path, and no credits on any of them.
  • Showing a screen: the customer shares their screen in the call from a browser on a computer (remote help).
  • How long they talked, for your records of the ticket: the webhook call.ended, with call the name of the ticket and seconds (sending).

From your server​

const { list } = await realtime.in( 'desk' ).members();      // the agents on duty now, with their info
await realtime.to( 'ticket:9' ).emit( 'closed', {} );        // the customer page says it is closed
await realtime.in( 'ticket:9' ).kick( 56 );                  // an agent taken off a ticket, out at once
  • Closing a ticket: tell the page with closed, and keep the ticket closed in your data, so the rule of the call says no from then on.
  • An agent taken off a ticket goes at once with kick(), and their token is refused from then on (taking access away).
  • An agent who leaves their desk shows in desk no more: the member.left webhook tells your server, to give their open tickets to others.

Variations​