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>",
    "mode": MAINTENANCE,
    "credentials": {
        "type": "HMAC | BASIC_AUTH",
        "identity": "<username-or-hmac-key>",
        "secret": "<secret>"
    },
    "contact": {
        "email": "<email address>"
    },
    "avatarUrl": "https://www.example.com/bot_avatar.jpg"
}

Registration payload fields

Field

Description

platform

Required.

Supported values:

  • LITHIUM
  • 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.

companyKey

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.

networkKey

Required. The source channel for this registration.

Supported values:

  • apple
  • facebook
  • googlemessages
  • sms
  • twitter
  • wechat
  • whatsapp
  • smooch (for Khoros Messaging)
  • instagram

externalId

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

appId

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.

name

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

callbackUrl

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.

mode

Required. No default is set.

Supported values:

  • LIVE
  • MAINTENANCE
  • MONITORING

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...

credentials

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": "<username-or-hmac-key>",
        "secret": "<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.

publicFilter

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
  ]
}

contact

Required. A contact subobject specifying contact information for the responsible party for a bot.

Currently, only the email field is supported.

"contact": {
    "email": "[email protected]"
},

avatarUrl

Optional. A URL for an image to use as the bot’s avatar for certain networks that support it (Khoros Messaging, for example).