# Bot.AI.chat

Sends a chat message request to the bot AI.

```javascript
Bot.AI.chat(message, residentName[, options]);
```


:::note
The `instructions` and `maxResponseTokens` settings are hard-coded in user settings. They do not need to be explicitly created for user settings. Instead, these values should be fetched from `userSettings.instructions` and `userSettings.maxResponseTokens` and included in the configuration.

In case of an error, this function throws an error with a message.

:::

## Input

| Variable | Description |
|----------|-------------|
| message  | The chat message to send to the bot. |
| residentName | The name of the resident sending the message. |
| options  | *(optional)* Configuration directives for the AI engine. |

### Options Format

```javascript
{
  instructions?: string;
  // Previous message ID, if responding to a particular previous AI message of the bot
  parentMessageId?: string;
  // Maximum number of tokens to generate in response
  maxResponseTokens?: number;
  // Max number of response bytes (SL IM has a max limit of 1023 bytes)
  maxResponseBytes?: number;
}
```

## Output

| Variable | Description |
|----------|-------------|
| text     | The response text generated by the bot. |
| messageId | The ID of the response message. Can be specified as `parentMessageId` in future calls. |
| usage    | An object containing token usage details. |

### Usage example

```javascript
{
  // Number of tokens in a request (message + instructions + history)
  prompt_tokens: number;
  // Number of tokens in a response
  completion_tokens: number;
  // Total tokens used
  total_tokens: number;
  // Tokens left on SmartBots AI balance
  tokens_left: number;
}
```