Any bot must register with Khoros Care before it can access the Bot APIs and the Automation Framework. Registration is a one-time (per network) operation. You can use the same bot with multiple channels. If using the same bot for multiple channels, register the bot once per channel using the same App ID for each.

📘

Note

We strongly recommend registering your bot in production with the bot registration mode flag set to MAINTENANCE as early as possible in your production environment. See Bot operating modes for more information and best practices.

Create, update, or delete a bot registration

Bot API v3 provides the following endpoints to register a bot, update a bot registration, and delete a bot registration:

• POST /bots/v3/registrations
• PUT /bots/v3/registrations
• DELETE /bots/v3/registrations/network/{networkKey}/externalId/{externalId}/appId/{appId}

HTTP POST and PUT calls to register a bot or edit a bot registration take a Registration JSON payload JSON payload. A full payload is required for both POST and PUT actions.

{
  "companyKey": "<companyKey>",
  "platform": "LITHIUM",
  "networkKey": "twitter",
  "externalId": "<externalId>",
  "appId": "<botId>",
  "name": "<botName>",
  "avatarUrl": "<optional avatar url>",
  "contact": { "email": "<email to notify of problems>" },
  "mode": "LIVE",
  "publicFilter": {
    "includeTargeted": true
  }, 
  "callbackUrl": "<url of your endpoint>",
  "credentials": {
    "type": "BASIC_AUTH",
    "identity": "<username>",
    "secret": "<secret>"
  },
  "metadata": {
    "internalBot": false,
    "botRefUrl": "https://example.com/reference/ABCDEFG"
  }
}

Metadata is supported within the bot registration payload, sending the included metadata to the bot with each event. The metadata must be included as flat JSON as nested metadata objects are not supported.

Example POST

curl PUT \
  https://api.app.lithium.com/bots/v3/registrations \
  --data @/path/to/payload.json \
  -H "Content-type: application/json; charset=utf-8" \
  -H "Authorization: Bearer [TOKEN]"

curl PUT \
  https://api-eu.app.lithium.com/bots/v3/registrations \
  --data @/path/to/payload.json \
  -H "Content-type: application/json; charset=utf-8" \
  -H "Authorization: Bearer [TOKEN]"

curl PUT \
  https://api-ap.app.lithium.com/bots/v3/registrations \
  --data @/path/to/payload.json \
  -H "Content-type: application/json; charset=utf-8" \
  -H "Authorization: Bearer [TOKEN]"

Retrieve existing bot registrations

You can also make a GET request retrieve registrations

• GET /bots/v3/registrations/network/{networkKey}/externalId/{externalId} - Retrieve all bot registrations registered with the Automation Framework for the specified source channel
• GET /bots/v3/registrations/network/{networkKey}/externalId/{externalId}/appId/{appId} - Retrieve registration details about an existing bot registered with the Automation Framework