Skip to main content
Version: 0.1

Operator API (Alpha)

Overview​

The Operator API integrates AIs into your virtual HQ.

AIs in Roam appear on the map just like users. They can chat using Roam messaging (using the Chat API) and enter meetings (audio only for now).

Modes of operation​

There are two modes of operation:

  1. Knock - AIs may be sent to visit someone with instructions to guide the conversation and obtain a certain output. It waits to initiate the meeting until the user is alone in their office. It tries again later if the knock is refused or the user verbally asks the AI to come back later.

  2. Seat - AIs may be assigned a seat on one or more floors of your Roam. This allows colleagues to drop-in to talk whenever they need something.

Conversations are fulfilled using OpenAI's Realtime API, though we intend to offer alternative backends.

Controlling AI behavior​

AIs have the following control knobs:

  1. Instructions provided to the AI may describe exactly what experience you're after:

    • The goal at hand. What should the output of the meeting be?

    • The persona to adopt. Should it inject humor when possible or speak quickly and succinctly?

    • Information that it needs to know about the individuals, projects, and processes.

  2. Tool-calling can be configured to retrieve information (RAG) or make changes.

    Tools may be supplied at the beginning of a meeting. Tool calls are relayed via webhook, and tool call output may be provided in response to the webhook or via a subsequent command.

    Roam provides built-in tools to come back later or conclude the meeting.

  3. Parameters such as the AI's voice (e.g. alloy, echo), temperature, and so on are also available for customization. With OpenAI Realtime as the backend, Developers may customize any properties of the Session.

Levels of customization​

There are three levels of customizability:

  • Level 1: Basic interactions with minimal setup.

    Roam handles the conversation, and results are sent via webhook.

  • Level 2: Realtime meeting control and visibility.

    Realtime control over conversations can be had by subscribing to the "knock.ready" webhook event, where instructions and context can be provided just-in-time. During the conversation, OpenAI's Realtime API Events are relayed in both directions. You will receive Server Events and may send Client Events.

  • Level 3: Advanced integration for direct handling of audio.

    A media connection is available via WebSocket for developers who want to bring their own voice backend.

Create an AI persona in "Roam Settings > Developer". Each API Client may have multiple personas associated with it which may be used for messaging or voice.

The API is under active development.

Please inform Developer Support (via Team Roam Support Chat) if you are an early adopter and we will provide live support.

Quick Start​

Requirements:

  • You must be an Admin of your Roam to access Developer Settings.

  • You must be present in your Roam HQ to receive the knock.

Here are the steps to send your first knock.

  1. Navigate to Roam Administration > Developer

  2. Add an API Client, of type API Key. Save it, and more settings appear.

  3. Enter these settings:

    • Scopes: bot:read, bot:write
    • Bot Personas: Upload an avatar for your bot

  4. Copy the API key & export it as API_KEY in your shell.

  5. Run the following command, replacing $EMAIL with the target user's email address:

$ curl -H "Content-type: application/json" \
       -H "Authorization: Bearer $API_KEY" \
       "https://api.ro.am/v0/bot.knock.create"
       -d '\{"target": "'$EMAIL'", "name": "hi", "instructions": "Say hi"\}'

Record the Knock ID.

You will be visited shortly by your bot's avatar greeting you.

  1. Accept the knock on your Roam office. As an unconfigured AI with no context about you, it would be able to answer questions but will not be especially engaging.

  2. Tell the AI "Please come back in 30 seconds". It should acknowledge the request and leave / return. Accept the knock again.

  3. Tell the AI "I'll have a burger and fries. Please leave the room". The AI should leave the room on its own.

    NOTE: If the AI does not leave on its own, you can always click on its avatar and choose End visit to boot it.

  4. Check the Knock's result:

$ curl -H "Content-type: application/json" \
       -H "Authorization: Bearer $API_KEY" \
       "https://api.ro.am/v0/bot.knock.info?id=$KNOCK_ID"

That concludes this scenario.

Contact

Developer Support: developer@ro.am

URL: https://developer.ro.am

Terms of Service

https://ro.am/terms