x-bot-id
: (Required) The bot ID targeted by the request. This header is mandatory for all Runtime API requests.x-integration-id
: (Optional) The ID of the integration making the request. This header is included only if the request originates from an integration.x-bot-id
is provided. The action is performed directly on behalf of the bot.x-bot-id
and x-integration-id
are provided. The action is performed on behalf of an integration within the specified bot.userId
and conversationId
track the sender and the conversation context.
text
, the payload must be compatible with { text: string; }
. In other words, it can add type constraints (like new properties) to the payload, but it can’t remove them.
name
and pictureUrl
fields are optional and useful for UI or debugging purposes but aren’t required for bot functionality.
status
field shows its current processing state.
name
. Bots or integrations can define multiple state types under different names.
type
indicates what kind of entity the state belongs to. The integration
type is a misnomer and should be treated as a bot
type.
type
property indicates whether the tag is associated with a user, conversation, or message. It can be used later to filter or search user, conversation, or message objects based on their tags.
Unlike States, Tags are returned with the entity they’re linked to. States can be bigger, but must be fetched separately. Also, tags are always string, while states can be any JSON object with a schema defined in the integration or bot definition.