Registration payload

Reference documentation for the registration JSON payload used with the Bot v3 API

This Registration payload is used to create and edit bot registrations with the Automation Framework.

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.

	"platform": "LITHIUM",
	"companyKey": "[COMPANY KEY]",
	"networkKey": "apple",
	"externalId": "117101b2-e66a-11e7-86ec-b1a405106b73",
	"appId": "my-abc-bot",
	"name": "My Apple Business Chat Bot",
	"callbackUrl": "<callback-url>",
	"credentials": {
		"type": "HMAC | BASIC_AUTH",
		"identity": "<username-or-hmac-key>",
		"secret": "<secret>"
	"contact": {
		"email": "<email address>"
	"avatarUrl": ""
 "hashKey": "<hashkey>",
 "appId": "<app-id>",
 "autoResponse": 0,
 "avatarS3Key": "<avatar-s3-key>",
 "avatarUrl": "<avatar-url>",
 "callbackUrl": "<callback-url>",
 "companyKey": "<company-key>",
 "contact": "{\"email\":\"[email protected]\"}",
 "createdTS": 1661514798312,
 "credentials": "{\"type\":\"HMAC\",\"identity\":\"user\",\"secret\":\"TpG_mEDBXygFhHmsExfX-A\",\"secretIV\":\"nwpQpYq/0jBouOZvXX8jgA==\"}",
 "externalId": "<external-id>",
 "internalBot": 0,
 "lastUpdatedTS": 1662631125128,
 "maintenanceMode": 0,
 "mode": "LIVE",
 "name": "Example Bot",
 "networkInstance": "",
 "networkKey": "lia",
 "platform": "LITHIUM",
 "version": 2

Registration payload fields





Supported values:

  • EXTERNAL (legacy value)

Use LITHIUM for all other networks.

Use EXTERNAL for legacy bots that are directly connected to Twitter or Facebook. This also includes Facebook Handover Protocol.

Note: EXTERNAL will support the legacy Bot API registration flow.


Required. Your company key. this is the Analytics API Company Key located in your Response app under Account Admin > General Settings > Analytics API Settings. If you do not see the key, contact your Care administrator. You might not have the appropriate permissions.


Required. The source channel for this registration.

Supported values:

  • apple
  • facebook
  • googlemessages
  • sms
  • twitter
  • wechat
  • whatsapp
  • brandmessenger (for current Khoros Brand Messenger)
  • instagram
  • lia (for Khoros Communities)


This is Required if you are using lia as your network. The value should be formatted as follows:

url/ with the trailing forward slash / at the end. For example:

“networkInstance”: “”,


Required. The external identifier of the page or account on the external network for which the bot is being registered.


Required. If platform LITHIUM, this is an internal identifier, determined by you, for your app. The ID is used by the Automation Framework. If you want to use the same bot for multiple networks, appId must be the same for each registration.

If platform EXTERNAL, this will be the app ID of the associated Facebook or Twitter app that is used by the bot. This is used as the unique identifier for the bot in Response.


Required. A user-friendly, customer-facing name, created by you, for the bot.


Required. An endpoint to call to relay the incoming message from Care to the bot.

Note: If using the Facebook Handover Protocol, enter a dummy value. This field is not used by the Facebook Handover Protocol, but is still required by the call.


Required. No default is set.

Supported values:

  • LIVE

When LIVE, all events are forwarded to the Bot Server via webhooks, and the bot can take any supported action. Only one LIVE bot can be supported on a specific network/externalId at one time.

When MAINTENANCE, no events are sent via webhooks. Any customer messages that arrive while in this mode are explicitly handed off to an AGENT, so that when the bot returns from MAINTENANCE mode, the bot will not start answering conversations already in progress.

When MONITORING, no responses are sent from the bot to the end-user. More information available in our Monitoring Bots guide.

Note: When mode is MAINTENANCE, you may still make API gateway requests, but you will be blocked from taking any bot action such as resolving a conversation, updating priority, etc...


Required. A credentials sub-object for passing authentication credentials to authenticate the bot webhook callback.

Fields include:

  • type - The authentication type: HMAC or BASIC_AUTH.
  • identity - the basic auth username or HMAC key. The username provided is used as the standard basic authentication header.
  • secret - the authentication secret. Required for basic authentication and HMAC.
"credentials": {        "type": "HMAC
BASIC_AUTH", "identity": "", "secret": "" }

Note: If using the Facebook Handover Protocol, enter a dummy value. This field is not used by the Facebook Handover Protocol, but is still required by the call.


Optional. A publicFilter object used to indicate what types of public content should be forwarded to the bot webhook. If this is left null, only private content will be generated.

Fields include:

  • includeTargeted - if set to true, then public messages that directly target the bot’s externalId are forwarded to the bot. This mainly applies to Twitter mentions.
  • includeSourceTagIds - a list of source tag IDs to match. Any incoming message with a source tag that matches one specified in the list is forwarded to the bot webhook.
"publicFilter": {  "includeTargeted": true,  "includeSourceTagIds": [    999, 1002  ]}
contactRequired. A contact subobject specifying contact information for the responsible party for a bot. Currently, only the email field is supported. "contact": { "email": "[email protected]" },
avatarUrlOptional. A URL for an image to use as the bot’s avatar for certain networks that support it (Khoros Messaging, for example).