Bot Directory

Bots can be created and managed in your organization's Bot Directory. Multi-tenant bots are shared across a group of organizations, and can be enabled and configured by each organization independently.

Bot Definitions and Instances

The bot definition is the global representation of your bot for use across all organizations, and the bot instance is the local representation for use in a specific organization. The bot serves as the template from which common and default properties are derived for use in creating corresponding bot instance objects. A bot therefore has a 1:1 relationship with the software application, and a 1:many relationship with its corresponding bot instance object(s).

A bot instance must be created in each tenant where the application is used, enabling it to establish an identity for sign-in and/or access to resources being secured by the organization. A single-tenant bot has only one bot instance (in its owner's organization). A multi-tenant bot also has a bot instance created in each organization where a user from that organization has consented to its use.

Multi-tenant bots

ChatShipper organizes users, bots and resources into groups called tenant organizations. Developers can choose to configure their bot to be either single-tenant or multi-tenant during bot registration.

• Single-tenant bots are only available in the organization they were registered in.
• Multi-tenant bots are available to users in both their own and other organizations.

In the admin UI, you can configure your bot to be single-tenant or multi-tenant by setting the audience.

(1) Audience can be set to Owner (only this org can enable/use it), Sub-orgs (this and suborgs can enable/use it) or Global (everyone can enable/use it)
(2) When Audience is set to Sub-org, you can either share it will all underlying organization or configure a tag that suborganisations must configure to see the bot in the bor directory

Bot Definition

A bot is defined by its one and only bot object, which resides in the organization where the bot was created. A bot's definition is used as a template to create one or more bot instances. A bot instance is created in every organization where the bot is used. Similar to a class in object-oriented programming, the bot definition has some static properties that are applied to all the bot instances.

The bot object describes three aspects of a bot application: how the bot application can issue tokens in order to access ChatShipper, resources that the bot might need to access, and the actions that the bot can take.

See the API Reference for full details

Bot Instance

A bot instance is the local representation, or application instance, of a global bot in a single organization. A bot instance is a concrete instance created from the bot definition and inherits certain properties from it. A bot instance is created in each organization where the bot is enable/added for the bot store and references the globally unique bot definition. The bot instance specifies what the bot can actually do in the specific tenant organization.

A bot instance is created automatically when you register a new bot in the admin UI, when a bot is given permission to access resources in an organization. You can also create a bot instance using the API.

(1) Selecting the store
(2) And adding a bot from the store, will create in instance of this bot where you can configure that bots settings (in the meta vaiable of the bot)

(1,2) When configuring the bot
(3) You can change it's configuration. meta vars that are show here but are empty can be overruled here.

See the API Reference for full details

Bot Authentication

To obtain an access token, the bot's client ID is used as part of the email, and the client secret must be used as the password in a JSON object posted to the token API URL:

Request: POST /v2/auth/token

{
  "email": `bot+${bot.id}@chatshipper.com`,
  "password": "t0pZ3kR3t"
}

See API Authentication for more information.

Bot registration

A bot must be registered with a tenant organization. When you register your bot with ChatShipper, you are creating an identity configuration for your bot that allows it to integrate with ChatShipper. When you register a bot, you choose whether it's a single tenant (only accessible in your own organization) or multi-tenant (accessible to other organizations) and can optionally set a webhook URL (where the subscribed events are sent to).

Register a bot application

Follow these steps to create a bot

SDK example

When using the chipchat nodejs SDK to listen to incoming events, you will get the instance configuration passed via the message and context objects of an incoming event, like this:

const Chipchat = require('chipchat');
const api = new Chipchat({ email: `bot+${process.env.BOTID}@chatshipper.com`});
api.on('message.create.contact.message', (message, context) => {
    console.log('the bots merged instance meta config:', context.instance.meta);
});
api.start();