Conversational Employee Bots

Overview

Connect your existing bots into Workvivo Chat via the Bot API, enabling automated employee interactions, from answering common queries to routing employees to the right resources.

Employees ask the same questions repeatedly: "How do I reset my password?", "What's the holiday policy?", "Who do I contact about expenses?" These queries flood HR, IT, and operations teams with repetitive work. Rather than building a separate bot platform or forcing employees to switch to another tool, the Workvivo Bot API lets you bring automated assistants directly into the chat experience employees already use every day.

The Bot API supports the full conversational lifecycle: register a bot, open a channel with a user, send text messages, present quick-reply buttons for guided interactions, and display rich cards with action buttons that either send a reply or open a URL. When a user messages your bot, Workvivo sends the message to your bot's callback URL, where your backend processes it and responds via the API. This creates a natural, chat-native experience where employees get instant answers without leaving Workvivo.

Bots can be scoped globally (available to everyone) or targeted to specific teams or spaces, letting you deploy specialised bots for different departments - an IT helpdesk bot for the engineering team, an HR policy bot for all employees, or a facilities bot for specific office locations.

Value & Benefits

Deflect repetitive queries from support teams. Common questions (password resets, policy lookups, office directions) are answered instantly by the bot, freeing HR, IT, and operations staff to focus on complex issues.

Deliver answers where employees already are. Bots live inside Workvivo Chat; employees don't need to navigate to a separate portal, knowledge base, or ticketing system to get help.

Provide 24/7 automated support. Bots respond instantly regardless of time zone or business hours, ensuring frontline and shift workers get answers when they need them.

Guide employees through multi-step processes. Quick replies and card buttons create structured, guided interactions - walking employees through leave requests, IT ticket creation, or onboarding checklists step by step.

Target bots to relevant audiences. Deploy bots to specific teams or spaces so employees only see bots relevant to them, reducing noise and ensuring the right bot handles the right queries.

Applications

IT helpdesk bot. Answer common IT queries (password resets, VPN setup, software requests), triage issues by category using quick replies, and route complex problems to the right support queue with a link to the ticketing system.

HR policy assistant. Let employees ask about leave policies, benefits, expenses, and company procedures. The bot retrieves answers from your knowledge base and presents them with links to full policy documents.

Onboarding companion. Guide new hires through their first-week checklist: completing forms, booking induction sessions, finding key contacts, and accessing training materials - all via interactive card messages.

Facilities and office bot. Help employees book meeting rooms, report maintenance issues, find office directions, or check cafeteria menus - scoped to specific office location teams.

Survey and feedback collection. Proactively reach out to employees via bot messages to collect pulse survey responses, event feedback, or onboarding satisfaction scores using quick-reply buttons.

Workflow trigger bot. Let employees initiate workflows (submit a leave request, raise a purchase order, request equipment) through a conversational interface that collects the required information step by step and submits it to your backend system.

Technical Details

Before using these examples, complete Quick Start to create an app and API key and find your Base URL and Workvivo-Id.

Create a Bot

Before creating bots, make sure Chat and Chat Bots are enabled for the organisation and that Chat is fully configured. Bot creation, bot channels, and bot messages are backed by Workvivo Chat, so these calls require a Chat-enabled organisation with chat provider credentials configured.

Register a new bot with a nickname, type, callback URL, and audience.

curl -X POST https://api.workvivo.com/v1/chat/bots \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -F "bot_nickname=IT Helpdesk" \
  -F "bot_type=productivity" \
  -F "bot_webhook_url=https://your-server.com/bot/callback" \
  -F "bot_profile_url=https://your-server.com/bot/profile" \
  -F "global_audience=1" \
  -F "active=1"

{
    "data": {
        "id": 123,
        "bot_type": "productivity",
        "bot_callback_url": "https://your-server.com/bot/callback",
        "bot_userid": "bot_userid",
        "bot_nickname": "IT Helpdesk",
        "bot_profile_url": "https://your-server.com/bot/profile",
        "active": true,
        "audience": {
            "is_global": true,
            "teams": [],
            "spaces": []
        }
    },
    "status": "success",
    "meta": {}
}

Create a Bot Channel

Open a 1:1 channel between the bot and a user.

curl -X POST https://api.workvivo.com/v1/chat/bots/channels \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -F "user_id=3" \
  -F "bot_userid=bot_userid"

{
    "data": {
        "channel_url": "example_channel_url",
        "cover_url": "https://images.com/example-image",
        "member_count": 2,
        "created_at": "2026-06-17T00:00:00Z",
        "users": [
            { "user_id": 3, "name": "James Ashton" },
            { "bot_userid": "bot_userid", "bot_nickname": "IT Helpdesk" }
        ]
    },
    "status": "success",
    "meta": {}
}

Send Messages

The bot message endpoint supports text, quick-reply, card, and attachment messages. Use application/json for text, quick-reply, and card messages. Use multipart/form-data for attachment uploads.

The examples below show request bodies for POST /v1/chat/bots/message. The first tab shows the full cURL wrapper for a text message; the remaining tabs show alternate JSON bodies you can send to the same endpoint.

curl -X POST https://api.workvivo.com/v1/chat/bots/message \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "bot_userid": "bot_userid",
  "channel_url": "example_channel_url",
  "type": "message",
  "message": "Hi! I'm the IT Helpdesk bot. How can I help you today?"
}
JSON

{
    "bot_userid": "bot_userid",
    "channel_url": "example_channel_url",
    "type": "quick_reply",
    "replies": [
        { "label": "Password Reset", "message": "Password Reset" },
        { "label": "VPN Issues", "message": "VPN Issues" },
        { "label": "Software Request", "message": "Software Request" }
    ]
}

{
    "bot_userid": "bot_userid",
    "channel_url": "example_channel_url",
    "type": "card",
    "cards": [
        {
            "cardTitle": "How can I help?",
            "cardDescription": "Select a category below or type your question.",
            "cardImage": "https://your-server.com/img/helpdesk-banner.png",
            "buttons": [
                { "label": "IT Help", "message": "IT Help" },
                { "label": "HR Help", "message": "HR Help" },
                {
                    "label": "Knowledge Base",
                    "link": "https://help.yourcompany.com"
                }
            ]
        }
    ]
}

Quick replies are buttons that send a predefined message when tapped. Cards are rich messages with title, description, image, and action buttons. Card buttons accept either a message (sent as a chat reply when clicked) or a link (opens a URL in a new tab) - not both.

Note: Messages from a chatbot to a channel trigger a mobile push notification by default. To suppress push notifications, include "send_push": false in the request.

Receiving User Messages

When a user sends a message to your bot, Workvivo delivers it to the bot_webhook_url you configured during bot creation. The callback request includes an x-workvivo-jwt header and a JSON body with action: "chat_bot_message_sent" and a message object containing the bot_userid, channel_url, user details, and the user's message text. Your server processes the message and responds using the POST /v1/chat/bots/message endpoint.

Note: User messages to chatbots are delivered to the bot's callback URL rather than as chat.message.created webhook events. If you need general chat webhook events, configure the standard Chat webhooks separately.

JavaScript Integration Example

A bot callback that receives a user's selection and responds through the Workvivo Chat API.

import express from 'express';
import { sendBotMessage, sendQuickReplies } from './helpers.js';

const app = express();
app.use(express.json());

const answers = {
    'Password Reset': {
        message: 'Visit the company sign-in page and select "Forgot password".',
        replies: [
            { label: 'That helped', message: 'Resolved' },
            { label: 'Raise a ticket', message: 'Raise IT Ticket' },
        ],
    },
    'VPN Issues': {
        message:
            'Reconnect the VPN, then confirm that your client is up to date.',
        replies: [
            { label: 'Fixed', message: 'Resolved' },
            { label: 'Still broken', message: 'Raise IT Ticket' },
        ],
    },
};

app.post('/bot/callback', async (request, response) => {
    const message = request.body.message ?? {};
    const userMessage = message.message?.trim();
    const answer = answers[userMessage];

    if (answer) {
        await sendBotMessage(message.channel_url, answer.message);
        await sendQuickReplies(message.channel_url, answer.replies);
    } else if (userMessage === 'Raise IT Ticket') {
        // Create the ticket in your service desk before replying.
        await sendBotMessage(
            message.channel_url,
            'Your request has been sent to IT.',
        );
    } else {
        await sendQuickReplies(message.channel_url, [
            { label: 'Password reset', message: 'Password Reset' },
            { label: 'VPN issues', message: 'VPN Issues' },
        ]);
    }

    return response.status(200).json({ status: 'processed' });
});

app.listen(3000);

const apiUrl = 'https://api.workvivo.com/v1';
const headers = {
    Authorization: `Bearer ${process.env.WORKVIVO_TOKEN}`,
    'Workvivo-Id': process.env.WORKVIVO_ORG_ID,
    'Content-Type': 'application/json',
    Accept: 'application/json',
};

async function send(payload) {
    const response = await fetch(`${apiUrl}/chat/bots/message`, {
        method: 'POST',
        headers,
        body: JSON.stringify({
            bot_userid: process.env.WORKVIVO_BOT_USERID,
            ...payload,
        }),
    });

    if (!response.ok) {
        throw new Error(`Workvivo API request failed: ${response.status}`);
    }
}

export function sendBotMessage(channelUrl, message) {
    return send({
        channel_url: channelUrl,
        type: 'message',
        message,
    });
}

export function sendQuickReplies(channelUrl, replies) {
    return send({
        channel_url: channelUrl,
        type: 'quick_reply',
        replies,
    });
}